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

CambioCliente de Volcengine existenteTokenLab
URL baseSu endpoint de Volcenginehttps://api.tokenlab.sh/
AutenticaciónFirma de solicitud AK/SKAuthorization: Bearer <TOKENLAB_API_KEY>
Transporte de tareasRutas REST oficiales /api/v3/contents/generations/tasksPreservado
Actions de material/validaciónParámetros de consulta Action y VersionPreservado
Cuerpo de la tareacontent[] al estilo VolcenginePreservado
Cuerpo del materialCampos en PascalCase como GroupId y ProjectNamePreservado
Resultado asíncronoCiclo de vida de tareas de VolcengineID 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 existenteEndpoint 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ónPOST /?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 rutaPropósito
POST /api/v3/contents/generations/tasksCrear una tarea de video
GET /api/v3/contents/generations/tasks/{id}Leer una tarea
GET /api/v3/contents/generations/tasksListar 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:

Reglas del cuerpo de la solicitud

  • content[] acepta elementos de tipo text, image_url, video_url, audio_url y draft_task.
  • Para image_url, omita role o utilice first_frame para imagen a video. Utilice last_frame junto con un primer fotograma, o reference_image para referencia a video.
  • Se puede utilizar un URI de material público como asset://asset-YYYYMMDDHHMMSS-xxxxx donde 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_after y safety_identifier. Los valores predeterminados dependen del modelo: generate_audio es false para modelos seedance-2.0 y true para seedance-2.5, y duration es 5 para modelos seedance-2.0 y -1 para seedance-2.5. Este formato REST acepta valores de resolution como 480p, 720p y 1080p (480p y 720p para seedance-2.5), pero no 4k, que solo acepta la API unificada /v1/videos/generations. seedance-2.5 rechaza seed, frames y camera_fixed.
  • callback_url acepta un endpoint HTTP(S) público. TokenLab envía el mismo cuerpo de tarea de consulta para queued, running, succeeded, failed y expired; solo succeeded y failed siguen 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:

  1. Crear sesión de validación visual
  2. Obtener resultado de validación visual

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

  1. Reemplace el host de la API con https://api.tokenlab.sh.
  2. Reemplace la firma AK/SK con una clave de API Bearer de TokenLab.
  3. 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.
  4. Mantenga el mismo ProjectName en todas las solicitudes relacionadas de material y verificación.
  5. Almacene los IDs de tarea, grupo y activo de TokenLab devueltos por estos endpoints.
  6. Verifique una respuesta de creación, sondeo, lista y error antes de mover el tráfico de producción.

En esta página