Biblioteca privada de personajes.

Comparación: CloudCLI y BytePlus

Coinciden en el flujo de trabajo y en las diez operaciones de la biblioteca. La revisión distingue diferencias de presentación, aclaraciones del servicio y ajustes de los ejemplos.

La comparación se refiere a las páginas enlazadas, consultadas en la misma fecha. Los bloques de código de esta versión son ejemplos propios.

Tu biblioteca de personajes virtuales

1. 01Crea un grupo
2. 02Añade referencias
3. 03Comprueba el estado
4. 04Genera tu escena

Biblioteca privada de retratos virtuales · documento original ↗

Ver el esquema de la guía de referencia

El gráfico conserva los nombres de la interfaz original. Los pasos están explicados en español en esta página.

Grupos, recursos e identificadores

GroupType: AIGC corresponde al grupo de personajes virtuales. No equivale a AssetType, que indica el formato de recurso.

Ejemplo de organización: el grupo «Luna» contiene «rostro frontal», «vestuario azul» y «voz tranquila». Cada archivo conserva un identificador diferente.

Preparar las referencias visuales

Utiliza versiones coherentes del mismo personaje. Nombra cada archivo por su función para distinguir fácilmente apariencia, vestuario y voz.

Recomendaciones de retratos de BytePlus ↗

Empezar desde la consola

Una organización útil: un grupo por personaje y nombres que distingan la vista, el vestuario y la versión. Por ejemplo, «Luna / frontal / chaqueta azul / v2».

Abrir Model Playground ↗

En la interfaz original, estas opciones aparecen como My assets, Virtual Portrait y Manage assets.

Archivos admitidos

Formatos y parámetros de CreateAsset ↗

Crear el grupo y añadir recursos

Ejemplo propio: cuerpo de CreateAssetGroup

