Video y recursos
Crear tarea (Compatible con Volc)
Cree una tarea de Seedance con la API compatible con Volc.
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"sinrole, o conrole: "first_frame", se trata como el primer fotograma.role: "last_frame"debe estar emparejado con un primer fotograma.type: "video_url"requiererole: "reference_video", ytype: "audio_url"requiererole: "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, 1draft_task). Seedance 2.5 acepta hasta 51 (1 de texto, 30 de imagen, 10 de video, 10 de audio, 1draft_task). image_url.urlacepta una URL de imagen pública o un URI de material comoasset://asset-YYYYMMDDHHMMSS-xxxxx. Elroledetermina 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_idymaterial_asset_ids, devuelve400 UnsupportedParameter. Coloque un URI de material de TokenLab enimage_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ámetro | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (predeterminado: 5) | 4–30 / -1 (predeterminado: -1) |
resolution | 480p, 720p, 1080p (predeterminado: 720p) | 480p, 720p (predeterminado: 720p) |
generate_audio | boolean (predeterminado: false) | boolean (predeterminado: true) |
priority | No compatible | integer: 0–9 |
seed | integer: -1–4294967295 (predeterminado: -1) | No compatible |
execution_expires_after | 3600–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.
ratioacepta16:9,4:3,1:1,3:4,9:16,21:9oadaptive(predeterminado:adaptive).watermarkyreturn_last_frameson booleanos (predeterminado:false).safety_identifieres una cadena de hasta 64 caracteres.service_tieracepta solodefault;flexdevuelve400 UnsupportedParameter.toolsacepta como máximo un elemento,{"type": "web_search"}.draft: true,framesycamera_fixedno son compatibles.camera_fixed: falsese acepta solo para Seedance 2.0.callback_urlpuede 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ñadeIdempotency-Replayed: true. - Reutilizar la clave con un cuerpo diferente devuelve
409con el códigoidempotency_conflicty 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 Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Encabezados
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"
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.
1 <= length <= 255Cuerpo de la solicitud
application/json
Respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json