So rufen Sie hailuo-2.3/text-to-video über die HiAPI API auf: curl, Python und lauffähige Anfragebeispiele

Was der Endpunkt hailuo-2.3/text-to-video tut

Wenn Sie einen Text-Prompt haben und daraus einen kurzen Videoclip generieren möchten, ist hailuo-2.3/text-to-video der Endpunkt, den Sie suchen. Er nimmt einen Prompt in natürlicher Sprache entgegen, der Szene, Subjekt und die gewünschte Bewegung beschreibt, und liefert anschließend den generierten Videoclip zurück. Das Modell ist auf kurze Ausgaben abgestimmt und entfaltet seine Wirkung daher am besten, wenn Sie einen kompakten, in sich geschlossenen Moment statt einer langen Erzählung anfordern.

Auf HiAPI folgt der Aufruf demselben Muster wie andere asynchrone Generierungsendpunkte: Sie senden eine Anfrage, der Dienst nimmt den Auftrag an, und Sie fragen dann ab, bis das Ergebnis bereitsteht. Das macht den Endpunkt ideal für Backend-Pipelines – Content-Tools, Prototypengeneratoren, Batch-Aufträge oder jede Situation, in der Sie auf Abruf einige Sekunden Video benötigen, ohne dass jemand manuell im Videoschnittprogramm sitzt.

Die Anfrage enthält einen Prompt und einige wenige Generierungssteuerungsparameter; die Antwort enthält eine Auftragskennung und später die URL des fertigen Videos. Sie müssen weder GPUs noch Modellgewichte verwalten – HiAPI übernimmt die Berechnung und gibt einen Ausgabelink zurück. Wenn Sie andere Text-zu-Video-APIs verwendet haben, wird Ihnen die Gesamtform vertraut vorkommen, doch der Prompt-Stil von hailuo-2.3 belohnt eher das Nachdenken über physische Bewegung als reine visuelle Beschreibung (dazu später mehr).

Voraussetzungen und API-Zugangsdaten

Bevor Sie den ersten Aufruf machen, stellen Sie sicher, dass drei Dinge bereit sind:

• Ein API-Schlüssel aus Ihrem HiAPI-Konto. Behandeln Sie ihn wie ein Passwort: nicht in die Versionskontrolle aufnehmen, aus einer Umgebungsvariablen laden und bei einer Offenlegung rotieren.
• Ein HTTP-Client. Die Shell-Beispiele unten benötigen nur curl. Die Python-Beispiele benötigen Python 3.8+ und die Bibliothek requests (pip install requests).
• Die HiAPI-API-Basis-URL. Alle Anfragen gehen an den HiAPI-API-Host, der Endpunktpfad lautet hailuo-2.3/text-to-video. Sie authentifizieren sich, indem Sie einen Bearer-Token im Header Authorization senden.

Legen Sie den Schlüssel in einer Umgebungsvariablen ab, damit er nicht in Ihrem Code auftaucht:

export HIAPI_API_KEY="your_api_key_here"

In Python können Sie ihn mit os.environ["HIAPI_API_KEY"] auslesen. In curl referenzieren Sie dieselbe Variable mit $HIAPI_API_KEY.

Eine weitere Sache sollten Sie vorab entscheiden: Wo die generierten Videos gespeichert werden. Die API gibt eine URL der Ausgabe zurück; diese URL sollte zeitnah abgerufen und in Ihrem eigenen Bucket oder Dateisystem gespeichert werden – bauen Sie keine Pipeline, die davon ausgeht, dass die URL ein dauerhaftes Asset ist.

Lauffähige Anfrage mit curl

Hier ist ein vollständiger curl-Aufruf zum Einreichen eines Text-zu-Video-Auftrags. Ersetzen Sie den Prompt durch Ihre eigene Szenenbeschreibung. Der Anfragekörper ist JSON; die zentralen Felder sind der Prompt sowie die Generierungsparameter, die Dauer und Ausgabeform steuern.

curl -X POST "https://api.hiapi.ai/v1/hailuo-2.3/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Eine Glasmurmel rollt eine Holzrampe hinunter, beschleunigt und fällt auf einen steinernen Boden, springt zweimal und kommt zur Ruhe",
    "duration": 6
  }'

