So rufen Sie veo-3.1-lite/text-to-video über die HiAPI API auf: curl und Python

Was veo-3.1-lite/text-to-video für Sie leistet

veo-3.1-lite/text-to-video ist ein Text-zu-Video-Endpunkt auf HiAPI: Sie senden einen Text-Prompt, und das Modell gibt einen generierten Videoclip zurück. Das "lite" im Namen ist das entscheidende Signal bei der Modellwahl. Die Lite-Stufe ist auf Durchsatz und schnelle Iteration ausgelegt, nicht auf höchste Wiedergabetreue. Sie ist daher eine gute Standardwahl, wenn Sie viele kurze Clips benötigen, Funktionen prototypisieren möchten, bevor Sie sich für ein schwergewichtigeres Modell entscheiden, oder wenn der Clip nur ein Glied in einer größeren Automatisierungspipeline ist und Latenz pro Clip sowie Batch-Größe wichtiger sind als filmreife Qualität.

Wenn der Clip selbst das Produkt ist – etwa ein Key-Visual-Shot, Marketingmaterial oder Inhalte, die Bild für Bild geprüft werden –, sollten Sie stattdessen ein schwergewichtigeres Text-zu-Video-Modell verwenden. Wenn der Clip nur ein Baustein ist – etwa eine Entwurfsvorschau, eine Hintergrundschleife, ein grober Storyboard-Entwurf oder ein erster Render, der später verfeinert wird –, wählen Sie veo-3.1-lite/text-to-video.

Zwei Eigenschaften dieses Endpunkts bestimmen alles Weitere:

• Er ist asynchron. Eine Generierungsanfrage liefert nicht in derselben Antwort direkt eine abspielbare Datei. Sie übermitteln einen Job, erhalten einen Verweis auf diesen Job und fragen dann so lange ab, bis der Job abgeschlossen ist und eine Ausgabe-URL verfügbar ist.
• Er wird durch Prompts gesteuert. In diesem Ablauf gibt es kein Eingabebild und kein Quellvideo – der von Ihnen gesendete Text ist das vollständige kreative Briefing. Die Prompt-Qualität ist daher der wichtigste Hebel, den Sie in der Hand haben.

Der Rest dieser Anleitung ist eine praktische Übung: Anfrage aufbauen, mit curl übermitteln, nach Python übertragen, korrekt abfragen und mit den Fehlerfällen umgehen, die Ihnen tatsächlich begegnen werden.

Voraussetzungen und Authentifizierung

Stellen Sie vor dem ersten Aufruf sicher, dass Sie Folgendes haben:

• Einen API-Schlüssel aus Ihrem HiAPI-Konto. Behandeln Sie ihn so sorgfältig wie ein Datenbankpasswort und als vertraulich.
• Eine Möglichkeit, HTTP-Anfragen zu senden: curl für schnelle Prüfungen und Python 3 mit der requests-Bibliothek für alle skriptgesteuerten Aufgaben.
• Einen Speicherort für den fertigen Clip, denn die Ausgabe kommt als URL an, die Sie herunterladen müssen.

Der Schlüssel wird bei jeder Anfrage über einen HTTP-Header übergeben. Übernehmen Sie den Header-Namen und das Bearer-Präfix genau wie gezeigt; ein fehlender oder falsch formatierter Header ist die häufigste Ursache für einen fehlgeschlagenen ersten Aufruf.

Den Schlüssel aus der Versionsverwaltung heraushalten

Kleben Sie niemals einen echten Schlüssel in eine Datei, die Sie committen würden. Verwenden Sie stattdessen Umgebungsvariablen:

export HIAPI_API_KEY="your-key-here"

Lesen Sie ihn dann zur Laufzeit aus. Wenn Sie im Team oder in einer CI-Pipeline arbeiten, bewahren Sie den Schlüssel in einem Secret Manager auf und injizieren Sie ihn beim Deployment als Umgebungsvariable. Wenn ein Schlüssel jemals offengelegt wurde – etwa durch einen versehentlichen Commit, durch Einfügen in ein Ticket oder durch Ausgabe in ein Log –, rotieren Sie ihn sofort, statt darauf zu hoffen, dass es niemand bemerkt.

