Video y recursos

Crear video

Iniciar una tarea de generación de video

POST
/v1/videos/generations

Descripción general

La generación de video es asíncrona. Una solicitud de creación exitosa devuelve un id de tarea (el mismo valor que task_id) y una poll_url. Llame a GET /v1/tasks/{id} con ese ID hasta que el status sea completed o failed, y luego lea video_url. Consulte Obtener estado del video.

  • El archivo resultante se guarda durante 30 días. Descárguelo si lo necesita por más tiempo; consulte Retención de datos.
  • Una tarea de Seedance en cola puede cancelarse con Cancelar tarea.
  • El costo puede reservarse cuando se acepta la tarea y se liquida cuando la tarea finaliza o falla. Consulte Facturación y precios.
  • Envíe un encabezado Idempotency-Key para reintentar una solicitud de creación de forma segura después de un tiempo de espera.

Cada modelo acepta sus propias operaciones y campos. GET /v1/models/{model} (Obtener modelo) enumera, para cada operación, los campos aceptados, resoluciones, duraciones y relaciones de aspecto. Un campo o valor fuera de esa lista devuelve 400 con los valores aceptados. Establezca duration, resolution, aspect_ratio y output_audio usted mismo: cuando omite uno, TokenLab utiliza el valor predeterminado del modelo para la operación, y si no coincide ningún valor predeterminado, la solicitud devuelve 400 e indica el campo que debe establecerse.

Entrada de audio y medios

El comportamiento del audio depende del modelo seleccionado y de la operación. Un video puede contener sonido incluso cuando no se muestra ningún selector de audio. Omitir un selector es diferente a enviar false.

  • veo3.1, veo3.1-fast y veo3.1-lite siempre generan audio. Omita output_audio o envíe true; false será rechazado.
  • wan-2.6 y wan-2.7 siempre incluyen audio. Omita output_audio o envíe true. wan-3.0 y wan-3.0-prime también incluyen siempre audio y no aceptan ningún selector de audio.
  • hailuo-h3 genera audio nativo y no tiene interruptor de silencio. No envíe un selector de audio que no aparezca en los detalles del modelo.
  • viduq3-pro y viduq3-turbo generan audio de forma predeterminada; envíe output_audio: false (o audio: false) para obtener una salida sin sonido. Los modelos Seedance y PixVerse aceptan output_audio; envíelo explícitamente en lugar de depender del valor predeterminado. Úselo solo para las operaciones que lo incluyan en su lista.
  • audio_url / audio_urls proporcionan audio de entrada o de referencia. No son interruptores de salida de audio. La edición de video, la transferencia de movimiento y la transferencia de estilo pueden conservar la banda sonora de entrada; preservar el audio de origen no significa silenciarlo.

Consulte los detalles del modelo para conocer los valores permitidos y los precios que dependen del audio. Cuando un modelo los enumera, los alias outputAudio, generate_audio y el booleano audio deben coincidir con output_audio cuando se combinan. No asuma que todas las versiones u operaciones dentro de una familia de modelos comparten los mismos controles de audio.

Utilice URLs https de acceso público para imágenes, videos y audio, y manténgalas válidas hasta que comience la tarea. Una URL de medios puede tener hasta 8,192 caracteres. Algunos modelos también aceptan URLs de imagen data: en línea (hasta 2,000,000 de caracteres por campo); las URLs son más fiables para archivos grandes. No mezcle base64 en línea y URLs remotas en la misma solicitud.

Cuerpo de la solicitud

modelstringpredeterminado: veo3.1

ID del modelo de video. Enumere los modelos de video actuales con Listar modelos (recommended_for=video) y luego envíe el modelo explícitamente.

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
promptstring

Descripción textual del video, hasta 10,000 caracteres. La mayoría de las operaciones necesitan una; los detalles del modelo indican cuáles no.

operationstring

Modo de generación: text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension o motion-control. Cada modelo solo admite algunos de ellos; los demás devuelven 400 unsupported_operation. Si lo omite, TokenLab lo infiere a partir de las entradas: un task_id con extend_at o extend_times resulta en video-extension, las imágenes o materiales de referencia resultan en reference-to-video, end_image resulta en start-end-to-video, una entrada de video resulta en video-to-video, una entrada de imagen (image, image_url, image_urls o start_image) resulta en image-to-video, y en cualquier otro caso text-to-video. Envíelo explícitamente para que un campo no coincidente falle de forma temprana.

image_urlstring

URL de acceso público de la imagen del primer fotograma. Los modelos Seedance 2.0 también aceptan asset://asset-YYYYMMDDHHMMSS-xxxxx para usar un material de TokenLab ACTIVE como primer fotograma. Prefiera una URL https para obtener la mayor compatibilidad con los modelos.

