Instruções de integração da API HappyHorse Videos

Este documento apresenta o método de integração da API HappyHorse Videos. Esta API oferece suporte para 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 através de uma entrada unificada /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 mantê-lo como reserva.

Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e fazer login. Após concluir, você retornará automaticamente à página atual. Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço. A primeira solicitação concede 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, compatível com happyhorse-1.0-t2v e happyhorse-1.1-t2v, sendo obrigatório fornecer prompt.
image_to_video: geração de vídeo a partir da imagem do primeiro quadro, compatível com 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, compatível com happyhorse-1.0-r2v e happyhorse-1.1-r2v, sendo obrigatório fornecer prompt e 1–9 image_urls.
video_edit: edição de vídeo, compatível com happyhorse-1.0-video-edit, sendo obrigatório fornecer prompt e video_url, e podendo opcionalmente fornecer 0–5 imagens de referência em image_urls.

Cada ação usa o modelo 1.1 por padrão; video_edit atualmente possui apenas happyhorse-1.0-video-edit.

Uso básico

A geração de vídeo a partir de texto requer apenas o fornecimento de prompt; também é possível especificar parâmetros como resolution, ratio e duration:

{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

Um exemplo de resultado retornado é o seguinte:

{
  "success": true,
  "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1",
  "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69",
  "data": [
    {
      "id": "9650580f-6d9e-4bc1-823a-29011790c5cb",
      "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
      "state": "succeeded",
      "duration": 5,
      "resolution": "720P",
      "ratio": null
    }
  ]
}

Descrição dos campos:

success: 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 solucionar 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 cobrada, em segundos; para video_edit, é a soma da duração 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:

curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "happyhorse-1.1-t2v",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}'

O código Python correspondente é o seguinte:

import requests

url = "https://api.acedata.cloud/happyhorse/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}

payload = {
    "action": "generate",
    "model": "happyhorse-1.1-t2v",
    "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
    "resolution": "720P",
    "ratio": "16:9",
    "duration": 5,
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Geração de vídeo a partir da 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 requer o envio de ratio.

{
  "action": "image_to_video",
  "model": "happyhorse-1.1-i2v",
  "image_url": "https://cdn.acedata.cloud/b1c82e4937.png",
  "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting",
  "resolution": "1080P",
  "duration": 5
}

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

Ao usar reference_to_video, é possível fornecer de 1–9 imagens de referência em image_urls. No prompt, é possível referenciar as imagens na ordem correspondente usando character1, character2 e assim por diante.

{
  "action": "reference_to_video",
  "model": "happyhorse-1.1-r2v",
  "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2",
  "image_urls": [
    "https://cdn.acedata.cloud/b1c82e4937.png",
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "ratio": "16:9",
  "duration": 5
}

Edição de vídeo

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 local. audio_setting pode ser auto ou origin, sendo que origin indica a preservação do áudio do vídeo original.

{
  "action": "video_edit",
  "model": "happyhorse-1.0-video-edit",
  "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion",
  "video_url": "https://cdn.acedata.cloud/assets/examples/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1-2c108ce23554.mp4",
  "image_urls": [
    "https://cdn.acedata.cloud/eb75d88a3f.png"
  ],
  "resolution": "720P",
  "audio_setting": "auto"
}

Retorno de chamada 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 o task_id e, após a conclusão da tarefa, enviará o resultado final via POST para esse endereço:

{
  "action": "generate",
  "prompt": "A horse running through a snowy forest",
  "duration": 5,
  "callback_url": "https://your-domain.com/callback/happyhorse"
}

O resultado retornado imediatamente é o seguinte:

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

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

A HappyHorse cobra com base nos segundos de vídeo gerados e na resolução:

720P: a partir de aproximadamente $0.105 / segundo.
1080P: a partir de aproximadamente $0.18 / segundo.
video_edit: cobrado com base na soma das durações do vídeo de entrada e do vídeo de saída; a duração efetivamente cobrada será baseada nas estatísticas após a conclusão da tarefa.

Tarefas com falha não são cobradas e não consomem a cota gratuita.

Tratamento de erros

Quando ocorre um problema com a solicitação, a API retorna 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 moderação de conteúdo.
429: solicitações muito frequentes acionaram o limite de taxa; tente novamente mais tarde.
500: erro interno do servidor ou falha na geração.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Instruções de integração da API HappyHorse Videos

Processo de solicitação

Tipos de operação

Uso básico

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

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

Edição de vídeo

Retorno de chamada assíncrono

Explicação de cobrança

Tratamento de erros

​Processo de solicitação

​Tipos de operação

​Uso básico

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

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

​Edição de vídeo

​Retorno de chamada assíncrono

​Explicação de cobrança

​Tratamento de erros

Processo de solicitação

Tipos de operação

Uso básico

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

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

Edição de vídeo

Retorno de chamada assíncrono

Explicação de cobrança

Tratamento de erros