Nach erfolgreicher Einreichung wird ein JSON-Objekt mit einer Auftragskennung zurückgegeben. Ungefähr so:

{
  "id": "job_abc123",
  "status": "queued"
}

Der entscheidende Teil ist die id. Die Generierung erfolgt nicht synchron – der Endpunkt stellt den Auftrag in die Warteschlange und kehrt sofort zurück. Speichern Sie die id; mit ihr fragen Sie den Status ab und erhalten schließlich die Video-URL.

Wenn ein Authentifizierungsfehler auftritt, prüfen Sie, ob der Schlüssel in derselben Shell-Sitzung exportiert wurde. Bei einem Validierungsfehler prüfen Sie, ob der JSON-Anfragekörper korrekt formatiert ist und der Prompt vorhanden ist. Eine 429-Antwort bedeutet, dass Sie Anfragen zu schnell senden, und Sie sollten zurückweichen – der Abschnitt zur Produktionsumgebung erläutert dies im Detail.

Derselbe Aufruf in Python

Die Python-Version macht dasselbe, ist aber in eine wiederverwendbare Funktion gekapselt, damit Sie sie in Ihre Pipeline aufnehmen können. Sie reicht den Auftrag ein und gibt die Auftragskennung zurück.

import os
import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"


def submit_text_to_video(prompt: str, duration: int = 6) -> str:
    """Reicht einen hailuo-2.3/text-to-video-Auftrag ein und gibt dessen Auftrags-ID zurück."""
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE}/hailuo-2.3/text-to-video",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"prompt": prompt, "duration": duration},
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()
    return data["id"]


if __name__ == "__main__":
    job_id = submit_text_to_video(
        "Eine Glasmurmel rollt eine Holzrampe hinunter, beschleunigt und fällt auf einen steinernen Boden, springt zweimal und kommt zur Ruhe"
    )
    print("submitted job:", job_id)

Einige Details sollten Sie beibehalten:

• raise_for_status() wandelt Nicht-2xx-Antworten in Ausnahmen um – genau das gewünschte Verhalten in einer Pipeline. In der Einreichungsphase laut zu scheitern ist besser, als einen Auftrag abzufragen, der nie erstellt wurde.
• Der Timeout der Einreichungsanfrage ist bewusst kurz gewählt. Das Einreichen sollte schnell gehen; lange Wartezeiten entstehen in der Polling-Phase, nicht hier.
• Der Parameter duration ist ein separater Parameter, sodass Aufrufer kürzere oder längere Clips anfordern können, ohne die Logik zum Aufbau der Anfrage zu duplizieren.

Sobald diese Funktion zurückkehrt, haben Sie alles, was Sie für die Statusabfrage benötigen.

Bewegungspysik-Prompts für 6-10-Sekunden-Clips schreiben

Kurze Clips verzeihen wenig. In sechs bis zehn Sekunden können Sie keine Figur etablieren, keine Welt aufbauen und keinen Handlungsbogen abschließen – daher sind die wirksamsten Prompts solche, die eine einzelne durchgehende Aktion mit klaren physischen Konsequenzen beschreiben. Stellen Sie sich den Prompt als Momentaufnahme einer Kamerabeschreibung vor, nicht als Geschichte.

Mit Subjekt und Aktion beginnen

Beginnen Sie damit, was sich bewegt und was es tut. „Eine Glasmurmel rollt eine Holzrampe hinunter“ gibt dem Modell sofort Subjekt, Material und Bewegungsrichtung. Ein vager Anfang wie „eine schöne Szene“ gibt ihm nichts, was sich animieren ließe.

Kräfte beschreiben, nicht nur Aussehen

Bewegungspysik-Prompts bedeuten, die wirkenden Kräfte zu benennen: Schwerkraft, Reibung, Impuls, Gewicht, Elastizität. Wörter wie rollen, beschleunigen, springen, zur Ruhe kommen, schwingen, umkippen, spritzen, zerreißen deuten auf ein physikalisches Modell hin. Bei einem springenden Objekt geben Sie an, wie oft es springt und wo es schließlich zum Stillstand kommt. Bei einem fallenden Objekt geben Sie an, worauf es fällt und ob es zerbricht, eindellt oder zurückprallt.

Kamera explizit und einfach halten

