Guías de medios

Generación de video

Cree videos a partir de texto, imágenes, audio o clips existentes

La generación de video es asíncrona. POST /v1/videos/generations devuelve un ID de tarea y, por lo general, una poll_url. Realice consultas GET /v1/tasks/{id} con ese ID hasta que el video final esté listo.

Envíe URLs HTTP(S) públicas o URLs de datos compatibles en los campos de imagen aceptados por el modelo seleccionado. Estas entradas siguen la ruta de medios normal y no crean automáticamente IDs de material reutilizables.

Cuando un material explícito aún se está preparando, POST /v1/videos/generations devuelve 409 seedance_material_preparing con inactive_asset_ids. Realice consultas sobre esos activos hasta que estén ACTIVE, luego vuelva a intentarlo con los mismos IDs de material. Si un activo está en estado FAILED, inspeccione el error_message y corríjalo o vuelva a importarlo antes de reintentar.

Elegir una API

Utilice /v1/videos/generations para una nueva integración de video. Los clientes existentes de Seedance 2.0 que ya envían solicitudes de content[] de Volcengine o Action pueden mantener ese formato a través de /api/v3. Ambas APIs utilizan una clave Bearer de TokenLab, pero sus campos y valores de estado son diferentes.

Elegir qué crear

Establezca operation explícitamente para que la API pueda validar los campos correctos para la tarea.

OperaciónEntrada requerida o típicaCaso de uso
text-to-videopromptGenerar solo a partir de texto
image-to-videoimage_url o image compatibleAnimar una imagen inicial
reference-to-videoreference_images y opcionalmente video_urls / audio_urls en modelos compatiblesMantener referencias de identidad, estilo o activos
start-end-to-videostart_image, end_imageControlar el primer y último fotograma
video-to-videovideo_url o task_id específico del modeloTransformar o escalar un clip existente
motion-controlimage_url más video_urlAplicar referencia de movimiento a un sujeto
audio-to-videoaudio_urlFlujos de video condicionados por audio
video-extensiontask_id, extend_at o campos de extensión específicos del modeloContinuar un video generado

Elegir un modelo

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

Utilice un ID de modelo devuelto por TokenLab, luego elija el tipo de generación con operation y las entradas de medios correspondientes. No utilice un nombre de operación como ID de modelo.

Lea los detalles del modelo seleccionado antes de depender de campos especializados como reference_images, kling_elements, output_audio, duration, resolution o aspect_ratio.

Crear un video

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

Utilice URLs https para medios que puedan obtenerse de Internet. Las URLs temporales deben permanecer válidas hasta que TokenLab cree la tarea.

Campos específicos del modelo

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.

  • Para la familia Seedance 2.0, lea la guía de modelos de video de Seedance 2.0 antes de utilizar salidas 4K, límites de resolución Fast/Mini o entradas de referencia multimodales.
  • Para grok-imagine-video de video a video, envíe prompt y una video_url HTTPS pública en formato .mp4. Una URL de resultado .mp4 de TokenLab de una tarea anterior funciona. Esta operación no utiliza selectores de duration, resolution o aspect_ratio.

PixVerse y HappyHorse

ModeloOperacionesEntradasResoluciónDuraciónSelector de audio
pixverse-c1, pixverse-v6text-to-video, image-to-video, start-end-to-video, reference-to-videoprompt; image_url; start_image + end_image; reference_images360p, 540p, 720p, 1080pCualquier número entero de 1 a 15 segundosoutput_audio, false por defecto
pixverse-v5.6text-to-video, image-to-video, start-end-to-video, reference-to-videoMismos campos que C1 y V6360p, 540p, 720p, 1080p5, 8 o 10 segundos; 1080p admite 5 u 8 segundosoutput_audio, false por defecto
happyhorse-1.0text-to-video, image-to-video, reference-to-video, video-to-videoprompt; image_url; reference_images; video_url + reference_images720p, 1080p3 a 15 segundos para operaciones de generación; la salida de video-to-video está limitada a 15 segundosNo enviar output_audio

En TokenLab, los modelos PixVerse anteriores no aceptan operation=video-extension.

curl https://api.tokenlab.sh/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pixverse-v6",
    "operation": "image-to-video",
    "prompt": "A slow camera move through a neon-lit street",
    "image_url": "https://example.com/start.jpg",
    "resolution": "1080p",
    "duration": 5,
    "output_audio": true
  }'

Obtener el video finalizado

Llame a GET /v1/tasks/{id} con el id o task_id de la respuesta de creación hasta que la tarea esté completed o failed.

Las tareas de video completadas pueden devolver video_url, video o videos dependiendo del modelo y la cantidad de salidas. Trate billing_transaction_id como un identificador de facturación, no como un identificador de tarea.

Las URLs de resultados de video son URLs de resultados de medios de TokenLab que terminan en el tipo de archivo, como .mp4, y permanecen válidas durante 30 días. media_retention.items informa el estado de guardado de cada elemento y expires_at; la respuesta puede omitir media_retention cuando el estado de guardado no se conoce a tiempo, y la URL sigue funcionando. Las tareas fallidas y en curso devuelven campos de URL de video vacíos. Las instantáneas de tareas asíncronas tienen un ciclo de vida separado. Consulte Retención de datos.

Errores comunes

  • No utilice rutas de estado por modalidad como /v1/videos/generations/{id} en código nuevo; consulte GET /v1/tasks/{id}.
  • No combine campos de primer fotograma con flujos de imagen de referencia dedicados a menos que los detalles del modelo lo permitan.
  • No asuma que duration describe la duración del video de referencia de entrada; generalmente controla la duración de la salida generada.
  • Envíe un Idempotency-Key con POST /v1/videos/generations. Después de un tiempo de espera, envíe la misma solicitud con la misma clave para obtener la tarea original. Sin una clave, verifique si ya se creó una tarea antes de volver a intentarlo.

Referencia de la API

TemaReferencia
Crear videoCrear video
Obtener estado del videoObtener estado del video
Obtener estado de la tareaObtener estado de la tarea
Cancelar tareaCancelar tarea
Facturación y preciosFacturación y precios

Hailuo H3-Max genera videos de 5 a 15 segundos a 480p o 768p a partir de texto, un primer fotograma o un primer y último fotograma. Su flujo de trabajo centrado en la velocidad es útil para convertir rápidamente una idea de toma en un clip corto.

{
  "model": "hailuo-h3-max",
  "operation": "text-to-video",
  "prompt": "A slow camera move through a quiet garden",
  "resolution": "768p",
  "duration": 5,
  "aspect_ratio": "16:9"
}

En esta página