So verwendest du happyhorse-1.1 über die hiapi API: Text-zu-Video, Bild-zu-Video und Referenz-zu-Video

Wenn du gerade suchst, wie du happy horse 1.1 verwendest, hier die Kurzfassung: happyhorse-1.1 ist kein einzelner Modell-Endpunkt, sondern drei, die alle über die einheitliche asynchrone Task-API von hiapi bereitgestellt werden:

Endpunkt (Modell-ID)	Funktion	Erforderliche Eingabe
happyhorse-1.1/text-to-video	Generiert ein Video aus einem Text-Prompt	prompt
happyhorse-1.1/image-to-video	Bringt ein statisches Bild in Bewegung	image_urls
happyhorse-1.1/reference-to-video	Generiert ein Video, gesteuert durch Referenzbilder plus Prompt	prompt, reference_image

Diese drei Endpunkte teilen denselben Lebenszyklus: POST /v1/tasks absenden → taskId erhalten → GET /v1/tasks/<id> abfragen (oder Callback empfangen) → output[0].url herunterladen. Jede Parametertabelle und jede Fehlermeldung unten wurde gegen die Live-API verifiziert – nichts davon ist geraten.

Voraussetzungen

Du brauchst nur eines: einen hiapi API-Schlüssel. Hol ihn dir in deiner hiapi-Konsole – er hat die Form sk-... und gehört in den Authorization: Bearer-Header. Die Videogenerierung wird nach Ausgabesekunden abgerechnet; die aktuellen Sekundentarife pro Endpunkt findest du auf der Preisseite.

export HIAPI_KEY="sk-your-key-here"

Minimales lauffähiges Beispiel (Text-zu-Video)

Aufgabe absenden:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "A golden retriever puppy runs through a sunlit meadow, slow motion, cinematic",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5
    }
  }'

Die Antwort gibt dir unter data.taskId eine Task-ID. Frage sie ab:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer $HIAPI_KEY"

Wenn data.status zu success wird, liegt die Video-URL unter data.output[0].url. Lade sie sofort herunter – Ausgabe-URLs tragen einen expireAt-Zeitstempel und liegen im temporären Speicher; behandle sie also als Abholfenster, nicht als dauerhaftes Hosting.

Hier ist das vollständige Python-Skript für denselben Ablauf (nur Standardbibliothek):

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-your-key-here"

def api(method, url, payload=None):
    req = urllib.request.Request(url, method=method)
    req.add_header("Authorization", f"Bearer {KEY}")
    req.add_header("Content-Type", "application/json")
    data = json.dumps(payload).encode() if payload else None
    with urllib.request.urlopen(req, data=data) as resp:
        return json.loads(resp.read())

# 1. Submit
task = api("POST", API, {
    "model": "happyhorse-1.1/text-to-video",
    "input": {
        "prompt": "A golden retriever puppy runs through a sunlit meadow, cinematic",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
    },
})
task_id = task["data"]["taskId"]
print("submitted:", task_id)

# 2. Poll until terminal state
while True:
    data = api("GET", f"{API}/{task_id}")["data"]
    status = data["status"]
    if status == "success":
        video_url = data["output"][0]["url"]
        break
    if status == "fail":
        raise RuntimeError(f"task failed: {data.get('error')}")
    time.sleep(5)

# 3. Download before the URL expires
urllib.request.urlretrieve(video_url, "output.mp4")
print("saved output.mp4")

Parameter der einzelnen Endpunkte

Das Eingabe-Schema ist strikt: Unbekannte Felder werden mit 400 abgelehnt, nicht stillschweigend ignoriert. Felder wie size, seed, negative_prompt und audio liefern alle additional properties ... not allowed zurück. Im Folgenden siehst du, welche Parameter jeder Endpunkt exakt akzeptiert.

happyhorse-1.1/text-to-video

Feld	Erforderlich	Typ	Erlaubte Werte
prompt	✅	string	Deine Szenenbeschreibung
aspect_ratio	—	string	16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (Sekunden)

Vollständige Anleitung mit Prompt-Tipps: happyhorse-1.1 Text-zu-Video-Tutorial.

happyhorse-1.1/image-to-video

Feld	Erforderlich	Typ	Erlaubte Werte
image_urls	✅	String-Array	Genau 1 öffentlich zugängliche Bild-URL (maxItems: 1)
prompt	—	string	Bewegungs-/Szenenführung für die Animation
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (Sekunden)

Hier gibt es zwei leicht zu übersehende Stolperfallen. Erstens: image_urls ist ein Array, akzeptiert aber derzeit nur ein Element – übergib ["https://..."], keinen nackten String und nicht mehrere URLs. Zweitens: Dieser Endpunkt hat kein aspect_ratio (die API lehnt es ab); das Ausgabeformat folgt deinem Quellbild.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "prompt": "slow camera push-in, soft studio lighting",
      "resolution": "720p",
      "duration": 5
    }
  }'

Weiterführende Lektüre: happyhorse Bild-zu-Video-Tutorial.

happyhorse-1.1/reference-to-video

Feld	Erforderlich	Typ	Erlaubte Werte
prompt	✅	string	Szenenbeschreibung
reference_image	✅	String-Array	1–9 öffentlich zugängliche Bild-URLs (maxItems: 9)
aspect_ratio	—	string	Dieselben 9 Seitenverhältnisse wie bei Text-zu-Video
resolution	—	string	720p, 1080p
duration	—	integer	3–15 (Sekunden)

