API de generación de video
Cómo generar video con /videos: inicia una tarea, consúltala y descarga el archivo. Campos, archivos de referencia, borradores y facturación.
Video
Los modelos de video se ejecutan como tareas. POST /videos inicia una y devuelve su id de inmediato; consulta GET /videos/{id} cada pocos segundos hasta que status sea completed o failed (normalmente de 1 a 5 minutos) y luego descárgalo: la tarea terminada trae una url (un enlace al archivo, válido por una semana y renovado en cada lectura; si no pudimos almacenar el archivo, url es la ruta /v1/videos/{id}/content) y GET /videos/{id}/content siempre obtiene el archivo. El id de cualquier respuesta (chatcmpl-…, img_…, video_…) y el request_id de cualquier error son lo que debes citar a soporte.
| Campo | Tipo | |
|---|---|---|
model | string | Obligatorio. El id de un modelo de video. |
prompt | string | Obligatorio (salvo con draft_id). De 3 a 20.000 caracteres. |
seconds | integer | "auto" | Duración (duration se acepta como el mismo campo). Seedance 2.5: de 4 a 30; Seedance 2.0: de 4 a 15. "auto" deja que el modelo elija; se reserva la duración máxima y pagas por lo que genere. Por defecto 5; con reference_videos el valor por defecto es "auto". |
resolution | string | 480p, 720p (por defecto), 1080p o 4k; solo las resoluciones que ofrece el modelo (ver la referencia de modelos). |
ratio | string | 16:9 (por defecto), 9:16, 1:1, 4:3, 3:4, 21:9 o adaptive. Con reference_videos el valor por defecto sigue al video de entrada. |
image | string | Primer fotograma: un enlace a una imagen o una data URL (first_frame se acepta como el mismo campo). |
last_frame | string | Último fotograma, se usa junto con image. |
audio | boolean | Generar sonido con el video. Por defecto true. |
seed | integer | -1 para una semilla aleatoria (por defecto), o un número entero de 1 a 4294967295 para repetir un resultado en el mismo modelo. La respuesta muestra la semilla que enviaste, o -1 si fue aleatoria. |
camera_fixed | boolean | true mantiene la cámara fija. |
bitrate_mode | string | standard (por defecto) o high. high puede fallar cuando el modelo está ocupado; en ese caso se reembolsa. |
return_last_frame | boolean | true: el último fotograma se conserva como imagen en GET /videos/{id}/last_frame. |
reference_images | string[] | Enlaces a imágenes o data URLs: hasta 30 en Seedance 2.5, 9 en Seedance 2.0 (jpeg, png, webp, bmp, tiff, gif; hasta 30 MB; cada lado de 300 a 6000 px). |
reference_videos | string[] | Enlaces públicos a MP4/MOV: hasta 10 en Seedance 2.5, 3 en Seedance 2.0; de 2 a 15 s cada uno, 480p o 720p, hasta 50 MB. Su duración también se cobra. |
reference_audios | string[] | Enlaces públicos a WAV/MP3: hasta 10 en Seedance 2.5, 3 en Seedance 2.0; de 2 a 15 s cada uno, hasta 15 MB. |
task_type | string | Con reference_videos: auto, reference, edit o extend (Seedance 2.5). edit y extend siguen al video de entrada; omite seconds y ratio. |
draft | boolean | Seedance 2.5: true genera una vista previa en 480p al precio de 480p. resolution debe ser 480p. |
draft_id | string | Convierte un borrador terminado en el video final a 1080p. Envía solo model y draft_id: el prompt, las referencias, la duración, la proporción, el audio y la semilla vienen del borrador. Los borradores duran 7 días. |
Las referencias se numeran por tipo en el orden en que las envías: el primer elemento de reference_images es la imagen 1, el segundo la imagen 2, y lo mismo para videos y audios. Nómbralas así en el prompt, como hace el playground con [Image 1], [Video 1] y [Audio 1], por ejemplo "The woman in [Image 1] walks through the street of [Video 1]". Enviar más archivos de los que acepta el modelo se rechaza, no se recorta.
status es queued, in_progress, completed o failed. Una tarea completada tiene usage.video_tokens y usage.cost_usd; una fallida no se cobra y trae error.code y error.message: generation_failed (el modelo no pudo generar el video), invalid_reference (uno de los archivos de referencia fue rechazado; el mensaje indica cuál) o timeout.
// GET https://api.apistore.cloud/v1/videos/video_...
{
"id": "video_0123456789abcdef0123456789abcdef",
"object": "video",
"model": "MODEL_NAME",
"status": "completed",
"created_at": 1793984023,
"completed_at": 1793984214,
"prompt": "A red paper boat drifting across a calm lake at sunrise",
"resolution": "720p",
"ratio": "16:9",
"seconds": 5,
"draft": false,
"seed": 49873,
"url": "https://.../video_0123456789abcdef0123456789abcdef.mp4",
"last_frame": null,
"error": null,
"usage": { "video_tokens": 108000, "cost_usd": 1.0978 }
}Borradores (Seedance 2.5): genera primero una vista previa barata en 480p y luego convierte la que te guste en el video final a 1080p con la misma semilla y los mismos ajustes.
# 1. the draft: 480p, at the 480p price
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "prompt": "A red paper boat on a lake", "seconds": 5, "resolution": "480p", "draft": true}'
# 2. when it is completed, the final video at 1080p
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "draft_id": "video_..."}'El costo estimado se retiene de tu saldo cuando la tarea empieza: (segundos del video de entrada + segundos de salida) en tokens de video al precio de esa resolución. Al terminar pagas por los tokens realmente generados (unos 108K por 5 segundos a 720p) y el resto se libera; una tarea fallida no cuesta nada. En Ajustes puedes cambiar la facturación de video de la lista de precios por token a "por USD": el cargo del propio proveedor por el trabajo a precio de lista, menos tu descuento. Cada registro de facturación indica cuál se aplicó.
Guías de modelos
Para qué sirve cada familia de modelos de video, sus límites y cómo escribir prompts que el modelo siga.
Seedance 2.5
El modelo de formato largo: hasta 30 segundos en una tarea, muchos archivos de referencia, y edición o extensión de un video existente. Escribe y habla 11 idiomas, entre ellos inglés y vietnamita.
| De un vistazo | |
|---|---|
| Duración | De 4 a 30 segundos, o "auto" para que el modelo elija |
| Resolución | 480p, 720p, 1080p |
| Proporción | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 o adaptive (sigue a la entrada) |
| Modos | Texto a video; primer fotograma o primer y último fotograma; referencias; editar un video; extender un video |
| Referencias | Hasta 30 imágenes, 10 videos y 10 audios. Se acepta audio solo |
| Sonido | La voz, la música y los efectos se generan junto con la imagen (audio: true) |
| Borradores | Sí: primero una vista previa en 480p, luego el video final a partir de la que te guste |
Cómo escribir prompts
- Empieza con una frase. Di quién, dónde, qué pasa, el estilo y la cámara en una sola línea. Luego agrega el detalle debajo.
- Vincula cada referencia. Nombra cada archivo por su número y di para qué sirve: "[Image 1] is the lead actress, [Image 2] is the cafe, follow the camera of [Video 1]". No confíes en texto escrito dentro de una imagen para decir quién es alguien.
- Usa una línea de tiempo en videos largos. Divide la historia en rangos de segundos enteros sin huecos ("0-5 s", "5-12 s") o en tomas numeradas, y da a cada uno su imagen, cámara, acción, voz y sonido. Con muy poco por rango el modelo improvisa; con demasiado, corta muy seguido.
- Pocos sujetos. De uno a cinco sujetos se mantienen mejor. Varias vistas del mismo sujeto sirven como referencia hasta cinco sujetos; más allá, envía una vista de cada uno.
- Edición (task_type: edit). Di qué cambia y dónde, de qué a qué, con los segundos cuando solo cambia una parte: "In [Video 1], from second 4 to 6 she waves instead of nodding; everything else stays". El resultado conserva la duración y la proporción de la entrada, así que omite seconds y ratio. Los videos de menos de 20 segundos se editan mejor.
- Extensión (task_type: extend). Di la dirección y qué pasa después: "Extend [Video 1] forward: she opens the door and walks into the rain". La proporción sigue al video de entrada.
- Primer y último fotograma. Envíalos como image y last_frame, con las mismas proporciones, para que el video empiece y termine exactamente ahí. Una imagen de referencia nombrada como "the first frame" en el prompt se sigue con menos rigor.
- Storyboards y fotogramas clave. Una hoja de storyboard (15 viñetas o menos, línea simple, sin texto) guía la trama pero no se sigue viñeta por viñeta. Para fotogramas estrictos, envía imágenes separadas y empieza con "Use Images 1 to 5 in order as keyframes".
- Cámara. Los términos habituales de cine funcionan tal cual: push in, pan, tracking shot, orbit, handheld, low angle, long take. Explica los términos poco comunes en unas palabras, y di cuándo ocurre una transición además de cómo.
- Qué dejar fuera. Escribe lo que quieres en lugar de lo que no quieres. Las dos excepciones que funcionan bien: "No subtitles" y "No background music, only ambient sound".
- Voz. Escribe las líneas así: nombre, estado de ánimo entre corchetes y luego las palabras. Un solo idioma por línea. Para palabras que deben aparecer escritas con exactitud en pantalla, envíalas como imagen.
[Image 1] is the fisherman, [Image 2] is his boat. Documentary style, natural light. 0-6 s: wide shot at water level, the boat drifts through morning mist. Slow push in. 6-14 s: medium shot, he pulls the net in, hand over hand. Water drips from the rope. 14-20 s: close-up on his face as he looks at the catch and smiles. Ambient sound only: water, wood, gulls. No subtitles, no background music.
Seedance 2.0
Tres modelos que aceptan la misma solicitud y se diferencian en calidad, velocidad y precio: Seedance 2.0 para la mejor imagen, Seedance 2.0 fast para un equilibrio entre velocidad y costo, Seedance 2.0 mini para el precio más bajo.
| De un vistazo | |
|---|---|
| Duración | De 4 a 15 segundos, o "auto" |
| Resolución | Seedance 2.0: 480p, 720p, 1080p, 4K. Fast y mini: 480p, 720p |
| Proporción | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 |
| Modos | Texto a video; primer fotograma o primer y último fotograma; referencias; editar o extender un video mediante el prompt |
| Referencias | Hasta 9 imágenes, 3 videos y 3 audios. El audio necesita ir con una imagen o un video |
| Sonido | La voz, la música y los efectos se generan junto con la imagen (audio: true) |
| Borradores | No |
| Archivos 4K | H.265 con color de 10 bits. Algunos reproductores no pueden abrirlo; VLC y las versiones actuales de Chrome, Edge y Safari sí |
| Rostros | Las imágenes y videos de referencia que muestran el rostro de una persona real son rechazados |
Cómo escribir prompts
- La fórmula. Sujeto, acción, lugar, luz y color, cámara, estilo, calidad y luego qué evitar. Define primero quién hace qué, después dónde y después cómo se filma.
- Define cada sujeto una vez. Dale dos o tres rasgos fijos (ropa, cabello, complexión) y una etiqueta, y usa siempre la misma etiqueta: "The girl in the red coat from [Image 1]".
- Escribe tomas, no segundos. Numera las tomas: "Shot 1: ... Shot 2: ...", cada una con su cámara, acción, lugar y sonido. Los tiempos exactos como "0-3 s" no se respetan de forma confiable en este modelo.
- Un movimiento de cámara por toma. Push in, o pan, o track. Combinar varios movimientos en una toma vuelve inestable el resultado.
- Describe el movimiento físicamente. Nombra la parte del cuerpo, cuánto y qué tan rápido. El movimiento lento y continuo funciona mejor. Muestra una emoción con el cuerpo ("lowers her head, eyes reddening") en lugar de nombrarla.
- Usa pocas referencias. Cuatro o cinco bastan: una o dos para el personaje, una para el lugar, un video para la cámara, un audio para el ambiente. Más de cuatro personas como referencia reduce la estabilidad, y no se recomiendan varias vistas de una misma persona.
- Rostros que se mantienen. Envía un primer plano de la cabeza y una imagen de cuerpo entero, y di cuál es para el rostro y cuál para la ropa. Pon primero los archivos más importantes.
- Edición. Nombra el video directamente y di qué cambia: "Strictly edit [Video 1]: replace the cat with the lion from [Image 1], keep everything else". No escribas "reference [Video 1]" aquí, o se tratará solo como referencia.
- Extensión. "Extend [Video 1] forward" o "backward", y luego qué pasa. Se pueden unir dos o tres clips con una transición entre ellos, 15 segundos en total. Agrega "end with [Video 1]" para conservar el material original en el resultado.
- Voz y texto. Pon las líneas habladas entre llaves y mantén un solo idioma: She says {We are late}. Para texto en pantalla indica las palabras, cuándo, dónde y cómo aparecen. Usa caracteres comunes.
- Qué evitar. Aun así pueden aparecer subtítulos y logos. "Keep it subtitle-free" y "Do not generate a logo or watermark" los reducen; también ayuda quitar el texto de tus archivos de referencia.
[Image 1] is the girl in the red coat, [Image 2] is the night market. Follow the camera of [Video 1].
Shot 1: wide shot, she walks in between the stalls. Slow push in.
Shot 2: medium shot, she stops at a lantern stall and lifts one lantern. Fixed camera.
Shot 3: close-up, warm light on her face. She says {This one}.
Cinematic, warm tones, rich detail. Keep it subtitle-free. Do not generate a logo or watermark.