imagestring

Imagen en línea como una URL de datos (por ejemplo, data:image/jpeg;base64,...). Solo algunos modelos la aceptan; image_url funciona en más.

image_urlsarray

URLs de imágenes para modelos que enumeran este campo. Consulte reference_images para conocer los límites de cantidad.

reference_imagesarray

Imágenes de referencia para reference-to-video, como URLs https o URLs de datos. El límite de cantidad depende del modelo:

  • seedance-2.0, seedance-2.0-fast y seedance-2.0-mini: hasta 9 referencias de imagen en total, incluidos los activos de material. Más devuelve 400 too_many_seedance_reference_images.
  • seedance-2.5: hasta 30 entradas de imagen en total entre image_urls y reference_images.
  • grok-imagine-video: hasta 7, y la duration está limitada a 10 segundos. grok-imagine-video-1.5 y grok-imagine-video-1.5-preview no aceptan imágenes de referencia.
  • Otros modelos: consulte los detalles del modelo. Una solicitud que supere el límite devuelve 400 too_many_items.

Los modelos Seedance 2.0 también aceptan asset://asset-YYYYMMDDHHMMSS-xxxxx para un material de TokenLab ACTIVE. Para la selección de modelos, límites 4K y notas sobre Mini, consulte la guía de modelos de video Seedance 2.0. Para grok-imagine-video, no combine imágenes de referencia con image_url o image.

start_imagestring

Imagen del primer fotograma. Con end_image, la solicitud es start-end-to-video. Sin end_image, es image-to-video, y start_image funciona como image en los modelos cuyo contrato lo especifica. Acepta una URL pública o una data URL; los modelos Seedance 2.0 también aceptan asset://asset-YYYYMMDDHHMMSS-xxxxx.

end_imagestring

Imagen del último fotograma para start-end-to-video. Acepta las mismas entradas que start_image.

material_asset_idstring

ID de activo de material de TokenLab Seedance devuelto por Crear activo de material. Aceptado solo por los modelos Seedance 2.0; otros modelos devuelven 400 unsupported_seedance_material_asset_model. El activo debe estar ACTIVE y pertenecer a su cuenta. Este campo es una entrada de referencia genérica; para asignar explícitamente el significado de primer fotograma, último fotograma o imagen de referencia, coloque asset://<material_asset_id> en start_image, end_image o reference_images en su lugar.

material_asset_idsarray

Hasta 9 IDs de activos de material de TokenLab Seedance. Cuentan para las 9 referencias de imagen de los modelos Seedance 2.0.

Las URLs de imagen ordinarias se pasan como entradas de imagen; no crean activos de material reutilizables. Cree activos reutilizables a través de la API de materiales y luego use sus IDs de TokenLab o URIs asset://asset-YYYYMMDDHHMMSS-xxxxx. Si un material explícito devuelve 409 seedance_material_preparing, verifique los inactive_asset_ids devueltos y vuelva a intentarlo después de que esos materiales estén ACTIVE.

video_urlstring

URL de acceso público del video de origen, para las operaciones que aceptan uno: video-to-video, video-extension y motion-control, en modelos que enumeran este campo.

video_urlsarray

Videos de origen o de referencia para modelos que enumeran este campo. seedance-2.5 acepta hasta 10 entradas de video en total entre video_url y video_urls. Consulte los detalles del modelo para otros modelos.

audio_urlstring

URL de audio pública para una referencia de audio u operación basada en audio, en modelos que enumeran este campo. Es una entrada, no un interruptor de salida de audio.

audio_urlsarray

Audio de referencia para modelos que enumeran este campo. seedance-2.5 acepta hasta 10 entradas de audio en total entre audio_url y audio_urls y permite una solicitud con referencias de audio y sin prompt. Para seedance-2.5, el audio de referencia más el video de referencia dura como máximo 30 segundos combinados.

task_idstring

ID de una tarea anterior en su espacio de trabajo, para video-extension en modelos que enumeran este campo. Una tarea que no pertenece a su espacio de trabajo devuelve 403 task_not_owned.

extend_atinteger

Segundo del video de origen donde comienza una video-extension. Requerido por grok-imagine-video.

extend_timesstring

Segundos a añadir en una video-extension, en modelos que enumeran este campo. grok-imagine-video acepta 6 o 10.

durationinteger

Duración de salida en segundos. Los valores permitidos dependen del modelo y la operación; otros valores devuelven 400 invalid_duration. Los modelos Seedance también aceptan -1 para permitir que el modelo elija dentro de su rango; la facturación se estima de forma conservadora hasta que finaliza la tarea. Algunas operaciones no requieren duración, como motion-control y grok-imagine-video video-to-video.