Eine feste Kamera oder eine einzige langsame Kamerabewegung reicht für einen kurzen Clip in der Regel aus. Wenn Kamera und Subjekt beide komplexe Dinge tun, wird der Clip unruhig und die Bewegung wirkt wie Rauschen. Geben Sie den Kameratyp nur an, wenn er für die Aktion wichtig ist – Nahaufnahme, Weitwinkel, Mitverfolgung.

Einen Ereignisbogen aufbauen

Eine nützliche Vorlage für 6–10-Sekunden-Clips ist: Aufbau → Aktion → Konsequenz. Die Murmel liegt oben auf der Rampe; sie rollt hinunter und beschleunigt; sie fällt, springt zweimal und kommt zur Ruhe. Dieser Bogen gibt dem Modell Anfang, Mitte und Ende, und alles passt in die Clip-Länge. Vermeiden Sie die Anforderung mehrerer unzusammenhängender Aktionen; ein gut beschriebenes physisches Ereignis liest sich weit besser als drei halbherzige Ereignisse.

Bleiben Sie schließlich konkret. Material, Beleuchtung und Oberflächentextur helfen dem Modell, die Bewegung zu verankern – eine Murmel auf Holz verhält sich anders als eine Murmel auf Eis, und das anzugeben lenkt das Ergebnis.

Asynchrone Aufträge durch Polling handhaben

Die Generierung braucht Zeit, daher ist der Endpunkt asynchron. Nach dem Einreichen des Auftrags erhalten Sie eine id; anschließend fragen Sie den Status-Endpunkt ab, bis der Auftrag einen Endzustand erreicht. Eine robuste Polling-Schleife behandelt drei Dinge: Intervall, Timeout und Fehleroffenlegung.

import time
import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"


def wait_for_video(job_id: str, api_key: str, interval: float = 3.0, max_wait: float = 600.0) -> str:
    """Fragt ab, bis der Auftrag abgeschlossen ist, und gibt die Ausgabe-Video-URL zurück."""
    deadline = time.time() + max_wait
    url = f"{HIAPI_BASE}/hailuo-2.3/text-to-video/{job_id}"

    while time.time() < deadline:
        response = requests.get(
            url,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()
        status = data.get("status")

        if status == "completed":
            return data["output"]["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Auftrag {job_id} endete mit Status {status}: {data.get('error')}")

        time.sleep(interval)

    raise TimeoutError(f"Auftrag {job_id} wurde nicht innerhalb von {max_wait} Sekunden abgeschlossen")

Hinweise zu dieser Schleife:

• In Intervallen abfragen, nicht in einer engen Schleife. Einige Sekunden zwischen den Prüfungen reichen aus und vermeiden, die API zu überlasten.
• Immer die Gesamtwartezeit begrenzen. Ein hängender Auftrag sollte keinen Worker unbegrenzt blockieren. Der max_wait-Wert hier ist konservativ; passen Sie ihn an Ihre Clip-Länge und die Warteschlangenlage an.
• failed als echten Zweig behandeln. Legen Sie die Fehlernutzlast offen, statt blind erneut zu versuchen – Probleme mit Prompt oder Parametern lösen sich nicht von selbst.
• Die Video-URL zurückgeben, nicht die rohe Antwort. Aufrufer dieser Funktion sollten die Antwortstruktur nicht kennen müssen.

Für schwerere Workloads legen Sie Einreichungs- und Polling-Schritte in verschiedene Worker-Prozesse: Ein Worker stellt Aufträge in die Warteschlange und speichert die Auftrags-ID, ein anderer übernimmt Polling und Download. So entkoppeln Sie Anforderungslatenz von Generierungszeit.

Ausgabe herunterladen und speichern

Sobald das Polling eine Video-URL zurückgibt, rufen Sie die Bytes ab und schreiben sie an einen dauerhaften Ort. Tun Sie dies zeitnah: Die zurückgegebene URL ist ein Auslieferungslink, kein dauerhafter Asset-Speicher. Laden Sie streamingweise herunter, statt die gesamte Datei in den Speicher zu laden; schreiben Sie zuerst in einen temporären Pfad und benennen Sie dann um, damit ein teilweiser Download nie wie eine fertige Datei aussieht.

import os
import tempfile
import requests


def download_video(video_url: str, dest_path: str) -> None:
    """Schreibt das fertige Video atomar per Streaming nach dest_path."""
    os.makedirs(os.path.dirname(dest_path) or ".", exist_ok=True)
    with requests.get(video_url, stream=True, timeout=120) as response:
        response.raise_for_status()
        fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(dest_path) or ".")
        try:
            with os.fdopen(fd, "wb") as f:
                for chunk in response.iter_content(chunk_size=1 << 16):
                    f.write(chunk)
            os.replace(tmp_path, dest_path)
        except Exception:
            if os.path.exists(tmp_path):
                os.unlink(tmp_path)
            raise


