Crear video - TokenLab

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, la familia Veo 3 activa audio por defecto cuando se omite output_audio. Si un modelo admite control de audio, actívalo o desactívalo explícitamente con output_audio. El alias camelCase outputAudio también se acepta por compatibilidad. 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

model

string

predeterminado:"sora-2"

ID del modelo de video. El valor predeterminado de la API es sora-2. Consulta la guía de generación de video para ver la matriz pública actual y las capacidades compatibles.

prompt

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.

operation

string

Operación de video que se va a ejecutar. El contrato público admite 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.

image_url

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.

image

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.

reference_images

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. Se recomiendan URLs públicas https; los modelos compatibles también aceptan URLs data:.

reference_image_type

string

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

kling_elements

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.

video_url

string

URL pública del video de origen. Es obligatoria para los flujos públicos actuales de video-to-video y para los modelos de motion-control.

video_urls

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.

audio_url

string

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

audio_urls

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.

task_id

string

Identificador de tarea del proveedor para algunos flujos de continuación, extensión o derivación.

extend_at

integer

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

extend_times

string

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

duration

integer

Duración del video de salida generado en segundos. Los valores admitidos dependen del modelo. Este campo solo controla la duración del resultado y no la duración del video de referencia de entrada.

aspect_ratio

string

Relación de aspecto, por ejemplo 16:9, 9:16 o 1:1.

resolution

string

Resolución de salida, por ejemplo 720p, 1080p o 4k. La compatibilidad depende del modelo.

output_audio

boolean

Selector de salida de audio dependiente del modelo. En TokenLab, las solicitudes de la familia Veo 3 usan true por defecto cuando se omite este campo. kling-3.0-video acepta este selector para solicitudes sin referencias de elementos y lo asigna al control de sonido upstream compatible; las solicitudes Kling omitidas son silenciosas por defecto. No combines output_audio=true con kling_elements. Otros modelos de video públicos siguen su comportamiento predeterminado gobernado. También se acepta el alias camelCase outputAudio por compatibilidad.

fps

integer

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

negative_prompt

string

Elementos que deben evitarse en el video generado.

seed

integer

Semilla aleatoria para resultados reproducibles.

cfg_scale

number

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

motion_strength

number

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

start_image

string

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

end_image

string

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

size

string

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

watermark

boolean

Interruptor de marca de agua para los modelos que lo exponen públicamente.

effect_type

string

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

user

string

Identificador único del usuario final.

Notas de compatibilidad

Los campos públicos canónicos están en snake_case: reference_images, reference_image_type y output_audio.
Por compatibilidad, TokenLab también acepta los alias camelCase referenceImages, referenceImageType y outputAudio.
Si omites operation, TokenLab la infiere a partir de las entradas. Aun así, en producción se recomienda enviarla explícitamente.

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.
Si usas URLs firmadas, asegúrate de que sigan siendo válidas durante todo el tiempo necesario para reintentos y creación asíncrona de tareas.

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.

task_id

string

Identificador único de la tarea para hacer polling.

poll_url

string

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

billing_transaction_id

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.

status

string

Estado inicial: pending.

created

integer

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

model

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": "sora-2",
    "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": "sora-2",
  "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"
    }
)

Kling 3.0 Elements

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 el contrato público 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. 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.

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

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": "topaz-video-upscale",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Upscale the clip while preserving the original motion.",
        "resolution": "1080p"
    }
)

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 contrato upstream correspondiente.

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"
    }
)

Disponibilidad actual de audio-to-video y video-extension

El contrato público de TokenLab acepta audio-to-video y video-extension para flujos específicos de ciertos modelos. Sin embargo, en la lista pública de modelos generalmente habilitados de esta compilación de documentación no hay ningún modelo ampliamente habilitado que anuncie públicamente estas capacidades. Antes de integrar esos flujos, confirma la disponibilidad actual mediante la Models API o la página de modelos.

Inventario público actual de modelos

Esta lista está alineada con el inventario público de modelos de video habilitados en esta compilación de documentación. Para el estado más reciente, consulta la Models API.