Das ist der Endpunkt für „meine Figur/mein Produkt konsistent halten": Referenzbilder verankern Identität und Stil, während der Prompt die Bewegung steuert. Anders als bei Bild-zu-Video gewinnst du hier die Kontrolle über aspect_ratio zurück und kannst bis zu 9 Referenzbilder übergeben.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/reference-to-video",
    "input": {
      "prompt": "the character waves at the camera and smiles, city street at dusk",
      "reference_image": ["https://your-cdn.example.com/character-front.jpg",
                          "https://your-cdn.example.com/character-side.jpg"],
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 5
    }
  }'

Weiterführende Lektüre: happyhorse-1.1 Referenz-zu-Video-Tutorial.

Welchen Endpunkt solltest du wählen?

• Du hast nur eine Idee → text-to-video. Der schnellste Weg vom Text zur Bewegung.
• Du hast das genaue Bild, das animiert werden soll (Produktbild, Illustration, Foto) → image-to-video. Das Quellbild ist das Aussehen des ersten Frames.
• Du musst dasselbe Subjekt über mehrere Clips hinweg beibehalten (eine Figur, ein Maskottchen, mehrere Ansichten eines Produkts) → reference-to-video. Referenzbilder fixieren die Identität; der Prompt variiert pro Clip.

Produktionsmuster

Callbacks statt Polling

Für jeden Einsatz, der über ein Skript hinausgeht, registriere beim Erstellen der Aufgabe einen Webhook – Videotasks dauern lange, und Polling in einem Web-Request-Handler läuft früher oder später in einen Timeout:

{
  "model": "happyhorse-1.1/text-to-video",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Nur "when": "final" wird unterstützt – wenn die Aufgabe einen Endzustand erreicht, erhältst du genau einen POST (jeder andere Wert liefert invalid callback.when: only 'final' is supported zurück). Gestalte deinen Empfänger idempotent bezogen auf taskId: Speichere die Task-ID beim Absenden und behandle wiederholte oder bereits verarbeitete Callbacks als No-op. Halte einen niederfrequenten Polling-Sweeper als Fallback bereit, falls ein Callback wegen Netzwerkstörungen verloren geht.

Fehlerbehandlung: drei Arten von Fehlern

1. Validierungsfehler (HTTP 400, INVALID_REQUEST). Die Meldungen sind sehr präzise – lies sie, sie benennen das exakte Feld:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: duration: maximum: got 99, want 15; resolution: value must be one of '720p', '1080p'"
}

2. Authentifizierungs-/Berechtigungsfehler (HTTP 401, permission_denied). Der Schlüssel ist falsch, oder der Schlüssel hat keine Berechtigung für dieses Modell:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026..."
  }
}

Prüfe den Schlüssel in der Konsole und gib beim Kontakt mit dem Support die request_id an.

3. Generierungsfehler (Task status: "fail"). Die Übermittlung war erfolgreich, aber die Generierung ist fehlgeschlagen; beim Polling oder beim Empfang des Callbacks stehen die Fehlerdetails im Feld error des Task-Objekts. Diese Fehler lohnen einen Retry mit Backoff – Validierungs- und Authentifizierungsfehler nicht.

Kostenkontrolle

Die Abrechnung erfolgt nach generierten Videosekunden, daher ist duration dein wichtigster Kostenhebel – ein 15-Sekunden-Clip kostet dreimal so viel wie ein 5-Sekunden-Clip, während resolution einen geringeren Einfluss hat. Iteriere Prompts mit duration: 3 und 720p und rendere die finale Version in voller Länge. Aktuelle Tarife findest du auf der Preisseite.

Verwandte Lektüre

• happyhorse-1.1 Text-zu-Video – Modellseite und Playground
• happyhorse-1.1 Bild-zu-Video – Modellseite und Playground
• happyhorse-1.1 Referenz-zu-Video – Modellseite und Playground
• Kurzvideo-Workflows mit happyhorse-1.1
• hiapi-Dokumentation

FAQ

Kann ich Bild und Text-Prompt gleichzeitig verwenden? Ja – image-to-video akzeptiert zusätzlich zum erforderlichen image_urls einen optionalen prompt, und reference-to-video verlangt sowohl prompt als auch reference_image. Nur text-to-video arbeitet ausschließlich mit einem Prompt.

Wie viele Bilder kann ich übergeben? image-to-video: genau eines (image_urls ist auf 1 Element begrenzt). reference-to-video: bis zu neun in reference_image. Beide akzeptieren Arrays öffentlich zugänglicher URLs, keine Upload-Dateien und kein base64.

Unterstützt happyhorse-1.1 die Parameter seed, negative_prompt oder audio? Nein. Das Eingabe-Schema ist strikt und lehnt alle drei mit dem Fehler 400 additional properties not allowed ab. Wenn du Reproduzierbarkeit brauchst, halte Prompt und Parameter exakt gleich und versioniere sie auf deiner Seite.

Welche Auflösungen und Dauern sind verfügbar? Alle drei Endpunkte: 720p oder 1080p sowie 3 bis 15 Sekunden (ganzzahlig). Werden sie weggelassen, gelten Standardwerte.

Warum erhalte ich mit einem scheinbar gültigen Schlüssel 401 permission_denied? Der Schlüssel existiert, kann dieses Modell aber nicht verwenden – das ist bei eingeschränkten oder Testschlüsseln üblich. Prüfe die Modellberechtigungen des Schlüssels in der Konsole oder erzeuge einen neuen uneingeschränkten Schlüssel.

Wie erfahre ich ohne Polling, wann das Video fertig ist? Übergib beim Absenden callback: {"url": "...", "when": "final"}. Wenn die Aufgabe success oder fail erreicht, sendet hiapi einmalig einen POST an deine URL. Denk daran, dass Ausgabe-URLs ablaufen – lade die Datei im Callback-Handler herunter und verlinke sie nicht hot.