En esta página
Hailuo 2.3 API
Crea tareas de texto a vídeo e imagen a vídeo de Hailuo 2.3 mediante una API asíncrona. Hailuo 2.3 Fast ofrece menor latencia para imagen a vídeo.
REST API · v1 · Tareas asíncronas
Envía tu primera solicitud
Crea una tarea con una clave idempotente, guarda el task ID y consúltalo hasta obtener el resultado.
- 1
Crear una API Key
Genera una clave en tu cuenta Imya.
- 2
Crear una tarea
Elige Hailuo 2.3 o Fast y envía las entradas.
- 3
Obtener el resultado
Consulta hasta que termine o falle.
Autenticación e idempotencia
Envía la API Key como Bearer token y una Idempotency-Key única en cada POST para reintentar sin duplicar cargos.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCrear una generación de vídeo
Crea una tarea asíncrona y devuelve credits_reserved calculado en tiempo real.
/v1/videos/generations# Text to video (Hailuo 2.3)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-t2v-order-001" \
-d '{
"model": "hailuo-2.3",
"prompt": "A paper boat crossing a rain-soaked neon street",
"duration": 6,
"resolution": "720p",
"prompt_optimizer": true
}'
# Image to video (Hailuo 2.3 Fast)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-i2v-order-001" \
-d '{
"model": "hailuo-2.3-fast",
"prompt": "Slow camera push-in with warm moving light",
"image_url": "https://cdn.example.com/first-frame.jpg",
"duration": 6,
"resolution": "1080p"
}'Compatibilidad Beta anterior
Las integraciones existentes pueden usar POST /api/video/generate con x-api-key e Idempotency-Key. Las nuevas deben usar /v1/videos/generations.
curl https://imya.ai/api/video/generate \
-H "x-api-key: YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: legacy-hailuo-order-001" \
-d '{
"modelKey": "hailuo-2-3-standard-t2v",
"prompt": "A paper boat crossing a rain-soaked neon street",
"resolution": "720p",
"outputDurationSec": 6,
"promptExtend": true
}'Consultar una tarea
Devuelve estado, créditos finales, MP4 o error seguro. Consulta con al menos 5 segundos de intervalo y descarga pronto las URL temporales.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Parámetros
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| model | string | Sí | hailuo-2.3 o hailuo-2.3-fast. |
| prompt | string | Sí | Instrucciones de hasta 5.000 caracteres. |
| image_url | string | Condicional | Primer fotograma HTTPS público. Obligatorio en Fast. |
| duration | number | No | 6 o 10 segundos. Predeterminado: 6. |
| resolution | string | No | 720p o 1080p. 1080p solo admite 6 segundos. |
| prompt_optimizer | boolean | No | Optimiza el prompt. Predeterminado: true. |
Respuestas
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 225
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:02:18.000Z",
"credits_reserved": 225,
"credits_used": 225,
"data": [
{
"url": "https://media.example.com/generated/example.mp4"
}
]
}Créditos en tiempo real
El servidor calcula credits_reserved según modelo, flujo, resolución, duración y plan. Los números de ejemplo solo muestran la forma; usa siempre la respuesta real.
Estado
pendingLa tarea fue aceptada y espera para comenzar.
processingEl modelo está generando el vídeo.
succeededLa generación terminó y data contiene el MP4.
failedLa generación falló. Lee el error seguro.
Errores
400Falta Idempotency-Key o JSON inválido.
401API Key ausente o inválida.
402Créditos insuficientes.
403Cuenta de API desactivada.
404Tarea inexistente o de otra cuenta.
409Clave reutilizada con otro cuerpo.
413Cuerpo mayor de 64 KiB.
415Content-Type debe ser application/json.
422Modelo, prompt, imagen, duración o resolución inválida.
429Límite de velocidad o concurrencia alcanzado.
5xxNo se pudo completar o enviar.
Contrato común de la API pública de Imya
Estas reglas se aplican a todos los endpoints públicos de generación. Los campos y precios específicos están en la tabla del modelo.
Facturación y reintentos seguros
Al aceptar una tarea nueva se descuentan de forma atómica los créditos exactos de credits_reserved. Repetir la misma Idempotency-Key y cuerpo devuelve la tarea original sin otro cargo.
Tiempo límite y reembolsos
Una tarea que no termina en 30 minutos falla. Los créditos elegibles se devuelven una sola vez y conservan su caducidad original.
Límites de velocidad y concurrencia
Cada API Key admite 120 solicitudes por 60 segundos; una cuenta puede ejecutar cinco tareas de imagen o tres de vídeo. Respeta Retry-After en 429.
Consulta y propiedad
Consulta GET /v1/tasks/{id} con el id devuelto y al menos 5 segundos de intervalo. Solo la cuenta creadora puede leer la tarea; no hay webhooks, SDK ni envíos batch.
Errores y seguridad
Los errores públicos eliminan credenciales, URL internas y detalles de infraestructura. Un prompt inseguro puede rechazarse con prompt_blocked.
Conservación de imágenes
Las cuentas gratis conservan imágenes 7 días y las activas de pago o Lifetime hasta 30. Después, status es failed y error.code es media_deleted.
Guía de integración en producción de Hailuo 2.3 API
Diseña la integración de Hailuo 2.3 como un sistema de tareas asíncronas recuperable, no como una solicitud HTTP larga. Guarda siempre el id de Imya y haz deterministas los reintentos.
Elegir parámetros del contrato
Valida cada solicitud con la tabla de esta página. Empieza con la configuración mínima y aumenta calidad, tamaño, duración o referencias solo cuando el producto lo necesite.
Permite solo combinaciones documentadas de duración, resolución, relación, audio y medios.
Diseñar un flujo asíncrono recuperable
Envía la tarea de vídeo, guarda id y consulta GET /v1/tasks/{id} con al menos 5 segundos de intervalo. Los status públicos son pending, processing, succeeded y failed y el límite es 30 minutos. No hay webhooks, SDK ni batch.
- 01Guarda id, status, credits_reserved e identidad de solicitud antes de actualizar la UI.
- 02Aplica backoff, respeta Retry-After en 429 y no conviertas un error de transporte en otra tarea de pago.
- 03Limita a tres tareas de vídeo por cuenta y 120 solicitudes por 60 segundos y API Key.
Facturación y reintentos deterministas
Al aceptar se descuenta credits_reserved. Guarda una Idempotency-Key por creación; repetirla con el mismo cuerpo devuelve la tarea original.
Los fallos elegibles se reembolsan una vez con su caducidad original. refund_pending indica liquidación y credits_refunded la confirma.
Proteger credenciales, propiedad y medios
Guarda las API Key en el servidor y asocia id al usuario autenticado. Registra identificadores de soporte sin exponer prompts, URL privadas ni credenciales.
No presupongas una retención fija de vídeo; copia pronto lo necesario a tu almacenamiento con consentimiento.
Lista de producción
- Valida campos del modelo.
- Guarda Idempotency-Key y cuerpo.
- Persiste estado y consulta cada 5 segundos o más.
- Aplica concurrencia y velocidad.
- Trata los cuatro status y los códigos de liquidación.
- Mantén credenciales en el servidor y define retención.
Preguntas frecuentes
¿Cada cuánto consulto?
Espera al menos 5 segundos y usa backoff.
¿Cuándo se cobran créditos?
Al aceptar se descuenta credits_reserved.
¿Un reintento cobra dos veces?
No con la misma Idempotency-Key y cuerpo.
¿Cómo trato un fallo final?
Muestra un error seguro, conserva id y comprueba credits_refunded.
¿Quieres probar Hailuo?
Compara Fast, estándar y entradas de texto o imagen en la herramienta alojada.
Probar Hailuo 2.3 online