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

# HappyHorse Videos API-Integrationsanleitung

> HappyHorse Video API guide - Ace Data Cloud

Dieser Artikel stellt die Integrationsmethode der HappyHorse Videos API vor. Diese Schnittstelle unterstützt über den einheitlichen Einstiegspunkt `/happyhorse/videos` und den Parameter `action` Text-zu-Video, Erstbild-zu-Video, Referenzbild-zu-Video und Videobearbeitung.

## Antragsprozess

Um die HappyHorse Videos API zu verwenden, rufen Sie zunächst die [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) auf, um Ihr API-Token zu erhalten, und bewahren Sie es als Reserve auf.

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

Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück.

**Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass für jeden Dienst ein separater Antrag erforderlich ist.** Beim ersten Antrag wird ein kostenloses Kontingent gewährt, das kostenlos getestet werden kann; bei unzureichendem Kontingent kann in der [Konsole](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufgeladen werden.

> 📘 Vollständige Dokumentation: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos)

## Aktionstypen

`action` bestimmt den Generierungsmodus dieser Anfrage:

* `generate`: Text-zu-Video, die Standardaktion, unterstützt `happyhorse-1.0-t2v` und `happyhorse-1.1-t2v`; `prompt` muss übergeben werden.
* `image_to_video`: Erstbild-zu-Video, unterstützt `happyhorse-1.0-i2v` und `happyhorse-1.1-i2v`; `image_url` muss übergeben werden.
* `reference_to_video`: Referenzbild-zu-Video, unterstützt `happyhorse-1.0-r2v` und `happyhorse-1.1-r2v`; `prompt` und 1–9 `image_urls` müssen übergeben werden.
* `video_edit`: Videobearbeitung, unterstützt `happyhorse-1.0-video-edit`; `prompt` und `video_url` müssen übergeben werden, zusätzlich können 0–5 Referenzbilder über `image_urls` übergeben werden.

Jede Aktion verwendet standardmäßig das 1.1-Modell; für `video_edit` gibt es derzeit nur `happyhorse-1.0-video-edit`.

## Grundlegende Verwendung

Für Text-zu-Video muss nur `prompt` bereitgestellt werden; auch Parameter wie `resolution`, `ratio` und `duration` können angegeben werden:

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

Ein Beispiel für das Rückgabeergebnis lautet wie folgt:

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

Feldbeschreibung:

* `success`: Ob diese Anfrage erfolgreich war.
* `task_id`: Aufgaben-ID auf der Ace-Data-Cloud-Seite, kann zur Abfrage des Aufgabenstatus verwendet werden.
* `trace_id`: Tracking-ID dieser Anfrage, wird zur Fehleranalyse verwendet.
* `data`: Liste der Videoergebnisse.
  * `id`: Aufgaben-ID auf der HappyHorse-Seite.
  * `video_url`: CDN-Linkadresse des generierten Videos.
  * `state`: Aufgabenstatus, optional `pending` / `succeeded` / `error`.
  * `duration`: Abgerechnete Videodauer in Sekunden; bei `video_edit` die Gesamtdauer von Eingabe- und Ausgabevideo.
  * `resolution`: Ausgabeauflösung.
  * `ratio`: Ausgabe-Seitenverhältnis.

Der entsprechende CURL-Code lautet wie folgt:

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

Der entsprechende Python-Code lautet wie folgt:

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

## Erstbild-zu-Video

Bei Verwendung von `image_to_video` wird `image_url` als erstes Videobild verwendet. Das Ausgabe-Seitenverhältnis folgt möglichst dem Bild des ersten Frames, daher muss bei dieser Aktion kein `ratio` übergeben werden.

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

## Referenzbild-zu-Video

Bei Verwendung von `reference_to_video` können über `image_urls` 1–9 Referenzbilder übergeben werden. Im Prompt können die Bilder in der entsprechenden Reihenfolge mit `character1`, `character2` usw. referenziert werden.

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

## Videobearbeitung

Bei Verwendung von `video_edit` müssen das zu bearbeitende Video `video_url` und die Bearbeitungsabsicht `prompt` übergeben werden. Optionale `image_urls` werden als Referenzbilder verwendet, beispielsweise für Kleidungswechsel, Stilübertragung oder lokale Ersetzung. `audio_setting` kann optional `auto` oder `origin` sein, wobei `origin` bedeutet, dass der Originalton des Videos beibehalten wird.

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

## Asynchroner Rückruf

Die Videogenerierung benötigt eine gewisse Verarbeitungszeit. Wenn Sie nicht warten möchten, während eine lange Verbindung offen bleibt, können Sie `callback_url` übergeben. In diesem Fall gibt die API sofort `task_id` zurück, und nach Abschluss der Aufgabe wird das endgültige Ergebnis per POST an diese Adresse gesendet:

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

Das sofort zurückgegebene Ergebnis lautet wie folgt:

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

Wenn Sie nur abfragen möchten und keinen Callback benötigen, können Sie auch `"async": true` übergeben und anschließend das Aufgabenergebnis über die [HappyHorse Tasks API](https://platform.acedata.cloud/documents/happyhorse-tasks) abfragen.

## Abrechnungshinweise

HappyHorse rechnet nach der Anzahl der Sekunden des ausgegebenen Videos und der Auflösung ab:

* `720P`: Ab etwa 0,105 \$ / Sekunde.
* `1080P`: Ab etwa 0,18 \$ / Sekunde.
* `video_edit`: Abrechnung nach der Gesamtdauer des Eingabevideos und des Ausgabevideos; die tatsächliche Abrechnungsdauer richtet sich nach den Statistiken nach Abschluss der Aufgabe.

Fehlgeschlagene Aufgaben werden nicht berechnet und verbrauchen auch kein kostenloses Kontingent.

## Fehlerbehandlung

Wenn ein Problem mit der Anfrage auftritt, gibt die API den entsprechenden Fehlercode und eine Beschreibung zurück. Häufige Fälle sind:

* `400`: Anfrageparameter sind fehlerhaft, beispielsweise stimmen action und model nicht überein, `prompt` / `image_url` / `video_url` fehlt oder `duration` liegt außerhalb des Bereichs von 3–15 Sekunden.
* `401`: Authentifizierung fehlgeschlagen, das Token ist ungültig oder stimmt nicht mit der API überein.
* `403`: Unzureichendes Guthaben oder die Eingabeaufforderung wurde aufgrund der Inhaltsprüfung abgelehnt.
* `429`: Die Anfragen erfolgen zu häufig und haben die Ratenbegrenzung ausgelöst. Bitte versuchen Sie es später erneut.
* `500`: Interner Serverfehler oder Generierung fehlgeschlagen.


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