Video y recursos

Crear tarea (Compatible con Volc)

Cree una tarea de Seedance con la API compatible con Volc.

POST
/api/v3/contents/generations/tasks

Descripción general

Los clientes existentes de Seedance al estilo Volc pueden usar TokenLab cambiando la dirección de la API y la clave.

Los ejemplos utilizan Seedance 2.0. Este endpoint también admite Seedance 2.5 con las diferencias específicas del modelo que se indican a continuación. Los ejemplos de URI de material reutilizable de TokenLab en esta página se aplican a Seedance 2.0.

Consulte también Modelos de video de Seedance 2.0 y Generación de video.

Autenticación y endpoints

  • Utilice Authorization: Bearer <TOKENLAB_API_KEY>.
  • No se acepta la firma AK/SK de Volc. Las solicitudes deben incluir una clave Bearer de TokenLab.
  • Utilice la ruta de tarea oficial: POST /api/v3/contents/generations/tasks.

Reglas de contenido

  • type: "text" es el texto del prompt.
  • type: "image_url" sin role, o con role: "first_frame", se trata como el primer fotograma.
  • role: "last_frame" debe estar emparejado con un primer fotograma.
  • type: "video_url" requiere role: "reference_video", y type: "audio_url" requiere role: "reference_audio". role: "reference_image" marca una imagen de referencia.
  • Límites de elementos: Seedance 2.0 acepta hasta 16 elementos de content (1 de texto, 9 de imagen, 3 de video, 3 de audio, 1 draft_task). Seedance 2.5 acepta hasta 51 (1 de texto, 30 de imagen, 10 de video, 10 de audio, 1 draft_task).
  • image_url.url acepta una URL de imagen pública o un URI de material como asset://asset-YYYYMMDDHHMMSS-xxxxx. El role determina si ese material es un primer fotograma, un último fotograma o una imagen de referencia.
  • No mezcle entradas de primer/último fotograma con medios de referencia en una misma solicitud.
  • El cuerpo REST solo acepta los campos de esta página. Cualquier otro campo de nivel superior, incluidos material_asset_id y material_asset_ids, devuelve 400 UnsupportedParameter. Coloque un URI de material de TokenLab en image_url.url.

Notas sobre los parámetros

model acepta un ID de modelo de TokenLab como seedance-2.0 o seedance-2.5. Los clientes existentes pueden seguir enviando el ID de modelo de Volcengine que ya utilizan para estos modelos. La respuesta de get-task devuelve el valor model que usted envió. Un valor no reconocido devuelve 400 InvalidParameter.

duration es un número entero de segundos; -1 selecciona la duración automática. Los valores predeterminados y los límites difieren según el modelo:

ParámetroSeedance 2.0Seedance 2.5
duration4–15 / -1 (predeterminado: 5)4–30 / -1 (predeterminado: -1)
resolution480p, 720p, 1080p (predeterminado: 720p)480p, 720p (predeterminado: 720p)
generate_audioboolean (predeterminado: false)boolean (predeterminado: true)
priorityNo compatibleinteger: 0–9
seedinteger: -1–4294967295 (predeterminado: -1)No compatible
execution_expires_after3600–259200 segundos (predeterminado: 172800)3600–259200 segundos (predeterminado: 172800)

Para Seedance 2.5, las solicitudes de primer fotograma, primer/último fotograma, extensión de video y video a video requieren ratio: "adaptive"; video a video también requiere duration: -1. output_format acepta mp4 o mov solo para Seedance 2.5.

  • ratio acepta 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 o adaptive (predeterminado: adaptive).
  • watermark y return_last_frame son booleanos (predeterminado: false). safety_identifier es una cadena de hasta 64 caracteres.
  • service_tier acepta solo default; flex devuelve 400 UnsupportedParameter.
  • tools acepta como máximo un elemento, {"type": "web_search"}.
  • draft: true, frames y camera_fixed no son compatibles. camera_fixed: false se acepta solo para Seedance 2.0.
  • callback_url puede apuntar a un endpoint HTTP(S) público de hasta 2048 caracteres.

