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ón | Entrada requerida o típica | Caso de uso |
|---|---|---|
text-to-video | prompt | Generar solo a partir de texto |
image-to-video | image_url o image compatible | Animar una imagen inicial |
reference-to-video | reference_images y opcionalmente video_urls / audio_urls en modelos compatibles | Mantener referencias de identidad, estilo o activos |
start-end-to-video | start_image, end_image | Controlar el primer y último fotograma |
video-to-video | video_url o task_id específico del modelo | Transformar o escalar un clip existente |
motion-control | image_url más video_url | Aplicar referencia de movimiento a un sujeto |
audio-to-video | audio_url | Flujos de video condicionados por audio |
video-extension | task_id, extend_at o campos de extensión específicos del modelo | Continuar 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-fastyveo3.1-litesiempre generan audio. Omitaoutput_audioo envíetrue;falseserá rechazado.wan-2.6ywan-2.7siempre incluyen audio. Omitaoutput_audioo envíetrue.wan-3.0ywan-3.0-primetambién incluyen siempre audio y no aceptan ningún selector de audio.hailuo-h3genera audio nativo y no tiene interruptor de silencio. No envíe un selector de audio que no aparezca en los detalles del modelo.viduq3-proyviduq3-turbogeneran audio de forma predeterminada; envíeoutput_audio: false(oaudio: false) para obtener una salida sin sonido. Los modelos Seedance y PixVerse aceptanoutput_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_urlsproporcionan 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-videode video a video, envíeprompty unavideo_urlHTTPS pública en formato.mp4. Una URL de resultado.mp4de TokenLab de una tarea anterior funciona. Esta operación no utiliza selectores deduration,resolutionoaspect_ratio.
PixVerse y HappyHorse
| Modelo | Operaciones | Entradas | Resolución | Duración | Selector de audio |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | Cualquier número entero de 1 a 15 segundos | output_audio, false por defecto |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | Mismos campos que C1 y V6 | 360p, 540p, 720p, 1080p | 5, 8 o 10 segundos; 1080p admite 5 u 8 segundos | output_audio, false por defecto |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | 3 a 15 segundos para operaciones de generación; la salida de video-to-video está limitada a 15 segundos | No 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; consulteGET /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
durationdescribe la duración del video de referencia de entrada; generalmente controla la duración de la salida generada. - Envíe un
Idempotency-KeyconPOST /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
| Tema | Referencia |
|---|---|
| Crear video | Crear video |
| Obtener estado del video | Obtener estado del video |
| Obtener estado de la tarea | Obtener estado de la tarea |
| Cancelar tarea | Cancelar tarea |
| Facturación y precios | Facturació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"
}