secondsinteger

Alias de compatibilidad para duration. Si se envían ambos, deben ser idénticos.

aspect_ratiostring

Relación de aspecto, por ejemplo 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 o adaptive (Seedance). Los valores permitidos dependen del modelo y la operación; otros valores devuelven 400 invalid_aspect_ratio.

resolutionstring

Resolución de salida, por ejemplo 480p, 720p, 1080p o 4k. Los valores permitidos dependen del modelo y la operación, y algunos modelos también usan 360p, 540p o 768p. Otros valores devuelven 400 invalid_resolution.

output_audioboolean

Selector de salida de audio para operaciones que lo enumeran. La omisión sigue el valor predeterminado del modelo; false solicita una salida silenciosa solo donde el modelo lo permite. Consulte las notas de audio anteriores y los detalles del modelo seleccionado.

output_formatstring

Formato de contenedor, mp4 o mov, para modelos que enumeran este campo, como seedance-2.5. Omítalo para modelos que no lo enumeran.

return_last_frameboolean

Devolver también el último fotograma generado como last_frame_url. Solo modelos Seedance.

watermarkboolean

Alternancia de marca de agua para modelos que enumeran este campo (modelos Seedance).

negative_promptstring

Qué evitar en el video generado, hasta 5,000 caracteres, para modelos que enumeran este campo.

seedinteger

Semilla para una generación reproducible, para modelos que enumeran este campo. Los modelos Seedance 2.0 aceptan -1 para una semilla aleatoria; seedance-2.5 no acepta este campo.

fpsinteger

Fotogramas por segundo (1-120), para modelos que enumeran este campo.

framesinteger

Recuento de fotogramas, para modelos que enumeran este campo. Los modelos Seedance no lo aceptan.

execution_expires_afterinteger

Segundos que la tarea puede esperar en la cola antes de que expire (3600 a 259200), para modelos Seedance.

priorityinteger

Prioridad de la tarea de 0 a 9, para modelos Seedance. No lo combine con service_tier=flex.

service_tierstring

default se acepta como una operación nula de compatibilidad en los modelos Seedance 2.0 y 2.5. flex se rechaza en esos modelos.

safety_identifierstring

Identificador de seguridad del usuario final (hasta 128 caracteres), para modelos Seedance. Si se omite, TokenLab utiliza user cuando se proporciona.

toolsarray

Herramientas que el modelo puede usar durante la generación, para modelos Seedance 2.0 y 2.5. La herramienta admitida es {"type": "web_search"}.

userstring

Un identificador único para el usuario final. Para los modelos Seedance, TokenLab también lo utiliza como safety_identifier cuando se omite ese campo.

Nombres de campos compatibles

  • Los campos principales usan snake_case: aspect_ratio, output_audio y reference_images.
  • Para compatibilidad, TokenLab también acepta ratio, generate_audio, outputAudio, seconds y referenceImages.
  • Si se envían tanto un campo principal como su alias, sus valores deben coincidir. Una discrepancia devuelve 400 con conflicting_audio_selector, conflicting_duration o conflicting_aspect_ratio.

Parámetros de Seedance

Los modelos Seedance (seedance-2.0, seedance-2.0-fast, seedance-2.0-mini y seedance-2.5) aceptan los nombres de campo de TokenLab anteriores y los alias seconds, ratio y generate_audio. Las versiones difieren:

Modelos Seedance 2.0seedance-2.5
Resoluciónseedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast y seedance-2.0-mini: 480p, 720p480p, 720p
Duración-1, 4 a 15 segundos-1, 4 a 30 segundos
Relación de aspecto1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptiveIgual para text-to-video y reference-to-video. Image-to-video, start-end, edición de video y extensión necesitan adaptive; la edición de video también necesita duration=-1
Formato de salidamp4mp4 o mov
seedAceptadoNo aceptado
Entradas de referencia9 referencias de imagen incluidos materiales (los materiales solo se aceptan en estos modelos)30 imágenes, 10 videos y 10 archivos de audio en total

Los detalles del modelo son la fuente actual para estos valores. Envíe duration, resolution, aspect_ratio y output_audio explícitamente en lugar de confiar en un valor predeterminado; el recommended_request del modelo muestra una solicitud típica.

duration=-1 o seconds=-1 permite que Seedance elija la duración de salida dentro del rango del modelo. TokenLab estima el costo de forma conservadora antes de que finalice la tarea, y luego liquida el uso de la tarea completada cuando está disponible. service_tier=flex y frames se rechazan en estos modelos.

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.5",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