Entrega de callback

Cuando callback_url está presente, TokenLab envía un POST HTTP cuando cambia el estado de la tarea. Los estados de callback son queued, running, succeeded, failed y expired. El cuerpo JSON coincide con la respuesta de get-task.

Una respuesta 2xx confirma la entrega. Para succeeded y failed, una entrega que no se realice correctamente en cinco segundos se reintenta hasta tres veces. El callback solo tiene el encabezado de contenido JSON estándar y no tiene encabezados de entrega específicos de TokenLab. No se siguen las redirecciones y se rechazan los destinos de red privados o reservados.

Guarde el ID de la tarea. Si no se entrega un callback, aún puede recuperar el resultado con el endpoint get-task.

Preparación de imágenes

Las URL de imágenes HTTP(S) públicas y las URL de datos compatibles se utilizan tal como se suministran; no se guardan automáticamente como materiales reutilizables. Las referencias explícitas asset://asset-... utilizan materiales existentes de TokenLab. TokenLab verifica la propiedad y la disponibilidad antes de la generación. Si un material referenciado aún se está preparando, espere hasta que esté listo y vuelva a intentarlo; inspeccione error.code y error.message cuando falle la creación.

Para materiales existentes, utilice el ID público asset-YYYYMMDDHHMMSS-xxxxx en lugar de un ID de activo original devuelto por otro sistema. TokenLab verifica la propiedad del material antes de la generación.

Respuesta de creación

{
  "id": "cgt-20260102030405-a1b2c"
}

La respuesta de creación contiene solo el ID de la tarea. Guárdelo para poder recuperar el estado y los resultados en cualquier momento.

Evitar tareas duplicadas

Envíe un Idempotency-Key único (de 1 a 255 caracteres, sin saltos de línea) con las solicitudes de creación. Si la conexión se cierra antes de que llegue la respuesta, vuelva a intentarlo con la misma clave API, clave de idempotencia y cuerpo de solicitud:

  • Si se creó la tarea original, TokenLab devuelve el mismo ID cgt-... y añade Idempotency-Replayed: true.
  • Reutilizar la clave con un cuerpo diferente devuelve 409 con el código idempotency_conflict y nunca crea una segunda tarea.
  • Una clave que tenga más de 255 caracteres o contenga saltos de línea devuelve 400 InvalidParameter.

La clave no cambia la forma de la respuesta JSON. TokenLab no infiere duplicados a partir de X-Request-ID ni de cuerpos de solicitud idénticos sin una clave.

Ejemplo

Creación REST

curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

Para materiales existentes, coloque cada URI en el elemento content[] oficial y declare su rol:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

Errores

Los errores REST utilizan {"error": {"code", "message", "param", "type"}}. Los problemas de solicitud devuelven 400 con InvalidParameter o UnsupportedParameter, y una clave Bearer faltante devuelve 401 AuthenticationError. Los errores de la generación de video, como saldo insuficiente (402) o un límite de tasa (429), mantienen su estado HTTP.

Las mismas operaciones también están disponibles como las Acciones CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks y DeleteContentsGenerationsTasks en POST /api/v3?Version=2024-01-01. Las nuevas integraciones deben utilizar las rutas REST anteriores.

Siguiente paso

Utilice el ID cgt-... devuelto con Obtener tarea (Compatible con Volc) hasta que la tarea alcance un estado terminal.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2.0",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'
{  "id": "string"}

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Clave generada por el cliente para la creación de tareas REST idempotentes, de 1 a 255 caracteres sin saltos de línea. Bajo la misma credencial de API de TokenLab, reutilizar la misma clave con el mismo cuerpo JSON devuelve el ID de tarea cgt original; reutilizarla con un cuerpo diferente devuelve 409 con el código idempotency_conflict. Una clave demasiado larga o que contenga saltos de línea devuelve 400. Mantenga la credencial, la clave y el cuerpo de la solicitud sin cambios al reintentar después de un tiempo de espera o desconexión.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json