Nesta página
Hailuo 2.3 API
Crie tarefas de texto para vídeo e imagem para vídeo do Hailuo 2.3 por uma API assíncrona. Hailuo 2.3 Fast oferece menor latência para imagem em vídeo.
REST API · v1 · Tarefas assíncronas
Envie sua primeira solicitação
Crie uma tarefa com chave idempotente, salve o task ID e consulte até o resultado.
- 1
Criar uma API Key
Gere uma chave na conta Imya.
- 2
Criar uma tarefa
Escolha Hailuo 2.3 ou Fast e envie as entradas.
- 3
Obter o resultado
Consulte até concluir ou falhar.
Autenticação e idempotência
Envie a API Key como Bearer token e uma Idempotency-Key única em todo POST para repetir sem duplicar cobranças.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCriar uma geração de vídeo
Cria uma tarefa assíncrona e retorna credits_reserved calculado em tempo 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"
}'Compatibilidade Beta anterior
Integrações existentes podem usar POST /api/video/generate com x-api-key e Idempotency-Key. Novas integrações devem 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 uma tarefa
Retorna status, créditos finais, MP4 ou erro seguro. Consulte com intervalo mínimo de 5 segundos e baixe logo URLs temporárias.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | string | Sim | hailuo-2.3 ou hailuo-2.3-fast. |
| prompt | string | Sim | Instruções de até 5.000 caracteres. |
| image_url | string | Condicional | Primeiro quadro HTTPS público. Obrigatório no Fast. |
| duration | number | Não | 6 ou 10 segundos. Padrão: 6. |
| resolution | string | Não | 720p ou 1080p. 1080p aceita apenas 6 segundos. |
| prompt_optimizer | boolean | Não | Otimiza o prompt. Padrão: true. |
Respostas
{
"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 em tempo real
O servidor calcula credits_reserved por modelo, fluxo, resolução, duração e plano. Os números de exemplo mostram apenas o formato; use sempre a resposta real.
Status
pendingA tarefa foi aceita e aguarda início.
processingO modelo está gerando o vídeo.
succeededA geração terminou e data contém o MP4.
failedA geração falhou. Leia o erro seguro.
Erros
400Idempotency-Key ausente ou JSON inválido.
401API Key ausente ou inválida.
402Créditos insuficientes.
403Conta de API desativada.
404Tarefa inexistente ou de outra conta.
409Chave reutilizada com outro corpo.
413Corpo maior que 64 KiB.
415Content-Type deve ser application/json.
422Modelo, prompt, imagem, duração ou resolução inválida.
429Limite de velocidade ou concorrência atingido.
5xxNão foi possível concluir ou enviar.
Contrato comum da API pública da Imya
Estas regras valem para todos os endpoints públicos de geração. Campos e preços específicos ficam na tabela do modelo.
Cobrança e repetição segura
Ao aceitar uma nova tarefa, os créditos exatos de credits_reserved são descontados atomicamente. Repetir a mesma Idempotency-Key e corpo retorna a tarefa original sem nova cobrança.
Prazo e reembolsos
Uma tarefa que não conclui em 30 minutos falha. Créditos elegíveis são devolvidos uma vez e mantêm a validade original.
Limites de velocidade e concorrência
Cada API Key aceita 120 solicitações por 60 segundos; uma conta executa até cinco tarefas de imagem ou três de vídeo. Respeite Retry-After no 429.
Consulta e propriedade
Consulte GET /v1/tasks/{id} com o id retornado e intervalo mínimo de 5 segundos. Só a conta criadora pode ler a tarefa; webhooks, SDK e envio batch não estão disponíveis.
Erros e segurança
Erros públicos removem credenciais, URLs internas e detalhes de infraestrutura. Um prompt inseguro pode ser rejeitado com prompt_blocked.
Retenção de imagens
Contas grátis mantêm imagens por 7 dias e contas pagas ativas ou Lifetime por até 30. Depois, status é failed e error.code é media_deleted.
Guia de integração em produção da Hailuo 2.3 API
Projete a integração do Hailuo 2.3 como um sistema de tarefas assíncronas recuperável, não como uma solicitação HTTP longa. Salve sempre o id da Imya e torne as repetições determinísticas.
Escolher parâmetros do contrato
Valide cada solicitação com a tabela desta página. Comece com a configuração mínima e aumente qualidade, tamanho, duração ou referências somente quando necessário.
Permita apenas combinações documentadas de duração, resolução, proporção, áudio e mídia.
Projetar um fluxo assíncrono recuperável
Envie a tarefa de vídeo, salve id e consulte GET /v1/tasks/{id} com intervalo mínimo de 5 segundos. Os status públicos são pending, processing, succeeded e failed e o limite é 30 minutos. Não há webhooks, SDK ou batch.
- 01Salve id, status, credits_reserved e identidade da solicitação antes de atualizar a UI.
- 02Use backoff, respeite Retry-After no 429 e não transforme erro de transporte em outra tarefa paga.
- 03Limite a três tarefas de vídeo por conta e 120 solicitações por 60 segundos e API Key.
Cobrança e repetição determinísticas
Na aceitação, credits_reserved é descontado. Salve uma Idempotency-Key por criação; repeti-la com o mesmo corpo retorna a tarefa original.
Falhas elegíveis são reembolsadas uma vez com a validade original. refund_pending indica liquidação e credits_refunded confirma.
Proteger credenciais, propriedade e mídia
Mantenha API Keys no servidor e associe id ao usuário autenticado. Registre identificadores de suporte sem expor prompts, URLs privadas ou credenciais.
Não presuma retenção fixa de vídeo; copie logo o necessário para seu armazenamento com consentimento.
Checklist de produção
- Valide campos do modelo.
- Salve Idempotency-Key e corpo.
- Persista status e consulte a cada 5 segundos ou mais.
- Aplique concorrência e velocidade.
- Trate os quatro status e códigos de liquidação.
- Mantenha credenciais no servidor e defina retenção.
Perguntas frequentes
Com que frequência consultar?
Espere pelo menos 5 segundos e use backoff.
Quando os créditos são cobrados?
Na aceitação, credits_reserved é descontado.
Uma repetição cobra duas vezes?
Não com a mesma Idempotency-Key e corpo.
Como tratar falha final?
Mostre erro seguro, preserve id e verifique credits_refunded.
Quer testar o Hailuo?
Compare Fast, padrão e entradas de texto ou imagem na ferramenta online.
Testar Hailuo 2.3 online