OpenAI

Modelo	Operaciones públicas
`sora-2`	Texto a video, imagen a video
`sora-2-pro`	Texto a video, imagen a video
`sora-2-pro-storyboard`	Imagen a video

Kuaishou

Modelo	Operaciones públicas
`kling-3.0-motion-control`	Control de movimiento
`kling-3.0-video`	Texto a video, imagen a video, inicio-fin a video, referencias de elementos
`kling-v2.5-turbo-pro`	Texto a video, imagen a video, inicio-fin a video
`kling-v2.5-turbo-std`	Texto a video, imagen a video
`kling-v2.6-pro`	Texto a video, imagen a video, inicio-fin a video
`kling-v2.6-std`	Texto a video, imagen a video
`kling-v3.0-pro`	Texto a video, imagen a video, inicio-fin a video
`kling-v3.0-std`	Texto a video, imagen a video, inicio-fin a video
`kling-video-o1-pro`	Texto a video, imagen a video, referencia a video, inicio-fin a video, video a video
`kling-video-o1-std`	Texto a video, imagen a video, referencia a video, inicio-fin a video, video a video

Google

Modelo	Operaciones públicas
`veo3`	Texto a video, imagen a video
`veo3-fast`	Texto a video, imagen a video
`veo3-pro`	Texto a video, imagen a video
`veo3.1`	Texto a video, imagen a video, referencia a video, inicio-fin a video
`veo3.1-fast`	Texto a video, imagen a video, referencia a video, inicio-fin a video
`veo3.1-pro`	Texto a video, imagen a video, inicio-fin a video

ByteDance

Modelo	Operaciones públicas
`seedance-1.5-pro`	Texto a video, imagen a video

MiniMax

Modelo	Operaciones públicas
`hailuo-2.3-fast`	Imagen a video
`hailuo-2.3-pro`	Texto a video, imagen a video
`hailuo-2.3-standard`	Texto a video, imagen a video

Alibaba

Modelo	Operaciones públicas
`wan-2.2-plus`	Texto a video, imagen a video
`wan-2.5`	Texto a video, imagen a video
`wan-2.6`	Texto a video, imagen a video, referencia a video

Shengshu

Modelo	Operaciones públicas
`viduq2`	Texto a video, referencia a video
`viduq2-pro`	Imagen a video, referencia a video, inicio-fin a video
`viduq2-pro-fast`	Imagen a video, inicio-fin a video
`viduq2-turbo`	Imagen a video, inicio-fin a video
`viduq3-pro`	Texto a video, imagen a video, inicio-fin a video
`viduq3-turbo`	Texto a video, imagen a video, inicio-fin a video

xAI

Modelo	Operaciones públicas
`grok-imagine-image-to-video`	Imagen a video
`grok-imagine-text-to-video`	Texto a video
`grok-imagine-upscale`	Video a video

Otros

Modelo	Operaciones públicas
`topaz-video-upscale`	Video a video

Documentation Index

​Resumen

​Comportamiento de sondeo

​Comportamiento de modelos y medios

​Cuerpo de la solicitud

​Notas de compatibilidad

​Buenas prácticas para entradas de medios

​Respuesta

​Imagen a video

​Kling 3.0 Elements

​Referencia a video

​Control de fotograma inicial y final

​Video a video

​Control de movimiento

​Disponibilidad actual de audio-to-video y video-extension

​Inventario público actual de modelos

​OpenAI

​Kuaishou

​Google

​ByteDance

​MiniMax

​Alibaba

​Shengshu

​xAI

​Otros

Resumen

Comportamiento de sondeo

Comportamiento de modelos y medios

Cuerpo de la solicitud

Notas de compatibilidad

Buenas prácticas para entradas de medios

Respuesta

Imagen a video

Kling 3.0 Elements

Referencia a video

Control de fotograma inicial y final

Video a video

Control de movimiento

Disponibilidad actual de audio-to-video y video-extension

Inventario público actual de modelos

OpenAI

Kuaishou

Google

ByteDance

MiniMax

Alibaba

Shengshu

xAI

Otros