{
  "Name": "Luna — temporada 1",
  "Description": "Referencias del personaje virtual Luna",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

Crear un grupo · CreateAssetGroup ↗

Ejemplo propio: cuerpo de CreateAsset

{
  "GroupId": "REEMPLAZA_POR_EL_ID_DEL_GRUPO",
  "URL": "https://tu-dominio.example/luna-frontal.png",
  "Name": "Luna frontal v2",
  "AssetType": "Image",
  "ProjectName": "default"
}

Son cuerpos de solicitud, no peticiones listas para ejecutar. Sustituye los valores de ejemplo y envíalos con el SDK de BytePlus, que firma las llamadas AK/SK. Mantén las credenciales en tu servidor.

Moderation.Strategy admite Default y Skip. El segundo omite parte del prefiltrado, no todas las comprobaciones. Los ejemplos de esta guía conservan la revisión predeterminada.

Esperar a que el recurso esté listo

Lógica de consulta

# Pseudocódigo: adapta consultar_recurso a tu SDK.
limite = ahora() + 600
while ahora() < limite:
    recurso = consultar_recurso(id_recurso, proyecto)
    if recurso["Status"] == "Active":
        return id_recurso
    if recurso["Status"] == "Failed":
        raise Error(recurso.get("Error"))
    esperar(5)
raise Error("El recurso sigue procesándose; consulta de nuevo más tarde")

Consultar estado y errores · GetAsset ↗

Usar el personaje en un vídeo

Ejemplo propio de prompt

Ejemplo propio de contenido de la solicitud

{
  "model": "REEMPLAZA_POR_TU_MODELO_O_ENDPOINT",
  "content": [
    {"type": "text", "text": "El personaje de la Imagen 1 saluda a cámara y dice: Hola, soy Luna."},
    {
      "type": "image_url",
      "image_url": {"url": "asset://REEMPLAZA_POR_EL_ID_ACTIVO"},
      "role": "reference_image"
    }
  ],
  "generate_audio": true,
  "duration": 5,
  "ratio": "16:9",
  "watermark": true
}

Sustituye ambos identificadores y usa un endpoint del mismo proyecto que el recurso. El ejemplo es una plantilla editable; esta web no ejecuta generaciones ni solicita claves.

Uso de referencias de personajes en la generación ↗

import os
import time
from arkruntime import Ark

# Instala el SDK con: pip install arkruntime
# Define ARK_API_KEY, ARK_MODEL_ID y ARK_ASSET_ID en tu entorno.
# ARK_ASSET_ID debe contener el ID de un recurso en estado Active.
cliente = Ark(
    base_url="https://ark.ap-southeast.bytepluses.com/api/v3",
    api_key=os.environ["ARK_API_KEY"],
)
recurso_id = os.environ["ARK_ASSET_ID"]
tarea = cliente.content_generation.tasks.create(
    model=os.environ["ARK_MODEL_ID"],
    content=[
        {"type": "text", "text": "Plano medio horizontal del personaje de la Imagen 1. Saluda a cámara y dice en español: Hola, soy Luna. Luz suave y fondo de taller."},
        {"type": "image_url", "role": "reference_image",
         "image_url": {"url": f"asset://{recurso_id}"}},
    ],
    duration=5,
    ratio="16:9",
    generate_audio=True,
    watermark=True,
)
print("Tarea creada:", tarea.id)
limite = time.monotonic() + 600
while time.monotonic() < limite:
    resultado = cliente.content_generation.tasks.get(task_id=tarea.id)
    if resultado.status == "succeeded":
        print("Vídeo terminado:", resultado.content)
        break
    if resultado.status == "failed":
        raise RuntimeError(f"La generación ha fallado: {resultado.error}")
    print("Estado:", resultado.status)
    time.sleep(10)
else:
    raise TimeoutError(f"La tarea sigue pendiente. Conserva su ID: {tarea.id}")

curl --fail-with-body --request POST \
  "https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer ${ARK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @solicitud-personaje.json

Ejemplo con cinco imágenes y una voz

Estas son las cinco referencias visuales de la guía. La voz es una referencia de audio independiente y conserva su propia numeración.

Prompt propio para explicar la asignación. Las imágenes proceden de la guía enlazada; los identificadores reales deben obtenerse desde tu biblioteca.

Buscar recursos y recorrer resultados

{
  "Filter": {"GroupType": "AIGC", "Statuses": ["Active"], "Name": "Luna"},
  "MaxResults": 20,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}

Buscar referencias · ListAssets ↗

Buscar grupos · ListAssetGroups ↗

Ejemplo en Go: crear y consultar

Un único programa permite ejecutar los cinco pasos de creación y consulta de la guía. Guarda el cuerpo JSON de cada operación en un archivo distinto. Configura las claves AK/SK mediante las variables de entorno indicadas en el código.

package main

import (
    "encoding/json"
    "fmt"
    "os"

    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/credentials"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/session"
    "github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/universal"
)

func ejecutar() error {
    ak, sk := os.Getenv("BYTEPLUS_ACCESS_KEY"), os.Getenv("BYTEPLUS_SECRET_KEY")
    if ak == "" || sk == "" {
        return fmt.Errorf("configura BYTEPLUS_ACCESS_KEY y BYTEPLUS_SECRET_KEY")
    }
    if len(os.Args) != 3 {
        return fmt.Errorf("uso: go run . ACCION cuerpo.json")
    }
    // Este ejemplo se limita a creación y consulta.
    permitidas := map[string]bool{
        "CreateAssetGroup": true, "CreateAsset": true,
        "GetAsset": true, "ListAssets": true, "ListAssetGroups": true,
    }
    accion := os.Args[1]
    if !permitidas[accion] {
        return fmt.Errorf("acción no incluida en este ejemplo: %s", accion)
    }
    contenido, err := os.ReadFile(os.Args[2])
    if err != nil { return err }
    var cuerpo map[string]any
    if err = json.Unmarshal(contenido, &cuerpo); err != nil { return err }

    configuracion := byteplus.NewConfig().
        WithRegion("ap-southeast-1").
        WithCredentials(credentials.NewStaticCredentials(ak, sk, ""))
    sesion, err := session.NewSession(configuracion)
    if err != nil { return err }
    resultado, err := universal.New(sesion).DoCall(universal.RequestUniversal{
        ServiceName: "ark", Action: accion, Version: "2024-01-01",
        HttpMethod: universal.POST, ContentType: universal.ApplicationJSON,
    }, &cuerpo)
    if err != nil { return err }
    salida, err := json.MarshalIndent(resultado, "", "  ")
    if err != nil { return err }
    fmt.Println(string(salida))
    return nil
}

func main() {
    if err := ejecutar(); err != nil {
        fmt.Fprintln(os.Stderr, "La solicitud ha fallado:", err)
        os.Exit(1)
    }
}

Preparación

# En una carpeta nueva para el ejemplo:
go mod init ejemplo-personajes
go get github.com/byteplus-sdk/byteplus-go-sdk-v2
# Guarda el programa anterior como main.go.
# Configura las variables BYTEPLUS_ACCESS_KEY y BYTEPLUS_SECRET_KEY.
go run . CreateAssetGroup grupo.json

Después, reutiliza el programa con CreateAsset, GetAsset, ListAssets o ListAssetGroups. Cada llamada requiere el cuerpo correspondiente.

Cuerpo de GetAsset

{
  "Id": "REEMPLAZA_POR_EL_ID_DEL_RECURSO",
  "ProjectName": "default"
}

Cuerpo de ListAssetGroups

{
  "Filter": {
    "GroupType": "AIGC",
    "Name": "Luna"
  },
  "MaxResults": 20,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}

Autenticación y creación de grupos ↗

Consulta de recursos ↗

Consulta de grupos ↗

Consultar, actualizar y eliminar

Antes de limpiar una biblioteca, relaciona los identificadores con tus escenas y proyectos. Conserva los archivos originales y comprueba qué referencias siguen utilizándose.

Permisos IAM

La guía incluye una política de administración de recursos. Es un ejemplo amplio: permite las acciones cuyo nombre coincide con ark:*Asset*, incluidas las de eliminación, sobre todos los recursos.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ark:*Asset*"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}

En IAM, crea una política, asígnala al usuario o grupo correspondiente y limita el proyecto cuando proceda. Para tareas de consulta, utiliza una política que conceda únicamente las operaciones necesarias.

Gestión de permisos en la documentación original ↗

Límites de solicitudes

Distribuye las consultas en el tiempo y aplica espera entre reintentos. Subir un recurso y generar un vídeo son operaciones distintas: espera a que la referencia esté preparada antes de enviar la escena.

Cuotas de la biblioteca privada ↗

Resolver los problemas habituales