Introducción
Asigna funciones a los archivos mediante <Picture 1>, <Video 1> y <Audio 1>, con un límite combinado de 12 elementos. Elige 16:9 o 9:16 y revisa con cuidado la identidad si un video de referencia aporta señales fuertes de movimiento y escena.
| Campo | Valor |
|---|---|
| Entrada | Texto |
| 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í | Identifica cada referencia con su etiqueta de archivo e indica su función. Para un retrato y un producto, escribe que la persona de <Picture 1> sostiene el objeto de <Picture 2>. mínimo 1 caracteres · máximo 32000 caracteres |
reference_image_urls | No | Usa imágenes de referencia para la persona, el objeto o el lugar que debe incorporar la escena. mínimo 1 elementos · máximo 9 elementos |
reference_video_urls | No | Los videos de referencia no deben superar 15 segundos combinados y cada clip cuenta dentro del total de 12 elementos. mínimo 1 elementos · máximo 3 elementos |
reference_audio_urls | No | Indica la función del audio con etiquetas como <Audio 1> y usa grabaciones que tengas derecho a utilizar. Los audios cuentan dentro del límite conjunto de 12 referencias. mínimo 1 elementos · máximo 3 elementos |
aspect_ratio | No | Selecciona 16:9 para una toma horizontal o 9:16 para una vertical. La prueba del hombre con el frasco usó 9:16 e incorporó las dos imágenes. |
resolution | No | La generación con referencias ofrece 480p o 768p. |
duration_seconds | No | Solicita 5–15 segundos de salida, aparte del material de referencia enviado. La factura suma los segundos de salida y los de video de referencia. |
prompt_optimization_mode | No | disabled evita reformular la descripción; turbo y quality lo permiten. Conserva el modo al revisar cómo afecta cada referencia a la escena. |
seed | No | Mantén el seed al agregar o quitar una referencia para comparar. Repetir el seed no promete un clip idéntico ni garantiza que se conserve un rostro concreto. |
Precios
Se cobran los segundos de salida solicitados más los segundos de video de referencia a la tarifa publicada; las dos imágenes iniciales están incluidas y cada imagen desde la tercera añade un cargo individual.
| Especificación | Precio |
|---|---|
| $0.102 / 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 crear video con referencias
HeyGen Video 1.0 combina imágenes, videos y audios de referencia en una escena de 5–15 segundos en 480p o 768p. El endpoint acepta hasta 12 elementos en total y ofrece 16:9 o 9:16, con videos de referencia limitados a 15 segundos combinados.
Haz una solicitud con una persona y un producto
Usa heygen/video-1/reference-to-video en un POST a https://api.spicyapi.ai/api/v1/jobs/createTask. Agrega Authorization: Bearer YOUR_SPICY_API_KEY y Content-Type: application/json, y reemplaza las dos URL de ejemplo por imágenes que tengas derecho a utilizar.
{
"model": "heygen/video-1/reference-to-video",
"input": {
"prompt": "The man in his thirties from <Picture 1>, in a pale blue shirt, holds the dropper bottle from <Picture 2> beside his face in a softly lit bathroom. Vertical framing, static camera, warm light, composed mood.",
"reference_image_urls": [
"https://example.com/person.jpg",
"https://example.com/bottle.jpg"
],
"duration_seconds": 5,
"resolution": "480p",
"aspect_ratio": "9:16",
"prompt_optimization_mode": "disabled",
"seed": 21
}
}
Esta solicitud propuesta demuestra cómo usar las etiquetas; no es el cuerpo original de la prueba. Utiliza textos, voces e imágenes de personas que tengas permiso para usar y nunca suplantes a una persona real.
Lee el resultado generado
Recoge data.taskId después del envío y recupera la tarea mediante GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID. El JSON abreviado siguiente ilustra una tarea en cola y un resultado correcto; los ID y los enlaces de archivos son de muestra.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/reference-scene.mp4"}]
}
}
}
Consulta el contrato completo de tareas para los detalles de integración. Revisa la aportación prevista de cada referencia en el resultado, sin dar por hecho que una tarea correcta conservó todas las entradas por igual.
Asigna una función a cada referencia
Identifica cada entrada con su etiqueta e indica qué aporta a la toma. La documentación de HeyGen explica que cada lista multimedia lleva una numeración independiente: una imagen se identifica con <Picture 1>, un video con <Video 1> y un audio con <Audio 1>.
| Parámetro | Uso y límite |
|---|---|
prompt | Describe la nueva escena y menciona los archivos enviados mediante sus etiquetas. |
reference_image_urls | Imágenes de personas, productos o lugares; cada imagen desde la tercera agrega un cargo. |
reference_video_urls | Referencias de movimiento o escena, hasta 15 segundos combinados; sus segundos también se cobran. |
reference_audio_urls | Clips de audio con una función asignada mediante etiquetas como <Audio 1>. |
| Listas combinadas | Hasta 12 referencias entre los tres tipos de archivo. |
duration_seconds | Duración de salida solicitada de 5–15 segundos. |
resolution | 480p o 768p. |
aspect_ratio | 16:9 o 9:16. |
prompt_optimization_mode | disabled, turbo o quality; los dos últimos modos pueden reformular la descripción. |
seed | Mantenlo fijo para comparar una modificación, sin promesa de una generación idéntica. |
Aprovecha las dos pruebas con referencias
La prueba de dos imágenes incorporó a un hombre y un frasco gotero en un resultado 9:16, mostrando al hombre sosteniendo ese frasco. El procesamiento tardó unos 158 segundos; es una ejecución medida, sin constituir un objetivo de servicio para la generación con referencias.
La prueba de referencias mixtas siguió de cerca el video y no conservó el rostro de la imagen. Sus entradas eran una imagen, un video de cuatro segundos y audio. Si importa la persona de una foto concreta, evita un clip de movimiento dominante; las imágenes solas o image-to-video ofrecen un punto de partida más acotado para evaluar.
- Empieza con un retrato y una imagen de producto si esos son los elementos que deben aparecer.
- Define sus funciones explícitamente con
<Picture 1>y<Picture 2>. - Agrega un video cuando realmente necesites su movimiento o escena y vuelve a comprobar el rostro.
- Conserva el seed y el ajuste de reescritura del prompt al comparar un cambio.
Incluye las referencias en el cálculo del cobro
La generación con referencias cobra los segundos de salida solicitados más los de video de referencia, al precio mostrado en esta página. Cada imagen de referencia desde la tercera añade un cargo individual. Si pides cinco segundos de salida y aportas cuatro segundos de video de referencia, cuenta ambas duraciones al planear la solicitud; el material de referencia no sustituye tiempo de salida solicitado.
Las pruebas proporcionadas de cinco segundos devolvieron archivos de 5,18–5,26 segundos tras redondear cuadros. La parte de salida sigue facturándose como los cinco segundos pedidos, aparte del uso de videos de referencia.
Diagnostica problemas y selecciona otro endpoint
Comprueba el total de archivos, la duración de video y los ajustes de salida antes de enviar una solicitud con referencias. Más de 12 elementos, más de 15 segundos de video de referencia, una proporción distinta de 16:9 o 9:16 o una resolución superior a 768p quedan fuera de los ajustes admitidos en esta página. Examina el error recibido en tareas rechazadas o fallidas, en vez de atribuir un resultado ausente a un problema de identidad.
Usa imagen a video para animar una foto concreta o pedir salida nativa en 1080p o 2k. Usa texto a video cuando no necesites referencias. HeyGen Avatar IV se orienta a fotos que hablan y HeyGen Video Translate es el modelo relacionado que debes revisar para traducción.
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/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p",
"reference_image_urls": [
"https://example.com/reference.png"
]
}
}'
# 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.

