Saltar para o conteúdo principal
Este documento apresenta como integrar a API HappyHorse Videos. Esta API oferece suporte à geração de vídeo a partir de texto, geração de vídeo a partir de imagem do primeiro quadro, geração de vídeo a partir de imagens de referência e edição de vídeo por meio do endpoint unificado /happyhorse/videos e do parâmetro action.

Processo de solicitação

Para usar a API HappyHorse Videos, primeiro acesse o Console Ace Data Cloud para obter seu API Token e guarde-o para uso posterior. Se você ainda não estiver conectado ou registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e entrar. Após a conclusão, você retornará automaticamente à página atual. Um único API Token permite chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço. A primeira solicitação inclui créditos gratuitos para experimentação; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.
📘 Documentação completa: HappyHorse Videos API →

Tipos de operação

action determina o modo de geração desta solicitação:
  • generate: geração de vídeo a partir de texto, action padrão, suporta happyhorse-1.0-t2v e happyhorse-1.1-t2v, sendo obrigatório fornecer prompt.
  • image_to_video: geração de vídeo a partir de imagem do primeiro quadro, suporta happyhorse-1.0-i2v e happyhorse-1.1-i2v, sendo obrigatório fornecer image_url.
  • reference_to_video: geração de vídeo a partir de imagens de referência, suporta happyhorse-1.0-r2v e happyhorse-1.1-r2v, sendo obrigatório fornecer prompt e de 1 a 9 image_urls.
  • video_edit: edição de vídeo, suporta happyhorse-1.0-video-edit, sendo obrigatório fornecer prompt e video_url, com a opção de fornecer adicionalmente de 0 a 5 imagens de referência em image_urls.
Cada ação usa o modelo 1.1 por padrão; no momento, video_edit possui apenas happyhorse-1.0-video-edit.

Uso básico

A geração de vídeo a partir de texto requer apenas prompt, e você também pode especificar parâmetros como resolution, ratio e duration:
Um exemplo do resultado retornado é o seguinte:
Descrição dos campos:
  • success: indica se esta solicitação foi bem-sucedida.
  • task_id: ID da tarefa no Ace Data Cloud, que pode ser usado para consultar o status da tarefa.
  • trace_id: ID de rastreamento desta solicitação, usado para investigar problemas.
  • data: lista de resultados de vídeo.
    • id: ID da tarefa no HappyHorse.
    • video_url: endereço do link CDN do vídeo gerado.
    • state: status da tarefa, podendo ser pending / succeeded / error.
    • duration: duração do vídeo para cobrança, em segundos; para video_edit, corresponde ao total das durações dos vídeos de entrada e saída.
    • resolution: resolução de saída.
    • ratio: proporção de aspecto de saída.
O código CURL correspondente é o seguinte:
O código Python correspondente é o seguinte:

Geração de vídeo a partir de imagem do primeiro quadro

Ao usar image_to_video, image_url será usado como o primeiro quadro do vídeo. A proporção de aspecto de saída seguirá, na medida do possível, a imagem do primeiro quadro; portanto, esta ação não exige a passagem de ratio.

Geração de vídeo a partir de imagens de referência

Ao usar reference_to_video, é possível fornecer de 1 a 9 imagens de referência em image_urls. No prompt, você pode usar character1, character2 e similares para referenciar as imagens na ordem correspondente.

Edição de vídeo

A duração e o enquadramento de saída de video_edit são herdados do vídeo de origem; fornecer duration ou ratio não os alterará; o enquadramento do vídeo gerado a partir de imagem também é herdado da imagem de origem. A taxa de edição é calculada com base no total das durações dos vídeos de entrada e saída. Ao usar video_edit, é obrigatório fornecer o vídeo a ser editado em video_url e a intenção de edição em prompt. Os image_urls opcionais serão usados como imagens de referência, por exemplo, para troca de roupa, transferência de estilo ou substituição parcial. audio_setting pode ser auto ou origin, em que origin indica a preservação do áudio do vídeo original.

Callback assíncrono

A geração de vídeo requer um certo tempo de processamento. Se não desejar manter uma conexão longa aguardando, você pode fornecer callback_url; nesse caso, a API retornará imediatamente task_id e, após a conclusão da tarefa, enviará o resultado final via POST para esse endereço:
O resultado retornado imediatamente é o seguinte:
Se desejar apenas fazer polling, sem precisar de callback, também é possível fornecer "async": true e, em seguida, consultar o resultado da tarefa por meio da API de Tarefas HappyHorse.

Explicação de cobrança

O HappyHorse cobra por segundos de vídeo de saída e resolução:
  • 720P: a partir de aproximadamente $0.105 / segundo.
  • 1080P: a partir de aproximadamente $0.18 / segundo.
  • video_edit: cobrado pela soma da duração do vídeo de entrada e do vídeo de saída; a duração real cobrada será baseada nas estatísticas após a conclusão da tarefa.
Tarefas com falha não são cobradas e também não consomem a cota gratuita.

Tratamento de erros

Quando houver um problema com a solicitação, a API retornará o código de erro e a descrição correspondentes; os mais comuns são:
  • 400: os parâmetros da solicitação estão incorretos, por exemplo, action e model não correspondem, falta prompt / image_url / video_url, ou duration está fora do intervalo de 3–15 segundos.
  • 401: falha na autenticação, o token é inválido ou não corresponde à API.
  • 403: saldo insuficiente ou o prompt foi rejeitado por acionar a revisão de conteúdo.
  • 429: solicitações muito frequentes, o limite de taxa foi acionado; tente novamente mais tarde.
  • 500: erro interno do servidor ou falha na geração.