Respuesta

Los campos que describen resultados, errores, marcas de tiempo y el modelo se devuelven cuando están disponibles para la tarea.

idstring

ID de la tarea. Idéntico a task_id.

task_idstring

ID de la tarea para consultar con GET /v1/tasks/{id}.

poll_urlstring

URL de estado para esta tarea, /v1/tasks/{id}. Llámela con su clave API.

statusstring

Estado de la tarea: pending, processing, completed, failed. Una tarea nueva normalmente está pending.

createdinteger

Marca de tiempo Unix de cuando se creó la tarea.

modelstring

Modelo utilizado.

billing_transaction_idstring

ID de transacción de facturación cuando la liquidación ya se completó. Es independiente del ID de la tarea.

video_urlstring

URL del video, presente solo cuando la respuesta de creación ya contiene el resultado. Normalmente, usted la lee de la respuesta de estado.

errorstring | object

Mensaje de error u objeto de error estructurado cuando la tarea falla.

Errores

Estado y códigoSignificado
400 invalid_requestUn campo está mal formado, fuera de rango o falta. error.param lo nombra. Un mensaje como "Set aspect_ratio explicitly" significa que el campo omitido no tiene un valor predeterminado para esta solicitud.
400 unsupported_operation, unsupported_parameter, invalid_resolution, invalid_duration, invalid_aspect_ratio, invalid_parameter_value, too_many_items, prompt_too_longLa solicitud no coincide con lo que el modelo acepta para la operación. El error suele enumerar los valores aceptados.
400 invalid_parameterUna entrada no se ajusta a la operación, por ejemplo, una imagen enviada con text-to-video.
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratioUn alias y su campo principal no coinciden.
400 unpriceable_selectionLa combinación seleccionada no tiene precio. Cambie resolution, duration, aspect_ratio o la configuración de audio.
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_modelDemasiadas referencias de imagen para un modelo Seedance 2.0, o un material enviado a otro modelo.
402Saldo insuficiente.
403 task_not_ownedEl task_id pertenece a otro espacio de trabajo.
409 seedance_material_preparing, seedance_material_route_unavailableUn material aún no está ACTIVE, o el modelo seleccionado no puede usar los materiales proporcionados.
429Límite de tasa excedido. Consulte Límites de tasa.

Solicitud

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,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Respuesta

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

Imagen a video

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3",
        "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,
        "resolution": "768p"
    }
)

Referencia a video

Use operation=reference-to-video cuando el modelo admita el condicionamiento de referencia dedicado. Las referencias de imagen van en reference_images; los modelos que aceptan videos y audio de referencia usan video_urls y audio_urls. duration establece solo la longitud de la salida generada. No limita la longitud de la entrada de video de referencia. Consulte reference_images arriba para conocer los límites de cantidad por modelo.

import requests

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"
        ],
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

Control de fotogramas clave

Use start_image y end_image para controlar el primer y último fotograma:

import requests

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

Video a video

Use operation=video-to-video cuando el modelo acepte un video existente como entrada principal. Para grok-imagine-video, envíe una URL .mp4 HTTPS pública en video_url y el prompt de edición, y omita resolution, duration y aspect_ratio.

import requests

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

Extensión de video

Use operation=video-extension para continuar un resultado anterior. Envíe el task_id de una tarea de su espacio de trabajo y un prompt; los otros campos dependen del modelo. grok-imagine-video también necesita extend_at y acepta extend_times de 6 o 10. veo3.1 y veo3.1-fast aceptan task_id y prompt. Los modelos Seedance enumeran video_url, video_urls y task_id para esta operación.

Control de movimiento

Use operation=motion-control cuando el modelo espere tanto una imagen de sujeto como un video de referencia de movimiento. Envíe image_url y video_url; se requiere resolution.

import requests

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 identity 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 videos y las operaciones admitidas cambian con el tiempo. Use la API de modelos para verificar el soporte actual antes de configurar un flujo específico del modelo:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

Lea la respuesta de detalles del modelo antes de confiar en operaciones o campos específicos del modelo. Las operaciones como video-extension y motion-control son específicas del modelo; confirme la disponibilidad actual allí en lugar de confiar en ejemplos estáticos en esta página.

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Clave opcional que hace que una solicitud de creación sea segura para reintentar. Envíe un nuevo valor único, como un UUID, para cada tarea. Un reintento con la misma clave y el mismo cuerpo devuelve el resultado de la solicitud de creación original, generalmente la tarea original, y no crea, envía ni cobra una segunda tarea. Un cuerpo diferente con una clave que ya fue aceptada se rechaza con 409. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json