Introducción
Envía image_url junto con un prompt que describa el movimiento que quieres agregar. Las pruebas con fotos conservaron a la persona y la composición en 480p, 1080p y 2k; selecciona la resolución nativa según las dimensiones de entrega.
| Campo | Valor |
|---|---|
| Entrada | Imagen |
| Salida | Video |
| Desarrollador y modelo | HeyGen — HeyGen Video 1.0; nombre de API heygen-video-1 |
| Nombres públicos de los endpoints | heygen/video-1/text-to-video; heygen/video-1/image-to-video; heygen/video-1/reference-to-video |
| Duración solicitada | 5–15 segundos en los tres endpoints |
| Resoluciones para generar con texto | 480p o 768p; la salida incluye audio AAC estéreo |
| Resoluciones para animar fotos | 480p, 768p, 1080p, 2k — resoluciones nativas |
| Dimensiones medidas al animar imágenes | 832×480 en 480p; 1890×1080 en 1080p; 2688×1536 en 2k |
| Ajustes de salida con referencias | 480p o 768p; relación de aspecto 16:9 o 9:16 |
| Límite de archivos de referencia | Hasta 12 elementos combinados; videos de referencia de hasta 15 segundos en total |
| Modos de reescritura del prompt | disabled, turbo, quality |
| Duración medida de los archivos | Las solicitudes de cinco segundos devolvieron 5,18–5,26 segundos; se cobraron cinco segundos solicitados |
| Unidad de cobro | Segundos de salida solicitados; también se cuentan los segundos de video de referencia y se cobra por imagen a partir de la tercera |
Funciones y aspectos destacados
Una escena escrita se convierte en un clip
Text-to-video crea una escena de 5–15 segundos en 480p o 768p e incluye una pista de audio. Nuestra ejecución de cinco segundos en 480p devolvió 832×480 a 24 fps con AAC estéreo tras unos 10 segundos de procesamiento. Ese dato corresponde a una ejecución y no promete un plazo de entrega.
Conserva a la persona del original
Image-to-video combina image_url con un prompt de movimiento para animar una foto. Las pruebas en 480p, 1080p y 2k conservaron a la persona y la composición; la ejecución en 2k entregó 2688×1536 píxeles. Elige esta entrada si necesitas continuidad con una fotografía concreta.
Asigna por separado la persona y el objeto
Reference-to-video combina imágenes, videos y audios hasta un total de 12 elementos. La prueba con retrato y frasco produjo una toma vertical del hombre sosteniendo ese frasco. Otra ejecución con referencias mixtas siguió de cerca el video y perdió el rostro de la foto, por lo que conviene dar una función clara a cada entrada.
Modifica el prompt conservando los ajustes
Los controles seed y prompt_optimization_mode ayudan a organizar las revisiones. Mantén un seed fijo al comparar un cambio; esto no garantiza un resultado idéntico. Selecciona disabled para evitar la reescritura o prueba turbo o quality si deseas que el modelo reformule la descripción.
Parámetros de la solicitud
| Parámetro | Obligatorio | Descripción |
|---|---|---|
prompt | Sí | Especifica el cambio que buscas, como un giro de cabeza o una mirada, e indica qué debe seguir siendo reconocible. mínimo 1 caracteres · máximo 32000 caracteres |
image_url | Sí | Proporciona la foto con la persona y la composición que deseas animar. Antes de describir el movimiento, verifica que el encuadre ya corresponda a la toma prevista. |
resolution | No | Selecciona 480p, 768p, 1080p o 2k en minúsculas. Las salidas medidas fueron 832×480, 1890×1080 y 2688×1536 para 480p, 1080p y 2k, respectivamente. |
duration_seconds | No | Fija una duración solicitada de entre 5 y 15 segundos. El cobro sigue esa solicitud aunque el redondeo a cuadros completos alargue un poco el archivo. |
prompt_optimization_mode | No | Usa disabled para evitar la reformulación o turbo o quality para permitirla. Compara el movimiento manteniendo un mismo modo antes de cambiar la resolución. |
seed | No | Un seed fijo ayuda a evaluar un cambio del prompt de movimiento a la vez. Sirve de apoyo para comparar, sin garantizar que el clip recibido sea idéntico. |
Precios
Se cobra cada segundo de salida solicitado a la tarifa publicada para la resolución nativa elegida; el tiempo extra por redondeo de cuadros no agrega segundos de salida a la factura.
| Especificación | Precio |
|---|---|
| $0.03 / segundo |
| $0.054 / segundo |
| $0.144 / segundo |
| $0.144 / segundo |
Casos de uso
Visualizar una escena antes del rodaje
Envía una descripción de una persona ceramista de unos treinta años, con delantal de lona, que gira hacia un estante en un taller soleado. Una solicitud de cinco segundos en 480p entrega un clip conceptual con audio para revisar antes del rodaje.
Dar un gesto breve a un retrato
Proporciona un retrato con licencia de una mujer de unos treinta años con vestido de noche junto a una ventana; pide un giro de cabeza y un movimiento lento de cámara. Image-to-video devuelve una animación corta guiada por esa foto; compara a la persona y la composición con el original.
Mostrar un presentador con tu producto
Adjunta el retrato de un hombre como <Picture 1> y la foto de un frasco gotero como <Picture 2>; solicita una toma 9:16 donde sostenga el frasco. La prueba con dos imágenes incorporó ambas referencias y tardó unos 158 segundos.
Probar una idea guiada por movimiento
Proporciona un retrato, un clip de movimiento de cuatro segundos y una referencia de audio con funciones definidas en el prompt. Nuestra ejecución mixta siguió de cerca el movimiento y la escena del video, pero no conservó el rostro del retrato; usa esta combinación si el movimiento pesa más que ese rostro.
Entregar una animación de foto de mayor tamaño
Combina una foto original con un prompt de movimiento moderado y selecciona 1080p o 2k en image-to-video. Las pruebas de cinco segundos entregaron salidas nativas de 1890×1080 y 2688×1536 y conservaron a la persona original.
Guía de prompts y consejos prácticos
Relaciona el endpoint con el material
Elige text-to-video para una escena escrita, image-to-video para una foto o reference-to-video para varios archivos originales. La animación de fotos ofrece 1080p y 2k cuando necesitas esas resoluciones.
Escribe una escena bien delimitada
Describe la persona, el vestuario, el lugar, la iluminación y una acción visible. Si usas referencias, vincula la acción con etiquetas como <Picture 1> y <Picture 2>, y utiliza textos, voces e imágenes de personas cuyos derechos de uso tengas.
Envía la tarea de generación
Haz POST a https://api.spicyapi.ai/api/v1/jobs/createTask con autenticación Bearer y un JSON como {"model":"heygen/video-1/text-to-video","input":{"prompt":"A potter in their thirties turns toward a shelf.","
duration_seconds":5,"resolution":"480p"}}.Recupera el clip y revísalo
Guarda data.taskId y consulta GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID para comprobar el resultado. Revisa el video recibido y mantén fijo el seed al probar una modificación; repetir los ajustes no garantiza un resultado idéntico.
HeyGen Video 1.0 API para convertir una imagen en video
HeyGen Video 1.0 anima una foto durante 5–15 segundos, con resoluciones nativas de 480p, 768p, 1080p y 2k. Las pruebas con imágenes mantuvieron a la persona y la composición originales, así que este endpoint es un punto de partida práctico cuando la fotografía ya define la toma.
Envía la foto y el movimiento
Envía heygen/video-1/image-to-video a https://api.spicyapi.ai/api/v1/jobs/createTask con el JSON de abajo. Configura Authorization: Bearer YOUR_SPICY_API_KEY y Content-Type: application/json, y reemplaza la URL por la de tu imagen.
{
"model": "heygen/video-1/image-to-video",
"input": {
"image_url": "https://example.com/portrait.jpg",
"prompt": "The woman in her thirties in the supplied portrait, wearing a cream blouse, turns gently toward the window. Retain the source person and composition, soft morning light, calm mood, static camera.",
"duration_seconds": 5,
"resolution": "1080p",
"prompt_optimization_mode": "disabled",
"seed": 7
}
}
La muestra ilustra una animación propuesta de retrato, sin constituir otro resultado de prueba. Usa una fotografía y una imagen de persona que tengas derecho a utilizar.
Obtén el video devuelto
El envío devuelve un ID de tarea que permite recuperar el resultado mediante GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID. Estas respuestas abreviadas muestran los campos relevantes con valores ilustrativos, sin corresponder a otra ejecución.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/animated-portrait.mp4"}]
}
}
}
La documentación de tareas de SpicyAPI describe la respuesta completa. Guarda el archivo recibido y compara a la persona en movimiento y el encuadre con la fotografía de entrada.
Configura los parámetros de animación
Envía image_url junto con el prompt y elige la duración y una resolución nativa. Los ajustes siguientes distinguen la foto de entrada del movimiento que deseas agregar con el modelo.
| Parámetro | Qué enviar |
|---|---|
image_url | La foto original que define a la persona y la composición. |
prompt | La acción, el comportamiento de cámara, la iluminación y la dirección de escena. |
duration_seconds | Una duración de salida solicitada de 5 a 15 segundos. |
resolution | 480p, 768p, 1080p o 2k; escribe 2k en minúsculas en el JSON. |
prompt_optimization_mode | disabled evita reescribir; turbo y quality lo permiten. |
seed | Un control para comparar revisiones, sin promesa de resultados idénticos. |
Conserva lo que establece la fotografía
Describe un cambio pequeño respecto a la pose original, en vez de reconstruir toda la escena con palabras. Un giro de cabeza o una mirada ofrecen una acción clara que puedes juzgar al comparar la persona y el encuadre con la foto fija.
HeyGen indica que image-to-video comienza con la imagen proporcionada. Su guía de prompts recomienda movimientos de cámara moderados y puntos de contacto explícitos para los gestos. Son descripciones del desarrollador; la evidencia disponible aquí es la continuidad de la foto y las dimensiones nativas registradas en las pruebas.
- Selecciona una foto con la persona y el entorno que deseas conservar.
- Escribe una instrucción de movimiento e indica qué elementos visuales importan.
- Revisa una prueba en 480p para evaluar la apariencia de la persona y la acción.
- Prueba 1080p o 2k cuando la dirección de escena resulte útil, manteniendo el seed para comparar.
Compara los tamaños medidos
Las pruebas de foto de cinco segundos produjeron salidas nativas en las resoluciones solicitadas y conservaron a la persona original. Estas mediciones describen la composición probada, sin definir dimensiones universales para todas las fotografías.
| Resolución solicitada | Salida medida |
|---|---|
480p | 832×480 |
1080p | 1890×1080 |
2k | 2688×1536 |
También se admite 768p, pero no tenemos dimensiones medidas en una prueba de imagen para esa resolución. Tampoco contamos con un tiempo de procesamiento específico de imagen, por lo que los aproximadamente 10 segundos de la ejecución con texto no deben usarse como estimación para este endpoint.
Calcula el cobro y revisa la duración
La animación de imágenes cobra los segundos de salida solicitados a la tarifa que aparece en esta página para la resolución elegida. Los archivos pedidos de cinco segundos duraron 5,18–5,26 segundos en las pruebas por el redondeo a cuadros completos, mientras que la duración de salida facturada siguió siendo de cinco segundos. Los píxeles adicionales resuelven necesidades de dimensiones de entrega; revisa el movimiento por separado antes de generar otra versión.
Comprueba errores de entrada y alternativas
Si se rechaza una solicitud, comprueba image_url, el prompt y la escritura de la resolución. Mantén la duración entre 5 y 15 segundos y escribe 2k para esa resolución; consulta el esquema actual y el error de tarea recibido antes de cambiar campos. Si el resultado altera un gesto importante, necesita revisión visual aunque la tarea haya terminado correctamente.
Elige texto a video cuando quieras una escena a partir de palabras sin una foto original. Elige referencias a video para asignar funciones distintas a un retrato y un producto; recuerda que sus videos de entrada pueden dominar la identidad. Para una foto que deba hablar como avatar, revisa HeyGen Avatar IV.
Inicio rápido de la API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "heygen/video-1/image-to-video",
"input": {
"duration_seconds": 5,
"image_url": "https://example.com/reference.png",
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Consulta la referencia de la API para autenticación, el esquema completo, sondeo y gestión de errores.