Bevor Sie irgendetwas anderes debuggen, prüfen Sie schnell, ob die Umgebungsvariable gesetzt ist:

test -n "$HIAPI_API_KEY" && echo "key is set" || echo "key is missing"

Eine funktionierende curl-Anfrage

Im Folgenden sehen Sie die Form der Übermittlungsanfrage für Text-zu-Video. Ersetzen Sie die Platzhalter-Basis-URL des Endpunkts durch die in Ihrer HiAPI-Referenz dokumentierte Adresse und lassen Sie den Modellbezeichner unverändert: veo-3.1-lite/text-to-video.

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "prompt": "A slow dolly-in on a rain-soaked neon sign at night, shallow depth of field, gentle camera drift, cinematic color"
  }'

Eine erfolgreiche Übermittlung gibt keine Videobytes zurück. Sie gibt ein Job-Objekt zurück: mit der Kennung des Jobs, einem Status-Feld, das anfangs etwa queued oder processing lautet, und Metadaten zum Erstellungszeitpunkt. Diese Kennung ist der Handle für alles Weitere – Sie fragen sie ab, bis der Status einen Endzustand erreicht, und erst dann enthält die Antwort die URL des generierten Clips.

Wenn Sie manuell testen, erfassen Sie die vollständige Antwort, statt nur hinzusehen:

curl -s -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1-lite/text-to-video","prompt":"A paper boat drifting down a sunlit gutter, macro lens"}' \
  | tee submission.json

Zwei Gewohnheiten lohnen sich, gleich jetzt anzunehmen. Erstens: Senden Sie immer Content-Type: application/json; ein Request-Body, der wie JSON aussieht, aber nicht als JSON deklariert ist, wird abgelehnt. Zweitens: Wenn der Aufruf fehlschlägt, lesen Sie zuerst den Fehler-Response-Body, bevor Sie irgendetwas ändern – HiAPI liefert strukturierte Meldungen, die das Problem (falscher Schlüssel, unbekanntes Modell, fehlendes Feld) in der Regel präziser benennen als der bloße Statuscode.

Wenn hier ein Nicht-2xx-Statuscode zurückkommt, wurde der Job nie angenommen. Fragen Sie bei einer fehlgeschlagenen Übermittlung nicht ab; reparieren Sie zuerst die Anfrage.

Dieselbe Anfrage in Python

Der curl-Aufruf lässt sich direkt übertragen. Das folgende Skript übermittelt den Prompt, prüft, ob die Übermittlung erfolgreich war, und speichert die Job-Referenz für den Abfrageschritt.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "veo-3.1-lite/text-to-video",
    "prompt": (
        "A single lantern floating on still black water, "
        "soft ripples, warm light against cool darkness, slow push-in"
    ),
}

response = requests.post(
    f"{BASE_URL}/v1/videos/generations",
    headers=headers,
    json=payload,
    timeout=30,
)

if response.status_code >= 400:
    raise RuntimeError(f"Submission failed: {response.status_code} {response.text}")

job = response.json()
job_id = job["id"]
print(f"submitted job {job_id} with status {job.get('status')}")

Einige Entscheidungen in diesem Snippet sind bewusst getroffen:

• json=payload statt manuell zusammengesetzter Strings. Überlassen Sie der Bibliothek das Serialisieren und das Setzen des Content-Typs; das vermeidet eine ganze Klasse von Anführungszeichen-Bugs.
• Explizit gesetztes timeout. Ohne dies kann eine hängende Verbindung das Skript unbegrenzt blockieren. Der Übermittlungsaufruf ist schnell – selbst ein großzügiges Timeout ist hier noch kurz.
• Harter Fehler bei Nicht-2xx. Sofortiges Werfen einer Exception hält den Fehler nah an seiner Ursache, statt eine beschädigte Job-ID in die Abfrageschleife weiterzureichen.
• Der Schlüssel stammt aus os.environ. In die Datei selbst wird kein Geheimnis geschrieben.

Wenn Sie dies in eine Funktion kapseln, die job_id zurückgibt, haben Sie den Übermittlungsteil jeder Pipeline.

