Tutorial

So rufen Sie happyhorse-1.1/image-to-video über die hiapi API auf: curl- und Python-Leitfaden

Nov 3, 2026

Was dieser Endpunkt tut und wann Sie ihn einsetzen

happyhorse-1.1/image-to-video verwandelt ein einzelnes Standbild in einen kurzen Clip. Sie senden ein Bild für das erste Frame an den Endpunkt, und das Modell erzeugt daraus eine Animation, die an diesem Frame ansetzt. Der eigentliche Nutzen liegt in der Kontinuität: Subjekt, Bildkomposition und Erscheinungsbild des Ausgangsbildes setzen sich im generierten Ausschnitt fort. Das ist es, was wir hier unter Identitätserhalt verstehen – das Modell erfindet keine völlig neue Szene nur aus einem Text-Prompt, sondern führt eine Szene fort, die Sie bereits mit einem Bild gestaltet haben.

Der Endpunkt eignet sich daher immer dann, wenn visuelle Identität wichtiger ist als Improvisation:

Sie haben bereits ein Referenz-Standbild – ein Porträt, ein Produktfoto, ein Character-Design – und möchten eine Bewegung, die diesem Standbild treu bleibt.
Sie produzieren Kurzfilme in einer Pipeline, in der alle anderen Assets zuerst als Bilder gestaltet werden.
Sie benötigen Animatics oder Bewegungsvorschauen auf Basis von Storyboard-Frames.

Weniger geeignet ist er, wenn das Modell eine Szene von Grund auf frei neu interpretieren soll oder wenn kein Standbild vorhanden ist, das die Ausgabe verankert. In diesen Fällen bedeutet ein bildorientierter Workflow meist, zuerst ein Ankerbild zu erzeugen und dieses Ergebnis dann an diesen Endpunkt zu übergeben.

Der Aufruf selbst ist asynchron: Sie reichen eine Aufgabe ein und fragen dann ab, bis das Video bereit ist. Der Rest dieses Leitfadens führt Sie durch diesen gesamten Lebenszyklus.

Bevor Sie die Anfrage senden

Vor dem ersten Aufruf müssen zwei Dinge vorbereitet sein.

API-Schlüssel

Alle Aufrufe laufen über die hiapi-Plattform, und der API-Schlüssel wird als Bearer-Anmeldeinformation angehängt. Bewahren Sie den Schlüssel in einer Umgebungsvariable auf und nicht in der Versionsverwaltung, damit derselbe Code sowohl in der lokalen Entwicklung als auch in CI funktioniert:

export HIAPI_API_KEY="your_key_here"

In Python lesen Sie ihn zur Laufzeit mit os.environ["HIAPI_API_KEY"]. Protokollieren Sie niemals den rohen Header-Wert.

Ein referenzierbares Bild für das erste Frame

Der Endpunkt benötigt ein Ausgangsbild. Entscheiden Sie bereits im Vorfeld, wie Sie es übergeben – als URL, die die Plattform abrufen kann, oder als hochgeladenes bzw. base64-kodiertes Asset, je nachdem, was Ihr Konto und die Endpunktdokumentation unterstützen. Wichtig ist, dass die Referenz zum Zeitpunkt der Einreichung stabil und erreichbar ist. Wenn die Aufgabe in die Warteschlange geraten kann, ist eine signierte URL, die in fünf Minuten abläuft, eine schlechte Wahl.

Es hilft außerdem, das erwartete Ausgabeseitenverhältnis und die Dauer vor dem Aufruf zu kennen, da das erste Frame diese häufig einschränkt. Diese Entscheidung frühzeitig zu treffen erspart späteres erneutes Einreichen.

Sobald der Schlüssel exportiert und die Bildreferenz festgelegt ist, können Sie einreichen.

Die Eingabe für das erste Frame zusammenstellen

Das erste Frame ist der Anker für alles, was das Modell danach erzeugt. In der Praxis sollten Sie es als Identitätsvertrag betrachten: Alles, was in diesem Bild deutlich sichtbar ist – Gesichter, Kleidung, Logos, Farbschemata, Kamerawinkel –, ist das, woran sich das Modell halten muss. Wenn ein Detail im Standbild unscharf oder verdeckt ist, wird auch die Ausgabe unscharf.

Unabhängig von den konkreten Modellparametern gelten die folgenden Vorbereitungsprinzipien:

Wählen Sie ein klares, gut beleuchtetes Frame. Kompressionsartefakte und starkes Rauschen verringern, was das Modell bewahren kann. Ein scharfes, gleichmäßig beleuchtetes Bild ist ein besserer Anker als ein dramatisches, aber unscharfes Bild.
Platzieren Sie das Subjekt dort, wo die Bewegung beginnen soll. Zuschneiden und Komponieren im Standbild ist günstiger, als vom Modell eine neue Bildkomposition zu erwarten.
Behalten Sie das Seitenverhältnis Ihrer erwarteten Ausgabe bei. Wenn das endgültige Video im Querformat sein soll, bereiten Sie ein Querformat-Ankerbild vor; späteres Auffüllen stellt die verlorene Komposition nicht wieder her.
Vermeiden Sie widersprüchliche Hinweise. Ein Standbild, das eine Bedeutung vermittelt, aber implizit eine Aktion außerhalb des Bildes andeutet, gibt dem Modell einen instabilen Ausgangspunkt.

