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

# Instrukcja integracji HappyHorse Videos API

> HappyHorse Video API guide - Ace Data Cloud

Ten artykuł przedstawia sposób integracji z HappyHorse Videos API. Ten interfejs obsługuje generowanie wideo z tekstu, generowanie wideo z obrazu pierwszej klatki, generowanie wideo z obrazów referencyjnych oraz edycję wideo za pośrednictwem jednolitego punktu wejścia `/happyhorse/videos` i parametru `action`.

## Proces aplikacji

Aby korzystać z HappyHorse Videos API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go na później.

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

Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania z zaproszeniem do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę.

**Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez potrzeby osobnego składania wniosku dla każdej usługi.** Przy pierwszym wniosku otrzymasz bezpłatny limit, aby móc korzystać z bezpłatnego okresu próbnego; gdy limit będzie niewystarczający, możesz doładować wspólne saldo w [konsoli](https://platform.acedata.cloud/console/coin).

> 📘 Pełna dokumentacja: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## Typy operacji

`action` określa tryb generowania dla bieżącego żądania:

* `generate`: generowanie wideo z tekstu, domyślna akcja, obsługuje `happyhorse-1.0-t2v` i `happyhorse-1.1-t2v`, należy przekazać `prompt`.
* `image_to_video`: generowanie wideo z obrazu pierwszej klatki, obsługuje `happyhorse-1.0-i2v` i `happyhorse-1.1-i2v`, należy przekazać `image_url`.
* `reference_to_video`: generowanie wideo z obrazów referencyjnych, obsługuje `happyhorse-1.0-r2v` i `happyhorse-1.1-r2v`, należy przekazać `prompt` oraz 1–9 `image_urls`.
* `video_edit`: edycja wideo, obsługuje `happyhorse-1.0-video-edit`, należy przekazać `prompt` i `video_url`, można dodatkowo przekazać 0–5 obrazów referencyjnych `image_urls`.

Każda akcja domyślnie używa modelu 1.1; `video_edit` obecnie ma tylko `happyhorse-1.0-video-edit`.

## Podstawowe użycie

Generowanie wideo z tekstu wymaga jedynie podania `prompt`; można również określić parametry takie jak `resolution`, `ratio`, `duration` itd.:

```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
}
```

Przykładowy zwracany wynik jest następujący:

```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
    }
  ]
}
```

Opis pól:

* `success`: czy bieżące żądanie zakończyło się powodzeniem.
* `task_id`: ID zadania po stronie Ace Data Cloud, może być używane do sprawdzania statusu zadania.
* `trace_id`: ID śledzenia bieżącego żądania, używane do rozwiązywania problemów.
* `data`: lista wyników wideo.
  * `id`: ID zadania po stronie HappyHorse.
  * `video_url`: adres linku CDN wygenerowanego wideo.
  * `state`: status zadania, dostępne wartości to `pending` / `succeeded` / `error`.
  * `duration`: rozliczany czas trwania wideo, w sekundach; dla `video_edit` jest to łączny czas trwania wideo wejściowego i wyjściowego.
  * `resolution`: rozdzielczość wyjściowa.
  * `ratio`: proporcje szerokości do wysokości wyjścia.

Odpowiedni kod CURL jest następujący:

```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
}'
```

Odpowiedni kod Python jest następujący:

```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)
```

## Generowanie wideo z obrazu pierwszej klatki

Podczas używania `image_to_video`, `image_url` będzie używany jako pierwsza klatka wideo. Wyjściowe proporcje szerokości do wysokości będą w miarę możliwości zgodne z obrazem pierwszej klatki, dlatego ta akcja nie wymaga przekazania `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
}
```

## Generowanie wideo z obrazów referencyjnych

Podczas używania `reference_to_video`, `image_urls` może przyjąć 1–9 obrazów referencyjnych. W promptcie można używać `character1`, `character2` itd., aby odwoływać się do obrazów w odpowiedniej kolejności.

```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
}
```

## Edycja wideo

Podczas używania `video_edit` należy przekazać edytowane wideo `video_url` oraz intencję edycji `prompt`. Opcjonalne `image_urls` będą używane jako obrazy referencyjne, na przykład do zmiany stroju, transferu stylu lub lokalnej zamiany. `audio_setting` może opcjonalnie przyjmować wartość `auto` lub `origin`, gdzie `origin` oznacza zachowanie oryginalnego dźwięku wideo.

```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"
}
```

## Asynchroniczne wywołanie zwrotne

Generowanie wideo wymaga pewnego czasu przetwarzania. Jeśli nie chcesz utrzymywać długiego połączenia w oczekiwaniu, możesz przekazać `callback_url`, wtedy API natychmiast zwróci `task_id`, a po zakończeniu zadania wyśle końcowy wynik metodą POST na ten adres:

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

Natychmiast zwrócony wynik jest następujący:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

Jeśli chcesz tylko odpytywać, bez potrzeby używania callbacku, możesz również przekazać `"async": true`, a następnie sprawdzić wynik zadania za pomocą [HappyHorse Tasks API](https://platform.acedata.cloud/documents/happyhorse-tasks).

## Informacje o rozliczeniach

HappyHorse rozlicza według liczby sekund wyjściowego wideo i rozdzielczości:

* `720P`: już od około \$0.105 / sekundę.
* `1080P`: już od około \$0.18 / sekundę.
* `video_edit`: rozliczane według łącznego czasu trwania wejściowego i wyjściowego wideo, a rzeczywisty czas rozliczeniowy jest określany na podstawie statystyk po zakończeniu zadania.

Nieudane zadania nie są rozliczane ani nie wykorzystują darmowego limitu.

## Obsługa błędów

Gdy wystąpi problem z żądaniem, API zwróci odpowiedni kod błędu i opis, najczęstsze są następujące:

* `400`: parametry żądania są nieprawidłowe, na przykład action nie pasuje do modelu, brakuje `prompt` / `image_url` / `video_url` lub `duration` wykracza poza zakres 3–15 sekund.
* `401`: uwierzytelnianie nie powiodło się, token jest nieprawidłowy lub nie pasuje do API.
* `403`: niewystarczające saldo lub monit został odrzucony przez moderację treści.
* `429`: żądania są zbyt częste, uruchomiono ograniczenie szybkości, spróbuj ponownie później.
* `500`: wewnętrzny błąd serwera lub niepowodzenie generowania.


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