Asynchrone Jobs abfragen und den Clip herunterladen

Die Videogenerierung braucht Zeit. Der Übermittlungsaufruf kehrt in ein bis zwei Sekunden zurück; das eigentliche Rendering nicht. Wenn Sie Code schreiben, der davon ausgeht, dass die erste Antwort die Video-URL enthält, wird er fehlschlagen – nicht weil die API defekt ist, sondern weil Sie einen noch nicht abgeschlossenen Job auslesen.

Das richtige Muster ist begrenztes Polling: zwischen den Prüfungen schlafen, den Abstand mit zunehmender Wartezeit vergrößern und nach einer festgelegten maximalen Anzahl von Versuchen aufgeben, statt endlos zu schleifen.

import time
import requests

def wait_for_video(job_id, headers, base_url, max_attempts=60, initial_delay=5):
    delay = initial_delay
    for attempt in range(1, max_attempts + 1):
        r = requests.get(
            f"{base_url}/v1/videos/generations/{job_id}",
            headers=headers,
            timeout=30,
        )
        if r.status_code >= 400:
            raise RuntimeError(f"Poll failed: {r.status_code} {r.text}")

        data = r.json()
        status = data.get("status")
        print(f"attempt {attempt}: {status}")

        if status == "completed":
            return data
        if status in {"failed", "cancelled"}:
            raise RuntimeError(f"Job {job_id} ended as {status}: {data}")

        time.sleep(delay)
        delay = min(delay * 1.5, 30)

    raise TimeoutError(f"Job {job_id} did not finish within polling budget")

Wenn der Job completed erreicht, enthält die Antwort den Ausgabeort – die URL des fertigen Clips. Wenn der Clip groß ist, laden Sie ihn herunter, statt ihn in den Speicher zu streamen:

result = wait_for_video(job_id, headers, BASE_URL)
video_url = result["output"]["url"]

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

print("saved", f"{job_id}.mp4")

Zwei Details sind im Produktivbetrieb wichtig. Erstens können Ausgabe-URLs zeitlich begrenzt sein; laden Sie daher zeitnah herunter, statt den Link tagelang zu speichern und später abzurufen – persistieren Sie die Datei oder kopieren Sie sie in Ihren eigenen Speicher. Zweitens sollten Sie neben jedem Artefakt die Job-ID festhalten. Wenn später in der nachgelagerten Verarbeitung etwas schiefgeht, können Sie mit der Job-ID Ihre eigenen Aufzeichnungen mit dem abgleichen, was die API tatsächlich zurückgegeben hat.

Häufige Fehler und wie man sie behebt

Die meisten Fehler beim ersten Lauf fallen in wenige Kategorien. Im Folgenden sehen Sie, wie sich jede äußert und was geändert werden muss.

Authentifizierungsfehler

Ein 401 oder 403 bei der Übermittlung bedeutet, dass der Schlüssel nicht akzeptiert wird. Prüfen Sie der Reihe nach: ob die Umgebungsvariable in dieser Shell bzw. diesem Prozess tatsächlich einen Wert hat; ob der Header-Name Authorization lautet; ob das Bearer -Präfix vorhanden ist und danach ein Leerzeichen folgt; ob der Schlüssel rotiert oder widerrufen wurde. Ein Schlüssel, der in Ihrem Terminal funktioniert, aber in der CI fehlschlägt, bedeutet fast immer, dass das Secret nicht in diese Umgebung injiziert wurde.

Ungültiger Modellbezeichner

Ein 400 oder 404 mit Hinweis auf den Modellnamen bedeutet, dass der String nicht übereinstimmt. Der Bezeichner lautet veo-3.1-lite/text-to-video – der Schrägstrich und die Versionsnummer gehören dazu. Kopieren Sie ihn ein, statt ihn neu zu tippen; ein überflüssiges Leerzeichen oder eine veränderte Versionsnummer genügt, um einen Fehler auszulösen.

Fehlerhaftes oder leeres Prompt