Gehen Sie nicht von modellspezifischen Parametern außerhalb der Endpunktdokumentation aus. Der sicherste Ansatz ist, das Bild selbst die Absicht tragen zu lassen und die Anfragefelder nur das abdecken zu lassen, was sie ausdrücklich abdecken.

Eine funktionierende Anfrage mit curl senden

Das Einreichen einer Aufgabe erfordert nur einen einzigen POST. Die Struktur ist: eine authentifizierte Anfrage an den Endpunkt senden, wobei der JSON-Anfragetext den Modellbezeichner und die Bildeingabe enthält.

curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/image-to-video",
    "input": {
      "image": "https://your-bucket.example.com/first-frame.jpg"
    }
  }'

Schritt für Schritt:

Der Endpunkt. Das POST-Ziel ist die Videogenerierungsroute auf der hiapi API. Wenn Sie Skripte für mehrere Umgebungen schreiben, legen Sie sie in einer Variablen ab.
Der Authentifizierungsheader. Authorization: Bearer $HIAPI_API_KEY – die Shell expandiert die zuvor exportierte Umgebungsvariable.
Der Inhaltstyp. application/json, da der Anfragetext JSON ist.
Der Anfragetext. model wählt happyhorse-1.1/image-to-video; input.image ist Ihre Referenz für das erste Frame. Sehen Sie in der Endpunktreferenz nach, um den genauen Bildfeldnamen und die Struktur zu erfahren, die für Ihr Konto akzeptiert werden.

Eine erfolgreiche Antwort ist nicht das Video selbst – sondern ein Aufgaben-Handle. Erwarten Sie einen Bezeichner und ein Statusfeld, üblicherweise ähnlich wie queued oder processing. Notieren Sie sich diese ID; Sie werden sie in den folgenden Schritten zum Abfragen verwenden. Führen Sie den Befehl zunächst einmal aus und geben Sie die Antwort aus, damit Sie ihre Struktur sehen, bevor Sie mit dem Skripten beginnen.

Dieselbe Anfrage mit Python senden

Die Python-Version ist eine direkte Portierung, keine neue Integration. Dieselbe Route, dieselben Header, derselbe JSON-Anfragetext.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/video/generations"

payload = {
    "model": "happyhorse-1.1/image-to-video",
    "input": {
        "image": "https://your-bucket.example.com/first-frame.jpg"
    },
}

resp = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)

Hinweise zur Zuordnung:

requests mit json=payload serialisiert das Dictionary so wie der -d-String von curl – wenn Sie json= verwenden, setzen Sie Content-Type nicht zusätzlich manuell; die Bibliothek übernimmt das. Der oben explizit gesetzte Header ist harmlos, aber überflüssig.
raise_for_status() verwandelt HTTP-Fehler frühzeitig in eine Exception, bevor Sie beginnen, eine nicht existierende Aufgabe abzufragen.
timeout ist lediglich ein clientseitiger Schutz für den Einreichungsaufruf. Die Generierung läuft serverseitig und unterliegt ihm nicht.

Bewahren Sie das Payload in einer Variablen auf und verwenden Sie es wieder. Wenn Sie später das Modell oder das Bild ändern, sollten Sie nur ein Dictionary bearbeiten müssen, nicht zwei parallele Implementierungen.

Asynchrone Aufgaben und Abfragen behandeln

Die Bild-zu-Video-Generierung dauert länger als ein Request/Response-Zyklus. Daher gibt die API sofort eine Aufgabenreferenz zurück und erwartet, dass Sie später nachfragen. Der Lebenszyklus ist: einreichen, ID erhalten, Status abfragen, Ergebnis abrufen.

Extrahieren Sie die Aufgaben-ID aus der Einreichungsantwort – der Feldname hängt vom dokumentierten Antwortschema dieses Endpunkts ab, daher lesen Sie es einmal und hardcodieren Sie den Schlüsselzugriff, nicht den Wert:

job_id = job["id"]  # check the endpoint docs for the exact field

Fragen Sie dann in Intervallen ab:

import time

poll_url = f"https://api.hiapi.ai/v1/video/generations/{job_id}"

while True:
    status = requests.get(
        poll_url,
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    ).json()

    if status["status"] == "succeeded":
        break
    if status["status"] == "failed":
        raise RuntimeError(status)
    time.sleep(5)

Regeln für ein vernünftiges Abfragen:

