Introducción
Describe en prompt el sujeto, el lugar, la acción y el sonido deseado; luego elige duration_seconds y una resolución. Usa seed para comparar revisiones y prompt_optimization_mode para decidir si la descripción puede reescribirse.
| 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í | Describe quién aparece, qué se mueve, dónde ocurre la toma y qué debe escucharse. Una acción y una vista de cámara concretas facilitan la evaluación de la escena recibida. mínimo 1 caracteres · máximo 32000 caracteres |
aspect_ratio | No | Elige una proporción entre las opciones actuales de este endpoint antes de enviar la solicitud. |
resolution | No | Elige 480p o 768p para generar con texto. |
duration_seconds | No | Solicita entre 5 y 15 segundos. Los archivos pedidos de cinco segundos duraron 5,18–5,26 segundos en las pruebas tras redondear cuadros, y se cobraron cinco segundos de salida. |
prompt_optimization_mode | No | Configura disabled para evitar que el prompt se reescriba. Tanto turbo como quality permiten reformular la descripción; mantén esa elección al comparar prompts. |
seed | No | Conserva el seed y cambia un detalle de la escena para facilitar la comparación. Usar el mismo seed no garantiza un resultado idéntico. |
Precios
Se cobra por segundo de salida solicitado a la tarifa publicada para 480p o 768p; el redondeo a cuadros completos no aumenta la duración solicitada facturable.
| Especificación | Precio |
|---|---|
| $0.03 / segundo |
| $0.054 / 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 generar video con texto
HeyGen Video 1.0 transforma una escena escrita en un clip de 5–15 segundos en 480p o 768p, con una pista de audio AAC estéreo. Este endpoint necesita un prompt en lugar de una imagen, por lo que sirve para visualizar una toma antes de tener fotografías o material grabado.
Solicita una escena
Llama a heygen/video-1/text-to-video enviando este JSON por POST a https://api.spicyapi.ai/api/v1/jobs/createTask. Incluye Authorization: Bearer YOUR_SPICY_API_KEY y Content-Type: application/json; la escena siguiente es una propuesta de solicitud, no una reproducción de nuestra prueba medida.
{
"model": "heygen/video-1/text-to-video",
"input": {
"prompt": "A potter in their thirties, wearing a blue work shirt, turns toward a shelf in a sunlit studio. Static medium shot, warm side light, thoughtful mood. Sound: quiet studio ambience, no music.",
"duration_seconds": 5,
"resolution": "480p",
"prompt_optimization_mode": "disabled",
"seed": 42
}
}
Recupera la respuesta de la tarea
Lee data.taskId en la respuesta del envío y consulta GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID con tu clave Bearer. Un resultado completado correctamente expone la URL del archivo generado; los ejemplos omiten campos ajenos al caso y usan ID y URL de muestra.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/generated-scene.mp4"}]
}
}
}
Consulta la guía de la API de tareas para conocer el contrato completo de solicitud y respuesta. Abre la URL del archivo para revisar la imagen y escuchar la pista generada.
Elige los controles de la escena
Los siguientes controles definen la duración, el tamaño de imagen y el tratamiento del prompt. Selecciona una relación de aspecto entre las opciones actuales del endpoint cuando el formato de entrega sea relevante.
| Parámetro | Función y ajustes admitidos |
|---|---|
prompt | Describe el sujeto, la acción visible, el lugar, la luz y el sonido deseado. |
duration_seconds | Solicita 5–15 segundos de salida. |
resolution | Elige 480p o 768p; este endpoint no tiene resolución 1080p. |
aspect_ratio | Selecciona un formato de cuadro admitido en los controles actuales del endpoint. |
prompt_optimization_mode | disabled, turbo o quality; los dos últimos permiten reescribir el texto. |
seed | Mantenlo fijo al comparar una modificación del prompt; no se garantiza una salida idéntica. |
Dirige una toma de acción acotada
Sitúa una acción visible en un lugar claro antes de agregar instrucciones de cámara. Por ejemplo, describe a una persona que gira hacia un estante, en vez de pedir un recorrido por la habitación, un gesto y un cambio de escena en el mismo clip corto.
HeyGen recomienda indicar la disposición de cámara, la iluminación y las fuentes de sonido. Su guía favorece las escenas acotadas y señala límites con movimientos de manos complejos y textos largos en pantalla. Tómalo como orientación del desarrollador y revisa esos detalles en tu propio resultado.
- Nombra la persona, la ropa, el lugar y la acción, en ese orden.
- Agrega una vista concreta, como un plano medio fijo con luz de ventana.
- Describe los sonidos que quieres e indica que no haya música cuando corresponda.
- Compara una revisión con el mismo seed y modo de reescritura antes de modificar otros ajustes.
Interpreta la medición obtenida
La prueba neutral con texto pidió cinco segundos en 480p y devolvió un video de 832×480 a 24 fps con audio AAC estéreo. Esa ejecución tardó unos 10 segundos; no establece un tiempo habitual de finalización para cualquier escena.
Las solicitudes de cinco segundos de las pruebas proporcionadas produjeron archivos de 5,18–5,26 segundos, redondeados a cuadros completos. Si tu línea de tiempo requiere un punto de corte exacto, revisa la duración del archivo y recórtalo en el editor.
Entiende la unidad de facturación
La generación con texto se cobra por segundo de salida solicitado, con el precio vigente que muestra esta página para la resolución elegida. Una solicitud de cinco segundos cuenta como cinco segundos de salida aunque el redondeo de cuadros alargue un poco la reproducción. Prueba la composición en 480p y luego considera 768p según la entrega que necesites; es una sugerencia de trabajo, sin una clasificación medida de calidad.
Revisa los límites y elige otra tarea
Mantén la solicitud entre 5 y 15 segundos y elige 480p o 768p antes de enviarla. Ante un error de entrada, compara los nombres de campos y la resolución con la tabla y el esquema actual; si falla la tarea, examina errorCode y errorMessage antes de considerar un video como terminado.
Usa imagen a video si una foto concreta debe guiar la persona y la composición o si necesitas 1080p o 2k nativos. Usa referencias a video para personas, productos o movimientos enviados por separado. Para una foto que hable, revisa HeyGen Avatar IV; para una tarea de traducción, consulta HeyGen Video Translate.
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/text-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"resolution": "768p",
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt_optimization_mode": "disabled"
}
}'
# 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.

