Guías de medios
Migrar Seedance desde Volcengine
Mantenga su formato de solicitud de Volcengine y cambie Seedance a TokenLab
Si su aplicación ya utiliza la API Seedance de Volcengine, puede mantener sus rutas REST, el cuerpo content[], los campos de respuesta, las devoluciones de llamada (callbacks) y las Actions de material en PascalCase. Cambie el host de la API y reemplace la firma AK/SK con una clave de API de TokenLab.
Qué cambia
| Cambio | Cliente de Volcengine existente | TokenLab |
|---|---|---|
| URL base | Su endpoint de Volcengine | https://api.tokenlab.sh/ |
| Autenticación | Firma de solicitud AK/SK | Authorization: Bearer <TOKENLAB_API_KEY> |
| Transporte de tareas | Rutas REST oficiales /api/v3/contents/generations/tasks | Preservado |
| Actions de material/validación | Parámetros de consulta Action y Version | Preservado |
| Cuerpo de la tarea | content[] al estilo Volcengine | Preservado |
| Cuerpo del material | Campos en PascalCase como GroupId y ProjectName | Preservado |
| Resultado asíncrono | Ciclo de vida de tareas de Volcengine | ID de tarea cgt-... de TokenLab con sondeo y callback opcional |
Las solicitudes firmadas solo con AK/SK devuelven 401 AuthenticationError. Cada solicitud a TokenLab debe incluir Authorization: Bearer <TOKENLAB_API_KEY>.
Elegir un endpoint
| Cliente existente | Endpoint de TokenLab |
|---|---|
| Cliente de tareas REST de Volcengine | /api/v3/contents/generations/tasks y sus rutas de tarea |
| Cliente de Action de material o validación | POST /?Action=...&Version=2024-01-01 o POST /api/v3?Action=...&Version=2024-01-01 |
Para tareas de video, mantenga el método REST, la ruta y el cuerpo JSON existentes. Las solicitudes de material y verificación continúan utilizando los parámetros de consulta Action y Version. El endpoint de Action también acepta las Actions de tarea CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks y DeleteContentsGenerationsTasks; utilice las rutas REST para el trabajo nuevo.
Rutas de tareas oficiales
| Método y ruta | Propósito |
|---|---|
POST /api/v3/contents/generations/tasks | Crear una tarea de video |
GET /api/v3/contents/generations/tasks/{id} | Leer una tarea |
GET /api/v3/contents/generations/tasks | Listar tareas |
DELETE /api/v3/contents/generations/tasks/{id} | Cancelar una tarea que aún está en cola. Una tarea que ha comenzado devuelve 409 task_not_cancellable |
Los clientes REST pueden usar estas referencias equivalentes:
- Crear tarea (Compatible con Volc)
- Obtener tarea (Compatible con Volc)
- Listar tareas (Compatible con Volc)
- Cancelar tarea (Compatible con Volc)
Reglas del cuerpo de la solicitud
content[]acepta elementos de tipotext,image_url,video_url,audio_urlydraft_task.- Para
image_url, omitaroleo utilicefirst_framepara imagen a video. Utilicelast_framejunto con un primer fotograma, oreference_imagepara referencia a video. - Se puede utilizar un URI de material público como
asset://asset-YYYYMMDDHHMMSS-xxxxxdonde el flujo de trabajo de Seedance seleccionado acepte ese rol de medio. - El cuerpo REST acepta solo campos oficiales, incluyendo
model,content,ratio,duration,resolution,generate_audio,watermark,return_last_frame,seed,execution_expires_afterysafety_identifier. Los valores predeterminados dependen del modelo:generate_audioesfalsepara modelosseedance-2.0ytrueparaseedance-2.5, ydurationes5para modelosseedance-2.0y-1paraseedance-2.5. Este formato REST acepta valores deresolutioncomo480p,720py1080p(480py720pparaseedance-2.5), pero no4k, que solo acepta la API unificada/v1/videos/generations.seedance-2.5rechazaseed,framesycamera_fixed. callback_urlacepta un endpoint HTTP(S) público. TokenLab envía el mismo cuerpo de tarea de consulta paraqueued,running,succeeded,failedyexpired; solosucceededyfailedsiguen el comportamiento oficial: un tiempo de espera de cinco segundos y un reintento cuando su endpoint no reconoce la notificación.
Ejemplo mínimo de 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.5",
"content": [
{"type":"text","text":"A cinematic product reveal"},
{"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
],
"ratio": "16:9",
"duration": 5,
"resolution": "720p"
}'Almacene el ID cgt-... devuelto. Realice sondeos hasta que el status sea succeeded, failed, cancelled o expired; no trate la respuesta de creación como un video completado. Si proporciona callback_url, permita notificaciones repetidas de succeeded o failed y mantenga el sondeo como una ruta de recuperación.
Mantenga separados los tipos v1 y v3
No reutilice una estructura de respuesta de /v1/tasks/{id} para este endpoint. La API unificada v1 reporta pending, processing, completed y failed; la API v3 compatible con Volc reporta queued, running, succeeded, failed, cancelled y expired. La respuesta oficial v3 también representa duration como una cadena JSON y omite error en tareas que no han fallado.
Para una recuperación segura después de un tiempo de espera de creación o desconexión, añada un Idempotency-Key único a la solicitud de creación REST. Reintentar el mismo cuerpo con la misma clave devuelve el ID cgt-... original; la misma clave con un cuerpo diferente devuelve 409.
Materiales y verificación de persona real
El mismo endpoint de Action también admite las 10 operaciones de material y grupo de materiales. Consulte Material Actions (Compatible con Volc) para conocer sus cuerpos exactos en PascalCase, filtros, paginación, sobre de respuesta y URLs de material de 12 horas.
Los materiales de persona real añaden dos Actions antes de la carga:
La segunda Action devuelve el GroupId verificado. Utilice ese ID con CreateAsset; un cliente no puede crear un grupo LivenessFace directamente.
Lista de verificación de migración
- Reemplace el host de la API con
https://api.tokenlab.sh. - Reemplace la firma AK/SK con una clave de API Bearer de TokenLab.
- Mantenga el método, la ruta y el formato del cuerpo de la solicitud de tareas REST oficiales; mantenga Action y version solo para operaciones de material o validación.
- Mantenga el mismo
ProjectNameen todas las solicitudes relacionadas de material y verificación. - Almacene los IDs de tarea, grupo y activo de TokenLab devueltos por estos endpoints.
- Verifique una respuesta de creación, sondeo, lista y error antes de mover el tráfico de producción.