Fragen Sie in festen Intervallen ab, nicht in einer engen Schleife. Bei Aufgaben dieser Größenordnung reichen einige Sekunden zwischen den Prüfungen; den Endpunkt zu hämmern erhöht die Last, bringt das Ergebnis aber nicht früher.
Begrenzen Sie die Gesamtwartezeit. Ein while True ohne Obergrenze ist ein Hänger, der früher oder später passiert. Verfolgen Sie die verstrichene Zeit und scheitern Sie nach einem vernünftigen Budget lautstark.
Behandeln Sie beide Endzustände. Erfolg und Misserfolg sind beides Antworten. Behandeln Sie unbekannte Statusstrings als nicht final, aber protokollieren Sie sie, damit Ihnen Musteränderungen auffallen.
Fragen Sie nicht von mehreren parallelen Workern für eine Aufgabe ab. Ein Abfrager pro Aufgabe oder Koordination über eine Warteschlange.

Sobald der Status final ist, fahren Sie mit dem Herunterladen des Ergebnisses fort.

Die Ausgabe herunterladen und speichern

Das fertige Video wird in der Antwort der abgeschlossenen Aufgabe als Asset bereitgestellt – üblicherweise eine URL, manchmal mit Ablaufzeit. Der erste Schritt nach einer erfolgreichen Abfrage ist, diese Referenz abzurufen und die Bytes in einen Speicher zu kopieren, den Sie kontrollieren.

video_url = status["output"]["video_url"]  # inspect the real response shape

with requests.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"out/{job_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 20):
            f.write(chunk)

Speicherhinweise, die für jede Pipeline gelten:

Kopieren Sie persistente Artefakte, verlinken Sie sie nicht. Signierte oder zeitlich begrenzte URLs sind Transportmittel, kein Speicher. Persistieren Sie die Datei und speichern Sie dann in Ihrer Datenbank Ihren eigenen Objektschlüssel zusammen mit der Aufgaben-ID.
Streamen Sie große Dateien. iter_content hält den Speicher stabil; das gesamte Video in eine Variable zu laden macht die Speicherobergrenze vom Asset abhängig.
Dokumentieren Sie die Herkunft. Speichern Sie job_id, die Bildreferenz der Eingabe und den Modellbezeichner zusammen mit dem Asset. Wenn Sie den Clip reproduzieren müssen, ist dieser Datensatz das Rezept.
Prüfen Sie den HTTP-Status vor dem Schreiben. Ein Teil-Schreibvorgang aufgrund einer Fehlerantwort ist schlimmer als ein sauberer Fehlschlag, weil er wie eine gültige Datei aussieht.

Sobald die Datei auf der Festplatte oder im Objektspeicher liegt, schließt sich der Kreis der Pipeline, und Sie können mit dem nächsten Frame fortfahren.

Fehler und Fallstricke, auf die Sie achten sollten

Die meisten Fehlschläge dieses Endpunkts sind vorhersehbar. Eine kurze Checkliste:

Eingabe des ersten Frames fehlerhaft oder nicht erreichbar. Der häufigste Grund für abgelehnte Einreichungen. Prüfen Sie, ob die Bild-URL öffentlich auflösbar ist, ob das Format vom Endpunkt akzeptiert wird und ob der Anfragetext das Bildfeld korrekt verschachtelt. Reproduzieren Sie mit einem curl-Aufruf, um Authentifizierungsprobleme von Payload-Problemen zu unterscheiden.
Abfragen, bevor die Aufgabe existiert. Die ID aus dem falschen Feld zu lesen oder eine Route abzufragen, die nicht zur Einreichungsantwort passt, erzeugt 404-Fehler, die wie Aufgabenfehler aussehen. Geben Sie die Einreichungsantwort einmal aus und fixieren Sie den Schlüsselzugriff darauf basierend.
Unbegrenztes Warten. Ohne Timeout bedeutet eine hängende Aufgabe, dass der Worker unbegrenzt blockiert. Legen Sie ein Budget fest, scheitern Sie und warnen Sie.
Verlorene Asset-Links. Die Generierung ist erfolgreich, aber die URL wird einmal konsumiert und nie kopiert. Speichern Sie die Bytes beim Abruf und behalten Sie Ihren eigenen Schlüssel; verlassen Sie sich nicht auf den zurückgegebenen Link als Langzeitspeicher.
Offenlegung von Anmeldeinformationen. Einen Schlüssel in ein Notebook zu kleben und versehentlich zu committen ist ein wiederkehrendes Problem. Laden Sie ihn aus der Umgebung und rotieren Sie ihn im Zweifel.
Annahme von nicht dokumentierten Endpunktparametern. Wenn Sie einen Parameter benötigen, der nicht aufgeführt ist, existiert er nicht. Drücken Sie die Absicht nur über das erste Frame und dokumentierte Felder aus.

Wenn Sie diese Punkte behandeln, wird der asynchrone Ablauf unspektakulär – genau das, was Sie in einer Produktionspipeline wollen. Halten Sie die Endpunktreferenz während der Entwicklung geöffnet, um endpunktspezifische Feldnamen und akzeptable Werte nachzuschlagen.