> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> HappyHorse Video API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) para obter seu API Token e mantê-lo como reserva.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentação completa: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## 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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```shell theme={null}
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:

```python theme={null}
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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/happyhorse-tasks).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.