Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Este documento irá apresentar uma descrição da integração da Hailuo Videos Generation API, que pode gerar vídeos oficiais da Hailuo através da entrada de parâmetros personalizados.

​
Processo de Solicitação

Para usar a API, você precisa primeiro acessar a página correspondente da Hailuo Videos Generation API para solicitar o serviço correspondente. Após entrar na página, clique no botão “Acquire”, conforme mostrado na imagem: Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o login ou registro, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito da API.

​
Uso Básico

Primeiro, entenda a forma básica de uso, que envolve a entrada de uma palavra-chave prompt, uma ação action, uma imagem de referência para o primeiro quadro first_image_url e o modelo model, para obter o resultado processado. Primeiro, é necessário passar um campo action, cujo valor deve ser generate. Em seguida, precisamos inserir o modelo, que atualmente possui os modelos de vídeo gerados a partir de imagem minimax-i2v e de texto minimax-t2v, conforme detalhado abaixo:

Podemos ver que aqui configuramos os Request Headers, incluindo:
  • accept: o formato de resposta desejado, que deve ser preenchido como application/json, ou seja, formato JSON.
  • authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Além disso, configuramos o Request Body, incluindo:
  • model: o modelo para gerar o vídeo, que possui os modelos de vídeo gerados a partir de imagem minimax-i2v e de texto minimax-t2v.
  • action: a ação da tarefa de geração de vídeo.
  • first_image_url: quando o modelo de vídeo gerado a partir de imagem minimax-i2v é escolhido, é necessário fazer o upload do link da imagem de referência do primeiro quadro, não suportando codificação Base64.
  • prompt: a palavra-chave.
  • callback_url: a URL para onde o resultado deve ser enviado.
Após a seleção, podemos ver que o código correspondente foi gerado à direita, conforme mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e assim obtemos o seguinte resultado: 
{
  "success": true,
  "task_id": "baf1034c-684c-46be-ae6d-89ebb89b690d",
  "trace_id": "3221eb74-1a25-447a-ba69-7d9b310e306c",
  "data": [
    {
      "id": "0pv8yhe4fdrge0cmckpv23pd2g",
      "model": "minimax-t2v",
      "prompt": "Internal heat",
      "video_url": "https://file.aigpai.com/czjl/qoueLWBokF3ud6tdVD6VJTZuXTnK5HaMO2qAOS46Ef8VSBFUA/tmp9e3u11c1.output.mp4",
      "state": "succeeded"
    }
  ]
}
O resultado retornado possui vários campos, descritos a seguir:
  • success: o estado da tarefa de geração de vídeo.
  • task_id: o ID da tarefa de geração de vídeo.
  • trace_id: o ID de rastreamento da geração de vídeo.
  • data: a lista de resultados da tarefa de geração de vídeo.
    • id: o ID do vídeo gerado pela tarefa de geração de vídeo.
    • prompt: a palavra-chave da tarefa de geração de vídeo.
    • model: o link da capa da tarefa de geração de vídeo.
    • video_url: o link do vídeo gerado pela tarefa de geração de vídeo.
    • state: o estado da tarefa de geração de vídeo.
Podemos ver que obtivemos informações satisfatórias sobre o vídeo, e precisamos apenas acessar o link do vídeo gerado em data para obter o vídeo Hailuo. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, como o código CURL abaixo: 
curl -X POST 'https://api.xhuoapi.ai/v1/hailuo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "Internal heat"
}'

​
Callback Assíncrono

Como o tempo de geração da Hailuo Videos Generation API é relativamente longo, cerca de 1-2 minutos, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente faz a solicitação, deve especificar um campo callback_url adicional. Após a solicitação da API, a API retornará imediatamente um resultado, contendo um campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado do vídeo gerado será enviado para a URL callback_url especificada pelo cliente, também incluindo o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID. A seguir, vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, e os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Para facilitar a demonstração, usaremos um site de exemplo de Webhook público https://webhook.site/, onde você pode abrir o site e obter uma URL de Webhook, conforme mostrado na imagem: Copie esta URL para usá-la como Webhook, sendo o exemplo https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83. Em seguida, podemos definir o campo callback_url como a URL do Webhook acima, enquanto preenchemos os parâmetros correspondentes, conforme mostrado na imagem:

Clique em executar e você verá que receberá imediatamente um resultado, como abaixo: 
{
  "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840"
}
Após alguns instantes, podemos observar o resultado do vídeo gerado em https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83, conforme mostrado na imagem: O conteúdo é o seguinte: 
{
    "success": true,
    "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840",
    "trace_id": "b9856b8a-725d-45c9-befe-e789d9fd9ffb",
    "data": [
        {
            "id": "t80jhsf96srg80cmcm6b0rk8gm",
            "model": "minimax-t2v",
            "prompt": "Internal heat",
            "video_url": "https://file.aigpai.com/czjl/YPaUz2DcwpJqItTXAG9XHAoEoj3dbF0XPU69LT5nefCMzBFUA/tmp8s_59jez.output.mp4",
            "state": "succeeded"
        }
    ]
}
Podemos ver que o resultado contém um campo task_id, e os outros campos são semelhantes aos mencionados anteriormente, permitindo que a tarefa seja associada através desse campo.

​
Tratamento de Erros

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 400 token_mismatched：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 400 api_not_implemented：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 401 invalid_token：Não autorizado, token de autorização inválido ou ausente.
  • 429 too_many_requests：Muitas solicitações, você excedeu o limite de taxa.
  • 500 api_error：Erro interno do servidor, algo deu errado no servidor.

​
错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
结论

通过本文档，您已经了解了如何使用 Hailuo Videos Generation API 可通过输入提示词以及首帧参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。