Ein leeres prompt, ein fehlendes prompt-Feld oder ein Request-Body ohne Content-Type: application/json wird abgelehnt, bevor die Generierung beginnt. Wenn Sie Prompts dynamisch zusammenbauen, protokollieren Sie bei einem fehlgeschlagenen Aufruf den genauen String, den Sie gesendet haben – Template-Bugs, die leere oder abgeschnittene Prompts erzeugen, sind häufig und bleiben bis zur Ausgabe unsichtbar.

Polling-Timeout

Wenn wait_for_video sein Budget aufgebraucht hat, übermitteln Sie nicht sofort erneut. Der Job läuft möglicherweise einfach noch. Prüfen Sie den Status erneut, vergewissern Sie sich, dass Ihr Polling-Intervall nicht so lang ist, dass das Budget im Schlafen verbraucht wird, und stellen Sie sicher, dass das Budget für die angeforderte Cliplänge realistisch ist. Bei jedem Timeout neu zu übermitteln ist genau der Grund, warum Sie versehentlich mehrfach für denselben Clip bezahlen.

Rate-Limits

429 bedeutet, dass Sie sich zurückhalten müssen. Die exponentielle Verzögerung in der Abfrageschleife hilft hier bereits; wenden Sie dieselbe Zurückhaltung auch auf die Übermittlung an und reihen Sie Arbeit ein, statt sie stoßweise zu senden. Im Zweifel befolgen Sie zuerst etwaige Retry-Hinweise in den Response-Headern, bevor Sie Ihren eigenen Backoff-Plan anwenden.

Kosten- und Iterationstipps vor dem Produktivbetrieb

Die Videogenerierung wird nach Ausgabe abgerechnet – also nach der Länge des von Ihnen erzeugten Inhalts –, weshalb der teuerste Fehler darin besteht, kleine Ideen mit langen Clips zu testen. Der günstigste Workflow ist der, der niemals Clips erzeugt, die Sie nicht brauchen.

Testen Sie die Prompt-Struktur, nicht die finale Ausgabe. Schreiben und optimieren Sie Prompts für die kürzeste vom Endpunkt unterstützte Dauer. Sobald Bildkomposition, Bewegung und Bildsprache im kurzen Clip stimmen, erhöhen Sie die Dauer für das finale Rendering. Die meisten Prompt-Iterationen betreffen die Formulierung, nicht die Länge, und kurze Renderings beantworten Formulierungsfragen ebenso gut.

Führen Sie ein Prompt-Log. Notieren Sie zu jedem Test den Prompt, die Dauer und Ihre eigene Bewertung. Zehn dokumentierte Iterationen vermitteln Ihnen mehr darüber, worauf das Modell reagiert, als fünfzig undokumentierte, und Sie testen keine bereits verworfenen Prompts erneut.

Bündeln Sie bewusst. Wenn Sie viele Clips benötigen, reihen Sie sie ein und führen Sie sie im Rahmen der Rate-Limits parallel aus – aber machen Sie zuerst einen Probelauf des gesamten Batches mit wenigen Prompts. Einen systematischen Prompt-Bug erst nach der Übermittlung von zweihundert Jobs zu entdecken, ist der am leichtesten vermeidbare Kostenfaktor.

Fragen Sie maßvoll ab. Häufiges Polling beschleunigt das Rendering nicht und kann Sie in Rate-Limits treiben. Ein moderates Anfangsintervall plus sanfter Backoff ist der richtige Standard.

Scheitern Sie früh und deutlich. Jede Schutzmaßnahme im obigen Code – Exception bei Nicht-2xx während der Übermittlung, Erkennung von Endzustandsfehlern beim Polling, begrenzte Versuchsanzahl – dient dazu, dass Sie nicht zweimal für dieselbe Arbeit bezahlen. Behalten Sie sie im Produktivbetrieb bei.

Beginnen Sie mit einem kurzen Prompt und einer curl-Anfrage, bestätigen Sie den Job-Lebenszyklus von Ende zu Ende und überführen Sie dann denselben Ablauf in Ihre Python-Pipeline. Die vollständige Endpunkt-Referenz finden Sie auf der HiAPI-Modellseite zu veo-3.1-lite/text-to-video.