Video y recursos
Crear video
Iniciar una tarea de generación de video
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-Keypara 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-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.
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
veo3.1ID 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,falsepor 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
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.
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.
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.
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.
URLs de imágenes para modelos que enumeran este campo. Consulte reference_images para conocer los límites de cantidad.
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-fastyseedance-2.0-mini: hasta 9 referencias de imagen en total, incluidos los activos de material. Más devuelve400 too_many_seedance_reference_images.seedance-2.5: hasta 30 entradas de imagen en total entreimage_urlsyreference_images.grok-imagine-video: hasta 7, y ladurationestá limitada a 10 segundos.grok-imagine-video-1.5ygrok-imagine-video-1.5-previewno 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.
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.
Imagen del último fotograma para start-end-to-video. Acepta las mismas entradas que start_image.
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.
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.
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.
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.
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 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.
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.
Segundo del video de origen donde comienza una video-extension. Requerido por grok-imagine-video.
Segundos a añadir en una video-extension, en modelos que enumeran este campo. grok-imagine-video acepta 6 o 10.
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.
Alias de compatibilidad para duration. Si se envían ambos, deben ser idénticos.
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.
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.
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.
Formato de contenedor, mp4 o mov, para modelos que enumeran este campo, como seedance-2.5. Omítalo para modelos que no lo enumeran.
Devolver también el último fotograma generado como last_frame_url. Solo modelos Seedance.
Alternancia de marca de agua para modelos que enumeran este campo (modelos Seedance).
Qué evitar en el video generado, hasta 5,000 caracteres, para modelos que enumeran este campo.
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.
Fotogramas por segundo (1-120), para modelos que enumeran este campo.
Recuento de fotogramas, para modelos que enumeran este campo. Los modelos Seedance no lo aceptan.
Segundos que la tarea puede esperar en la cola antes de que expire (3600 a 259200), para modelos Seedance.
Prioridad de la tarea de 0 a 9, para modelos Seedance. No lo combine con service_tier=flex.
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.
Identificador de seguridad del usuario final (hasta 128 caracteres), para modelos Seedance. Si se omite, TokenLab utiliza user cuando se proporciona.
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"}.
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_audioyreference_images. - Para compatibilidad, TokenLab también acepta
ratio,generate_audio,outputAudio,secondsyreferenceImages. - Si se envían tanto un campo principal como su alias, sus valores deben coincidir. Una discrepancia devuelve
400conconflicting_audio_selector,conflicting_durationoconflicting_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.0 | seedance-2.5 | |
|---|---|---|
| Resolución | seedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast y seedance-2.0-mini: 480p, 720p | 480p, 720p |
| Duración | -1, 4 a 15 segundos | -1, 4 a 30 segundos |
| Relación de aspecto | 1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptive | Igual 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 salida | mp4 | mp4 o mov |
seed | Aceptado | No aceptado |
| Entradas de referencia | 9 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 -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.
ID de la tarea. Idéntico a task_id.
ID de la tarea para consultar con GET /v1/tasks/{id}.
URL de estado para esta tarea, /v1/tasks/{id}. Llámela con su clave API.
Estado de la tarea: pending, processing, completed, failed. Una tarea nueva normalmente está pending.
Marca de tiempo Unix de cuando se creó la tarea.
Modelo utilizado.
ID de transacción de facturación cuando la liquidación ya se completó. Es independiente del ID de la tarea.
URL del video, presente solo cuando la respuesta de creación ya contiene el resultado. Normalmente, usted la lee de la respuesta de estado.
Mensaje de error u objeto de error estructurado cuando la tarea falla.
Errores
| Estado y código | Significado |
|---|---|
400 invalid_request | Un 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_long | La solicitud no coincide con lo que el modelo acepta para la operación. El error suele enumerar los valores aceptados. |
400 invalid_parameter | Una 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_ratio | Un alias y su campo principal no coinciden. |
400 unpriceable_selection | La 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_model | Demasiadas referencias de imagen para un modelo Seedance 2.0, o un material enviado a otro modelo. |
402 | Saldo insuficiente. |
403 task_not_owned | El task_id pertenece a otro espacio de trabajo. |
409 seedance_material_preparing, seedance_material_route_unavailable | Un material aún no está ACTIVE, o el modelo seleccionado no puede usar los materiales proporcionados. |
429 | Lí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
{
"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 Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Encabezados
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"
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.
1 <= length <= 255Cuerpo de la solicitud
application/json
Respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json