Resumen
La generación de video es asíncrona. Envías una solicitud, recibes unatask_id y un poll_url, y luego consultas periódicamente hasta obtener el resultado final.
Comportamiento de sondeo
Para el comportamiento de polling más fiable, usa exactamente elpoll_url que devuelve la respuesta de creación.
Si una respuesta de creación devuelve poll_url, llama exactamente a esa URL. Cuando apunte a /v1/tasks/{id}, trátala como el endpoint fijo canónico de estado.
Comportamiento de modelos y medios
La salida de audio depende del modelo. En TokenLab, las solicitudes de Veo 3 y Seedance activan el audio por defecto cuando se omiteoutput_audio. Cuando un modelo admite control de audio, usa output_audio para activarlo o desactivarlo explícitamente. Los alias outputAudio y generate_audio se aceptan por compatibilidad y deben coincidir con output_audio cuando se proporciona más de uno.
Para integraciones en producción, es mejor usar URLs https públicas para imágenes, videos y audio. Los modelos compatibles siguen aceptando URLs data:, pero los payloads base64 grandes son más difíciles de reintentar, inspeccionar y depurar.
Cuerpo de la solicitud
ID del modelo de video. Usa los IDs de modelo que muestra TokenLab como
veo3.1, wan-2.7, happyhorse-1.0, viduq3, pixverse-v6 o kling-3.0-video; elige text-to-video, image-to-video, reference-to-video u otras variantes con operation. Consulta la guia de video y Models API.PixVerse
- Modelo:
pixverse-c1,pixverse-v6,pixverse-v5.6 - Operaciones:
text-to-video,image-to-video,start-end-to-video,reference-to-video - Selector de audio:
output_audio,falsepor defecto
operation=video-extension.HappyHorse- Modelo:
happyhorse-1.0 - Operaciones:
text-to-video,image-to-video,reference-to-video,video-to-video - Selector de audio: No enviar
output_audio
Descripción en texto del video que quieres generar. Este campo es obligatorio para la mayoría de los modelos públicos de video.
Operación de video que se va a ejecutar. Los valores admitidos son
text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, audio-to-video y motion-control. TokenLab puede inferir la operación a partir de las entradas, pero en producción se recomienda enviarla de forma explícita.URL pública de la imagen inicial para flujos image-to-video. Para la compatibilidad más amplia entre modelos, conviene preferir
image_url.Imagen inline como URL
data: (por ejemplo, data:image/jpeg;base64,...). Los modelos compatibles la aceptan, pero image_url suele ser más robusta en producción.Imágenes de referencia para flujos con condicionamiento dedicado. La cantidad admitida depende del modelo. Para
seedance-2.0 y seedance-2.0-fast, TokenLab admite actualmente hasta 9 imágenes de referencia, además de hasta 3 videos de referencia y 3 audios de referencia. Para selección de modelo, límites 4K y notas de Mini, consulta la guía de modelos de video Seedance 2.0. Se recomiendan URLs públicas https; los modelos compatibles también aceptan URLs data:. Para grok-imagine-video, reference-to-video acepta hasta 7 referencias de imagen y duration está limitada a 10 segundos. grok-imagine-video-1.5-preview solo admite image-to-video y no acepta referencias de imagen.ID de material Seedance de TokenLab devuelto por Crear material o por la preparación automática de imágenes. Úsalo después de que el material esté
ACTIVE con modelos Seedance que puedan usar la biblioteca de materiales de TokenLab.Varios IDs de material Seedance de TokenLab. Comparten el límite de referencias de imagen de Seedance con
reference_images; el modelo seleccionado debe poder usar la biblioteca de materiales de TokenLab.Cuando el modelo Seedance seleccionado puede usar la biblioteca de materiales de TokenLab, TokenLab prepara los campos de imagen (
image, image_url, image_urls, reference_images, start_image, end_image) como materiales reutilizables antes de generar. Si la preparación no termina en 60 segundos, la API devuelve 409 seedance_material_preparing con auto_material_asset_ids; reintenta cuando esos materiales estén ACTIVE. Si el modelo seleccionado no puede usar la biblioteca de materiales, las entradas de imagen normales siguen el flujo de imagen habitual y los IDs de material explícitos fallan de forma segura con un error de disponibilidad de material.Campo opcional para modelos que distinguen entre referencias
asset y style.Definiciones de referencias de elementos de Kling 3.0. Solo se admiten con
kling-3.0-video en solicitudes condicionadas por imagen. Define 1-3 elementos; cada elemento incluye name, description opcional y element_input_urls con 2-4 URL de imágenes. Referencia cada elemento en prompt como @name. No combines kling_elements con output_audio=true; omite output_audio o ponlo en false para solicitudes con referencias de elementos.URL pública del video de origen. Requerida para flujos
video-to-video basados en URL de video y para motion-control; algunos flujos derivados usan task_id en su lugar.Entradas adicionales de video de referencia para modelos con condicionamiento multimodal. La cantidad admitida depende del modelo. Para
seedance-2.0 y seedance-2.0-fast, TokenLab admite actualmente hasta 3 videos de referencia.URL pública del audio para modelos que admiten
audio-to-video.Entradas adicionales de audio de referencia para modelos con condicionamiento multimodal. La cantidad admitida depende del modelo. Para
seedance-2.0 y seedance-2.0-fast, TokenLab admite actualmente hasta 3 audios de referencia.Identificador de tarea usado por algunos flujos de continuación, extensión o derivados.
Desplazamiento inicial específico del modelo para algunos flujos
video-extension.Multiplicador o número de repeticiones específico del modelo para algunos flujos
video-extension.Duración del video generado en segundos. Para modelos Seedance 1.5/2.0, omitir este campo usa
5; enviar -1 permite que el modelo elija dentro de su rango admitido, y la facturación se estima de forma conservadora hasta que finaliza la tarea.Alias compatible de
duration. Si envías seconds y duration, ambos deben ser idénticos. Para Seedance, seconds=-1 tiene el mismo significado de duración automática que duration=-1.Relación de aspecto canónica, por ejemplo
adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 o 21:9. Seedance usa adaptive por defecto cuando se omite.Resolución de salida dependiente del modelo. Seedance usa
720p por defecto; seedance-2.0 admite 480p, 720p, 1080p y 4k, mientras que seedance-2.0-fast y seedance-2.0-mini se limitan a 480p y 720p.Control canónico de salida de audio dependiente del modelo. Veo 3 y Seedance usan
true por defecto cuando se omite. kling-3.0-video acepta este selector en solicitudes sin referencias de elementos y, cuando se omite, genera salida sin audio. No combines output_audio=true con kling_elements.Indicador del flujo Draft de Seedance 1.5 Pro. Usa
draft=true con modelos Seedance que admiten tareas draft. No lo envíes junto con draft_task_id.ID de tarea draft de Seedance 1.5 Pro para promoción. Envía el ID de una tarea draft anterior para crear el video final; no es un campo genérico de video.
Alias compatible de
aspect_ratio. Si se envían ratio y aspect_ratio, deben ser idénticos.Alias compatible de
output_audio. Si aparecen generate_audio, output_audio y outputAudio, todos los valores deben coincidir.Tiempo opcional de expiración de ejecución en segundos para modelos de video compatibles. Seedance usa
172800 segundos por defecto cuando se omite.Prioridad opcional de la tarea de
0 a 9 para modelos de video compatibles. No combines priority con service_tier=flex.Identificador opcional de seguridad del usuario final para modelos de video compatibles. Si se omite en Seedance, TokenLab usa
user cuando está disponible.default se acepta como no-op compatible para modelos Seedance 2.0. flex solo se permite cuando el modelo seleccionado lo admite.Recuento opcional de fotogramas para modelos de video compatibles. Los modelos Seedance 2.0 y Seedance 1.5 Pro no admiten este campo.
Selector opcional de cámara fija para modelos de video compatibles. Los modelos Seedance 2.0 no admiten este campo.
Fotogramas por segundo (1-120). Solo surte efecto en los modelos que exponen FPS.
Elementos que deben evitarse en el video generado.
Semilla aleatoria para generación reproducible. Seedance usa
-1 como semilla aleatoria cuando se omite.Intensidad de adherencia al prompt (0-20) en los modelos que exponen este control.
Intensidad del movimiento (0-1) en los modelos que exponen este control.
URL de la imagen del primer fotograma, o entrada compatible, para
start-end-to-video.URL de la imagen del último fotograma, o entrada compatible, para
start-end-to-video.Nivel de tamaño específico del modelo para modelos de video compatibles.
Control opcional de marca de agua para modelos que lo exponen. Seedance usa
false por defecto cuando se omite.Selector de efecto específico del modelo para algunos flujos especializados de edición o efectos.
Identificador único del usuario final. Para Seedance, TokenLab también usa este valor como
safety_identifier cuando ese campo se omite.Notas de compatibilidad
- Los campos públicos canónicos están en snake_case:
reference_images,reference_image_typeyoutput_audio. - Los campos públicos canónicos siguen usando snake_case:
aspect_ratio,output_audio,reference_imagesyreference_image_type. - Por compatibilidad, TokenLab también acepta
ratio,generate_audio,outputAudio,seconds,referenceImagesyreferenceImageType. - Si se envían campos canónicos y alias al mismo tiempo, sus valores deben coincidir; los alias en conflicto se rechazan antes de crear la tarea.
Buenas prácticas para entradas de medios
- Para
image_url,reference_images,video_urlyaudio_url, es preferible usar URLshttpspúblicas. - Siempre que sea posible, evita mezclar base64 inline y URLs remotas en la misma solicitud.
- Asegúrate de que las URLs multimedia remotas sigan siendo válidas durante los reintentos y la creación asíncrona de tareas.
Parámetros de Seedance
Para modelos Seedance 1.5/2.0, el endpoint unificado sigue los nombres de campos de TokenLab y acepta los alias compatiblesseconds, ratio y generate_audio. Si se omiten los selectores de Seedance, se usan estos valores por defecto: duration=5, resolution=720p, aspect_ratio=adaptive, output_audio=true, watermark=false, return_last_frame=false, execution_expires_after=172800, priority=0 y seed=-1.
duration=-1 o seconds=-1 permite que Seedance elija la duración de salida dentro del rango admitido por el modelo. TokenLab estima el coste de forma conservadora antes de que finalice la tarea y luego liquida según el uso de la tarea completada cuando está disponible. service_tier=default se acepta como no-op compatible para Seedance 2.0; service_tier=flex, frames y camera_fixed se rechazan cuando el modelo seleccionado no los admite.
Ejemplo de Seedance
cURL
Respuesta
Identificador canónico de la tarea asíncrona. Cuando
id y task_id estén presentes a la vez, considéralos la misma tarea.Identificador único de la tarea para hacer polling.
URL de polling recomendada para esta tarea. Usa exactamente esta ruta al consultar el estado.
ID de transacción de facturación de TokenLab cuando la liquidación ya terminó. Es el identificador de dashboard/contabilidad y es distinto del
id / task_id asíncrono.Estado inicial:
pending.Marca de tiempo Unix de creación de la tarea.
Modelo utilizado.
Imagen a video
Kling 3.0 Elements
Usakling_elements con kling-3.0-video cuando necesites referencias de elementos. Proporciona una solicitud condicionada por imagen (image_url, image_urls, start_image o end_image) y referencia cada elemento en el prompt con @name. No combines kling_elements con output_audio=true; omite output_audio o ponlo en false para solicitudes con referencias de elementos.
Referencia a video
Usaoperation=reference-to-video cuando el modelo admita condicionamiento de referencia dedicado. En los detalhes do modelo de TokenLab, las referencias de imagen se envían mediante reference_images, mientras que los videos y audios de referencia multimodales se envían mediante video_urls y audio_urls. Para seedance-2.0 y seedance-2.0-fast, TokenLab admite actualmente hasta 9 imágenes de referencia, además de hasta 3 videos de referencia y 3 audios de referencia. Para selección de modelo, límites 4K y notas de Mini, consulta la guía de modelos de video Seedance 2.0. duration solo controla la duración del resultado generado; no fija un límite independiente para la duración del video de referencia de entrada. Para grok-imagine-video, reference-to-video acepta hasta 7 referencias de imagen (reference_images o image_urls) y duration está limitada a 10 segundos. No combines referencias de imagen con entradas de primer fotograma image_url / image. grok-imagine-video-1.5-preview solo admite image-to-video.
Control de fotograma inicial y final
Usastart_image y end_image para controlar el primer y el último fotograma.
Video a video
Para video-to-video congrok-imagine-video, envía una URL HTTPS pública .mp4 en video_url. TokenLab la traduce al cuerpo REST de xAI video.url. Puedes definir resolution como 480p o 720p; duration y aspect_ratio no se aceptan en ese flujo de edición.
Cuando un modelo acepta un video existente como entrada principal, usa operation=video-to-video.
Control de movimiento
Cuando un modelo necesita tanto una imagen del sujeto como un video de referencia de movimiento, usaoperation=motion-control. TokenLab normaliza la forma pública image_url + video_url al formato motion-control de ese modelo.
Descubrimiento de modelos
El inventario público de video y las operaciones admitidas cambian con el tiempo. Usa la Models API como referencia actual antes de implementar un flujo específico de un modelo:audio-to-video y video-extension dependen del modelo; confirma allí la disponibilidad actual en lugar de depender de ejemplos estáticos de esta página.