Crear tarea (Compatible con Volc)

Descripción generalCopy Anchor Link

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

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

Autenticación y endpointsCopy Anchor Link

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

Reglas de contenidoCopy Anchor Link

• 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.
• role: "reference_image", reference_video y reference_audio se utilizan como referencias.
• 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.
• Se rechazan los campos de nivel superior material_asset_id y material_asset_ids. Coloque el URI de material TokenLab en image_url.url. priority solo se admite para Seedance 2.5.

Notas sobre los parámetrosCopy Anchor Link

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

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

• ratio acepta 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 o adaptive.
• watermark, return_last_frame, seed, execution_expires_after y safety_identifier se aceptan cuando son válidos para el modelo seleccionado.
• callback_url puede apuntar a un endpoint HTTP(S) público.

Entrega de callbackCopy Anchor Link

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 un plazo de cinco segundos se reintentará 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 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ágenesCopy Anchor Link

Las URL públicas de imágenes HTTP(S) y las URL data compatibles se usan tal como se proporcionan, sin guardarlas automáticamente como materiales reutilizables. Las referencias explícitas asset://asset-... usan materiales TokenLab existentes. Antes de generar se comprueban la propiedad y la disponibilidad. Si un material sigue preparándose, espere hasta que esté listo y reintente. Si la creación falla, consulte error.code y error.message.

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ónCopy Anchor Link

{
  "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 duplicadasCopy Anchor Link

Envíe una Idempotency-Key única 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 la tarea original se creó, TokenLab devuelve el mismo ID cgt-... y añade Idempotency-Replayed: true.
• Si la solicitud original todavía se está registrando, TokenLab devuelve 409 IdempotencyRequestInProgress. Reintente más tarde con la misma clave y el mismo cuerpo.
• Reutilizar la clave con un cuerpo diferente devuelve 409 IdempotencyConflict y nunca crea una segunda tarea.

La idempotencia se aplica a la ruta de creación REST v3 oficial. No cambia la forma de la respuesta JSON y no se infiere de X-Request-ID ni de cuerpos de solicitud idénticos sin una clave.

EjemploCopy Anchor Link

Creación RESTCopy Anchor Link

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": "doubao-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 oficial content[] 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"}
  }
]

Siguiente pasoCopy Anchor Link

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": "doubao-seedance-2-0-260128",    "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"}