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.

CampoTipo
modelstringObligatorio. El id de un modelo de video.
promptstringObligatorio (salvo con draft_id). De 3 a 20.000 caracteres.
secondsinteger | "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".
resolutionstring480p, 720p (por defecto), 1080p o 4k; solo las resoluciones que ofrece el modelo (ver la referencia de modelos).
ratiostring16: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.
imagestringPrimer fotograma: un enlace a una imagen o una data URL (first_frame se acepta como el mismo campo).
last_framestringÚltimo fotograma, se usa junto con image.
audiobooleanGenerar sonido con el video. Por defecto true.
seedinteger-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_fixedbooleantrue mantiene la cámara fija.
bitrate_modestringstandard (por defecto) o high. high puede fallar cuando el modelo está ocupado; en ese caso se reembolsa.
return_last_framebooleantrue: el último fotograma se conserva como imagen en GET /videos/{id}/last_frame.
reference_imagesstring[]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_videosstring[]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_audiosstring[]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_typestringCon reference_videos: auto, reference, edit o extend (Seedance 2.5). edit y extend siguen al video de entrada; omite seconds y ratio.
draftbooleanSeedance 2.5: true genera una vista previa en 480p al precio de 480p. resolution debe ser 480p.
draft_idstringConvierte 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ónDe 4 a 30 segundos, o "auto" para que el modelo elija
Resolución480p, 720p, 1080p
Proporción21:9, 16:9, 4:3, 1:1, 3:4, 9:16 o adaptive (sigue a la entrada)
ModosTexto a video; primer fotograma o primer y último fotograma; referencias; editar un video; extender un video
ReferenciasHasta 30 imágenes, 10 videos y 10 audios. Se acepta audio solo
SonidoLa voz, la música y los efectos se generan junto con la imagen (audio: true)
BorradoresSí: 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.
Prompt de ejemplo
[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ónDe 4 a 15 segundos, o "auto"
ResoluciónSeedance 2.0: 480p, 720p, 1080p, 4K. Fast y mini: 480p, 720p
Proporción21:9, 16:9, 4:3, 1:1, 3:4, 9:16
ModosTexto a video; primer fotograma o primer y último fotograma; referencias; editar o extender un video mediante el prompt
ReferenciasHasta 9 imágenes, 3 videos y 3 audios. El audio necesita ir con una imagen o un video
SonidoLa voz, la música y los efectos se generan junto con la imagen (audio: true)
BorradoresNo
Archivos 4KH.265 con color de 10 bits. Algunos reproductores no pueden abrirlo; VLC y las versiones actuales de Chrome, Edge y Safari sí
RostrosLas 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.
Prompt de ejemplo
[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.