Skip to main content
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 Hailuo Videos Generation API, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro. Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar individualmente para cada serviço. A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no painel de controle.
📘 Documentação Completa: Hailuo Videos Generation 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:

Aqui, podemos ver que configuramos os Cabeçalhos da Solicitação, 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 Corpo da Solicitação, que inclui:
  • model: o modelo para gerar o vídeo, que pode ser o modelo de vídeo gerado a partir de imagem minimax-i2v ou o modelo de vídeo gerado a partir 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 enviar o 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.
  • async: opcional, se definido como true, a interface retorna imediatamente um task_id, sem necessidade de fornecer callback_url, e o resultado pode ser obtido posteriormente através da interface de consulta de tarefas correspondente.
Após a seleção, podemos ver que o código correspondente foi gerado à direita, como mostrado na imagem:

Clique no botão “Try” para realizar o teste, como mostrado na imagem acima, e obtemos o seguinte resultado:
O resultado retornado contém 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 tudo o que precisamos fazer é 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 correspondente para a integração, pode copiá-lo diretamente, como o código CURL abaixo:

​
Retorno 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 retorno assíncrono. 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 o callback_url especificado pelo cliente em formato JSON POST, incluindo também 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 retorno do Webhook é um serviço que pode receber solicitações HTTP, e o desenvolvedor deve substituí-lo pela URL do servidor HTTP que ele configurou. Para facilitar a demonstração, usaremos um site de exemplo de Webhook público https://webhook.site/, onde ao abrir o site você obterá uma URL de Webhook, como mostrado na imagem: Copie esta URL para usá-la como Webhook; o exemplo aqui é 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:
Após alguns instantes, podemos observar o resultado do vídeo gerado em https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83, como mostrado na imagem: O conteúdo é o seguinte:
Pode-se ver que o resultado contém um campo task_id, os outros campos são semelhantes ao texto anterior, e através desse campo é possível realizar a associação da tarefa.

​
Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o respectivo código de erro e informações. Por exemplo:
  • 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.

​
Exemplo de Resposta de Erro

​
Conclusão

Através deste documento, você já entendeu como usar a API de Geração de Vídeos Hailuo, que pode gerar vídeos através de palavras-chave de entrada e uma imagem de referência do primeiro quadro. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.