api_key = os.environ["HIAPI_API_KEY"]
video_url = wait_for_video("job_abc123", api_key)
download_video(video_url, f"out/{'job_abc123'}.mp4")

Einige praktische Entscheidungen:

• Dateien nach Auftrags-ID benennen. Das gibt Ihnen einen stabilen, kollisionsresistenten Schlüssel und macht es kinderleicht, die Datei wieder der Anfrage zuzuordnen, die sie erzeugt hat.
• Metadaten zusammen mit dem Video speichern. Bewahren Sie den ursprünglichen Prompt, die Dauer und den Zeitstempel in einer begleitenden JSON-Datei oder Datenbank auf. In sechs Monaten werden Sie wissen wollen, wodurch ein Clip entstanden ist.
• In der Produktion in Objektspeicher hochladen. Das Schreiben auf die lokale Festplatte ist für Prototypen in Ordnung; echte Pipelines sollten die Dateien in Ihren Bucket pushen und den Objektschlüssel protokollieren, damit Videos einen Neustart des Workers überleben.

Tipps für die Produktion und häufige Fehlermuster

Die meisten Erstintegrationen scheitern an denselben Stellen. Auf Folgendes sollten Sie achten.

Das Richtige erneut versuchen

Wiederholen Sie bei transienten Fehlern – Netzwerkfehler, Timeouts, 429- und 5xx-Antworten – mit exponentiellem Backoff und Jitter. Wiederholen Sie keine 4xx-Validierungsfehler; ein fehlerhaft formatierter Prompt oder falsche Parameter schlagen jedes Mal auf dieselbe Weise fehl. Wenn der Generierungsauftrag selbst fehlschlägt, legen Sie den Fehler offen und entscheiden Sie sorgfältig, ob Sie erneut einreichen.

Einreichen und Polling trennen

In der Produktion sollten Einreichen und Polling getrennte Schritte sein, üblicherweise in verschiedenen Prozessen. Speichern Sie die Auftrags-ID unmittelbar nach erfolgreicher Einreichung in einer Warteschlange oder Datenbank. Wenn ein Worker abstürzt, können Sie das Polling wieder aufnehmen, statt den Auftrag zu verlieren.

Überall Timeouts setzen

Einreichungsanfrage, Statusabfrage und Dateidownload sollten jeweils eigene Timeouts haben. Ein fehlender Timeout beim Download-Schritt ist eine klassische Ursache für hängende Worker.

Prompts im Stärkebereich des Modells halten

Fordern Sie im Bereich von sechs bis zehn Sekunden eine einzige, physikalisch plausible Aktion an. Wenn ein Prompt zu viel verlangt, erhalten Sie einen unruhigen Clip mit verwaschener Bewegung. Wenn die Ausgabequalität schwankt, kürzen Sie zuerst den Prompt und vereinfachen Sie die Aktion, bevor Sie Parameter ändern.

Zugangsdaten korrekt behandeln

Laden Sie den API-Schlüssel aus Umgebungsvariablen oder einem Secret-Manager, niemals aus einer eingecheckten Datei. Verwenden Sie pro Umgebung einen anderen Schlüssel, damit ein offengelegter Entwicklungsschlüssel nicht die Produktion erreichen kann.

Annahmen über ablaufende URLs vermeiden

Der häufigste Fehler in der Produktion ist, die zurückgegebene Video-URL als permanenten Link zu behandeln und sie Monate später direkt in der Benutzeroberfläche zu rendern. Machen Sie das Herunterladen und erneute Hosten der Datei zum Teil des Auftrags und speichern Sie Ihre eigene URL.

Mit diesen Gewohnheiten ist die Integration überschaubar: einreichen, abfragen, herunterladen, speichern.