Crear video

Resumen

La generación de video es asíncrona. Envías una solicitud, recibes una task_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 el poll_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 omite output_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

string

predeterminado:"veo3.1"

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, false por defecto

En TokenLab, los modelos PixVerse anteriores no aceptan 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

string

requerido

Descripción en texto del video que quieres generar. Este campo es obligatorio para la mayoría de los modelos públicos de video.

string

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.

string

URL pública de la imagen inicial para flujos image-to-video. Para la compatibilidad más amplia entre modelos, conviene preferir image_url.

string

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.

array

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.

string

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.

array

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.

string

Campo opcional para modelos que distinguen entre referencias asset y style.

array

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.

string

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.

array

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.

string

URL pública del audio para modelos que admiten audio-to-video.

array

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.

string

Identificador de tarea usado por algunos flujos de continuación, extensión o derivados.

integer

Desplazamiento inicial específico del modelo para algunos flujos video-extension.

string

Multiplicador o número de repeticiones específico del modelo para algunos flujos video-extension.

integer

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.

integer

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.

string

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.

string

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.

boolean

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.

boolean

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.

string

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.

string

Alias compatible de aspect_ratio. Si se envían ratio y aspect_ratio, deben ser idénticos.

boolean

Alias compatible de output_audio. Si aparecen generate_audio, output_audio y outputAudio, todos los valores deben coincidir.

integer

Tiempo opcional de expiración de ejecución en segundos para modelos de video compatibles. Seedance usa 172800 segundos por defecto cuando se omite.

integer

Prioridad opcional de la tarea de 0 a 9 para modelos de video compatibles. No combines priority con service_tier=flex.

string

Identificador opcional de seguridad del usuario final para modelos de video compatibles. Si se omite en Seedance, TokenLab usa user cuando está disponible.

string

default se acepta como no-op compatible para modelos Seedance 2.0. flex solo se permite cuando el modelo seleccionado lo admite.

integer

Recuento opcional de fotogramas para modelos de video compatibles. Los modelos Seedance 2.0 y Seedance 1.5 Pro no admiten este campo.

boolean

Selector opcional de cámara fija para modelos de video compatibles. Los modelos Seedance 2.0 no admiten este campo.

integer

Fotogramas por segundo (1-120). Solo surte efecto en los modelos que exponen FPS.

string

Elementos que deben evitarse en el video generado.

integer

Semilla aleatoria para generación reproducible. Seedance usa -1 como semilla aleatoria cuando se omite.

number

Intensidad de adherencia al prompt (0-20) en los modelos que exponen este control.

number

Intensidad del movimiento (0-1) en los modelos que exponen este control.

string

URL de la imagen del primer fotograma, o entrada compatible, para start-end-to-video.

string

URL de la imagen del último fotograma, o entrada compatible, para start-end-to-video.

string

Nivel de tamaño específico del modelo para modelos de video compatibles.

boolean

Control opcional de marca de agua para modelos que lo exponen. Seedance usa false por defecto cuando se omite.

string

Selector de efecto específico del modelo para algunos flujos especializados de edición o efectos.

string

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_type y output_audio.
Los campos públicos canónicos siguen usando snake_case: aspect_ratio, output_audio, reference_images y reference_image_type.
Por compatibilidad, TokenLab también acepta ratio, generate_audio, outputAudio, seconds, referenceImages y referenceImageType.
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_url y audio_url, es preferible usar URLs https pú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 compatibles seconds, 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

curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

Respuesta

string

Identificador canónico de la tarea asíncrona. Cuando id y task_id estén presentes a la vez, considéralos la misma tarea.

string

Identificador único de la tarea para hacer polling.

string

URL de polling recomendada para esta tarea. Usa exactamente esta ruta al consultar el estado.

string

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.

string

Estado inicial: pending.

integer

Marca de tiempo Unix de creación de la tarea.

string

Modelo utilizado.

curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

Imagen a video

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9"
    }
)

Elementos de Kling 3.0

Usa kling_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.

response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

Referencia a video

Usa operation=reference-to-video cuando el modelo admita condicionamiento de referencia dedicado. En los detalles del 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.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

Control de fotograma inicial y final

Usa start_image y end_image para controlar el primer y el último fotograma.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "prompt": "Smooth transition from day to night",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }
)

Video a video

Para video-to-video con grok-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.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion.",
        "resolution": "720p"
    }
)

Control de movimiento

Cuando un modelo necesita tanto una imagen del sujeto como un video de referencia de movimiento, usa operation=motion-control. TokenLab normaliza la forma pública image_url + video_url al formato motion-control de ese modelo.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

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:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"

Lee la respuesta de detalle del modelo antes de depender de operaciones o campos específicos del modelo. Operaciones como 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.

Base

Texto

Archivos y lotes

Imágenes

Audio y tiempo real

Música

Video y recursos

Worlds

3D

Trabajos asíncronos

Gemini nativo

Administración

Resumen

Comportamiento de sondeo

Comportamiento de modelos y medios

Cuerpo de la solicitud

Notas de compatibilidad

Buenas prácticas para entradas de medios

Parámetros de Seedance

Ejemplo de Seedance

Respuesta

Imagen a video

Elementos de Kling 3.0

Referencia a video

Control de fotograma inicial y final

Video a video

Control de movimiento

Descubrimiento de modelos

​Resumen

​Comportamiento de sondeo

​Comportamiento de modelos y medios

​Cuerpo de la solicitud

​Notas de compatibilidad

​Buenas prácticas para entradas de medios

​Parámetros de Seedance

​Ejemplo de Seedance

​Respuesta

​Imagen a video

​Elementos de Kling 3.0

​Referencia a video

​Control de fotograma inicial y final

​Video a video

​Control de movimiento

​Descubrimiento de modelos

Resumen

Comportamiento de sondeo

Comportamiento de modelos y medios

Cuerpo de la solicitud

Notas de compatibilidad

Buenas prácticas para entradas de medios

Parámetros de Seedance

Ejemplo de Seedance

Respuesta

Imagen a video

Elementos de Kling 3.0

Referencia a video

Control de fotograma inicial y final

Video a video

Control de movimiento

Descubrimiento de modelos