Zum Hauptinhalt springen
Dieser Artikel stellt die Integrationsmethode der HappyHorse Videos API vor. Diese Schnittstelle unterstützt Text-zu-Video, Bild-zu-Video mit dem ersten Frame, Bild-zu-Video mit Referenzbildern und Videobearbeitung über den einheitlichen Einstieg /happyhorse/videos und den Parameter action.

Antragsprozess

Um die HappyHorse Videos API zu verwenden, rufen Sie zunächst die Ace Data Cloud-Konsole auf, um Ihren API-Token abzurufen und für die spätere Verwendung aufzubewahren. Falls 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. Mit einem API-Token können alle Dienste der Plattform aufgerufen werden, ohne dass Sie ihn für jeden Dienst separat beantragen müssen. Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben zum kostenlosen Ausprobieren; bei unzureichendem Guthaben können Sie Ihr allgemeines Guthaben in der Konsole aufladen.
📘 Vollständige Dokumentation: HappyHorse Videos API →

Aktionstypen

action bestimmt den Generierungsmodus dieser Anfrage:
  • generate: Text-zu-Video, die standardmäßige action, unterstützt happyhorse-1.0-t2v und happyhorse-1.1-t2v; prompt muss übergeben werden.
  • image_to_video: Bild-zu-Video mit dem ersten Frame, unterstützt happyhorse-1.0-i2v und happyhorse-1.1-i2v; image_url muss übergeben werden.
  • reference_to_video: Bild-zu-Video mit Referenzbildern, 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 als image_urls übergeben werden.
Für alle Aktionen wird standardmäßig das Modell 1.1 verwendet; 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; Parameter wie resolution, ratio und duration können ebenfalls angegeben werden:
Ein Beispiel für das Rückgabeergebnis lautet wie folgt:
Felderklärung:
  • success: Ob diese Anfrage erfolgreich war.
  • task_id: Die Aufgaben-ID auf der Seite von Ace Data Cloud, die zum Abfragen des Aufgabenstatus verwendet werden kann.
  • trace_id: Die Tracking-ID dieser Anfrage, die zur Fehlerbehebung verwendet wird.
  • data: Liste der Videoergebnisse.
    • id: Die Aufgaben-ID auf der Seite von HappyHorse.
    • video_url: Die CDN-Linkadresse des generierten Videos.
    • state: Aufgabenstatus, optional pending / succeeded / error.
    • duration: Abrechenbare 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:
Der entsprechende Python-Code lautet wie folgt:

Bild-zu-Video mit dem ersten Frame

Bei der Verwendung von image_to_video wird image_url als erster Frame des Videos verwendet. Das Ausgabe-Seitenverhältnis folgt nach Möglichkeit dem Bild des ersten Frames, daher muss für diese Aktion ratio nicht übergeben werden.

Bild-zu-Video mit Referenzbildern

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

Videobearbeitung

Die Ausgabedauer und das Bildformat von video_edit werden vom Quellvideo übernommen; die Übergabe von duration oder ratio ändert sie nicht. Auch das Bildformat von Bild-zu-Video übernimmt das Quellbild. Die Bearbeitungskosten werden anhand der Gesamtdauer von Eingabe- und Ausgabevideo berechnet. Bei der 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 lokalen Ersatz. audio_setting kann optional auto oder origin sein, wobei origin bedeutet, dass das Originalaudio des Videos beibehalten wird.

Asynchroner Rückruf

Die Videogenerierung benötigt eine gewisse Verarbeitungszeit. Wenn Sie nicht auf eine lange Verbindung warten möchten, können Sie callback_url übergeben. In diesem Fall gibt die API sofort task_id zurück, und nach Abschluss der Aufgabe wird das Endergebnis per POST an diese Adresse gesendet:
Das sofort zurückgegebene Ergebnis lautet wie folgt:
Wenn Sie nur abfragen möchten und keinen Rückruf benötigen, können Sie auch "async": true übergeben und anschließend das Aufgabenergebnis über die HappyHorse Tasks API abfragen.

Abrechnungshinweise

HappyHorse berechnet nach Sekunden des Ausgabevideos und Auflösung:
  • 720P: bereits ab ca. $0.105 / Sekunde.
  • 1080P: bereits ab ca. $0.18 / Sekunde.
  • video_edit: Die Abrechnung erfolgt nach der Gesamtdauer des Eingabe- und Ausgabevideos; die tatsächliche Abrechnungsdauer richtet sich nach der Statistik nach Abschluss der Aufgabe.
Fehlgeschlagene Aufgaben werden nicht berechnet und verbrauchen auch kein kostenloses Kontingent.

Fehlerbehandlung

Wenn bei der Anfrage ein Problem auftritt, gibt die API den entsprechenden Fehlercode und eine Beschreibung zurück. Häufige Fälle sind:
  • 400: Anfrageparameter sind fehlerhaft, z. B. 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 der Prompt wurde von der Inhaltsprüfung abgelehnt.
  • 429: Zu häufige Anfragen haben die Ratenbegrenzung ausgelöst. Bitte versuchen Sie es später erneut.
  • 500: Interner Serverfehler oder Generierung fehlgeschlagen.