Tutorial
So verwenden Sie gemini-omni-flash/text-to-video über die HiAPI-API: ein Leitfaden mit curl und Python
Auf dieser Seite
Was dieser Endpunkt tut und wann Sie ihn verwenden
gemini-omni-flash/text-to-video ist ein Generierungsendpunkt auf HiAPI, der einen Text-Prompt – optional verankert durch ein Anfangsbild – in einen kurzen Clip umwandelt. Sie senden eine Anfrage, HiAPI gibt einen Job zurück, den Sie pollen können, und wenn der Job abgeschlossen ist, erhalten Sie eine Video-URL, die Sie herunterladen oder streamen können.
Dieser Endpunkt eignet sich für folgende Szenarien:
- Schnelle Konzeptclips. Erzeugen Sie kurze Marketing-Teaser, Storyboard-Vorschauen oder Social-Media-Übergänge direkt aus ein oder zwei Sätzen Beschreibung.
- Bildgeführte Bewegung. Sie haben bereits ein Standbild – ein Produktfoto, ein Charakterdesign, eine Illustration – und möchten es in Bewegung setzen, statt von Grund auf neu zu generieren.
- Batch-Generierung in Pipelines. Da die Generierung asynchron ist, können Sie von einem Backend-Worker aus viele Jobs auf einmal einreichen und die Ergebnisse später einsammeln, ohne die Anfrageverbindung offen zu halten.
Er ist nicht für lange Videos, frame-genaue Bearbeitung oder deterministische Reproduktion bestimmter Einstellungen geeignet. Betrachten Sie ihn als schnellen generativen Erstentwurf: kostengünstig zu iterieren, gut genug zum Prüfen, durchgängig skriptbar.
Alles im Folgenden läuft über dieselbe HiAPI-Schnittstelle – ein API-Schlüssel, eine Basis-URL, eine Anfragestruktur –, sodass Ihr hier geschriebener Code auf andere Generierungsendpunkte übertragen werden kann, ohne Authentifizierung oder Polling neu erlernen zu müssen.
Bevor Sie die erste Anfrage senden
Bevor der erste Aufruf erfolgreich ist, müssen vier Dinge bereitstehen.
1. API-Schlüssel
Erstellen Sie einen Schlüssel in Ihrem HiAPI-Konto und speichern Sie ihn in einer Umgebungsvariable statt im Quellcode:
export HIAPI_API_KEY="your_key_here"
2. Basis-URL und Endpunktpfad
Alle Anfragen gehen an die HiAPI-Basis-URL, wobei der Modellbezeichner im Pfad liegt. Behandeln Sie die Basis-URL im Code als eine einzige Konstante, sodass Sie sie nur an einer Stelle ändern müssen:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. JSON-Anfragekörper
Die Anfrage ist ein POST mit Content-Type: application/json und einem Bearer-Token im Authorization-Header. Es gibt keine Formularcodierung und keinen Multipart-Upload, es sei denn, Sie stellen das Anfangsbild über eine URL bereit.
4. Anfangsbild (optional)
Wenn Sie eine bildgeführte Generierung planen, stellen Sie zunächst sicher, dass das Bild über eine öffentliche HTTPS-URL erreichbar ist. Lokale Dateisystempfade funktionieren nicht – die API ruft das Bild serverseitig ab.
Ein praktischer Hinweis zum Kostenbewusstsein: Dieser Endpunkt wird nach der von Ihnen erzeugten Ausgabe abgerechnet – sowohl die Auflösungsstufe als auch die Clipdauer fließen ein. Prüfen Sie die aktuellen Stückpreise im HiAPI-PreisDashboard, bevor Sie Batch-Jobs hochskalieren. Die wichtige Gewohnheit: Prototypisieren Sie zuerst mit minimalen Einstellungen und erhöhen Sie diese erst, wenn der Prompt das gewünschte Ergebnis liefert.
Die Generierungsanfrage aufbauen
Eine Anfrage besteht konzeptionell aus drei Teilen: dem Modellpfad, dem Prompt (und optional dem Bild) und den Generierungsoptionen. Die Struktur sieht so aus:
{
"prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}
Der Prompt
Das Feld prompt enthält die Beschreibung der Einstellung. Schreiben Sie es wie Regieanweisungen: Motiv, Kamerabewegung, Licht und Atmosphäre. Konkrete Bewegungsverben („slow dolly-in“, „camera pans left“, „steam curls upward“) lenken das Ergebnis zuverlässiger als eine bloße Anhäufung von Adjektiven.
Das optionale Anfangsbild
Das Feld image ist optional. Lassen Sie es weg, generiert das Modell den gesamten Clip allein aus dem Text. Fügen Sie es hinzu, beginnt der Clip mit diesem Frame und der Prompt beschreibt, was als Nächstes geschehen soll. Dies ist der größte Hebel für Konsistenz: Ein reiner Text-Prompt erfindet die Szene bei jedem Lauf neu, während ein festes Anfangsbild die Komposition über mehrere Iterationen stabil hält.
Wenn Sie beides angeben, stellen Sie sicher, dass sie zueinander passen. Ein Anfangsbild einer Wüstenlandschaft zusammen mit einem Prompt über eine Stadtstraße im Regen führt zu einem wirren Ergebnis – das Modell muss zwei widersprüchliche Anweisungen miteinander vereinbaren.
Wo die Optionen hingehören
resolution, duration und audio stehen zusammen mit prompt und image auf der obersten Ebene desselben JSON-Körpers. Es gibt kein verschachteltes options-Objekt, das Sie sich merken müssten. Halten Sie den Anfragekörper flach und lesbar – das macht Logging und den Vergleich von Anfragen beim Debuggen von Batch-Jobs deutlich einfacher.
Auflösung und Dauer wählen
Zwei Parameter bestimmen sowohl das Aussehen der Ausgabe als auch die Jobkosten: die Auflösungsstufe und die Clipdauer.
Auflösungsstufen
HiAPI bietet diesen Endpunkt in mehreren Auflösungsstufen an. Eine niedrigere Stufe ist der passende Standard während der Prompt-Entwicklung – schnelleres Rendern, sodass Sie Formulierungen iterieren können, ohne für Details zu zahlen, die Sie ohnehin verwerfen. Sobald der Prompt zuverlässig die gewünschte Komposition liefert, wechseln Sie für das finale Rendering auf eine höhere Stufe.
Ein praktischer Workflow:
- Entwerfen Sie den Prompt auf der niedrigsten Stufe.
- Generieren Sie zwei oder drei Varianten und vergleichen Sie sie.
- Legen Sie den Prompt fest und rendern Sie dann auf einer höheren Stufe neu.
Clipdauer
Die Dauer wird in Sekunden angegeben, und der Endpunkt ist auf kurze Clips ausgelegt. Halten Sie die Dauer moderat: Kurze Clips machen einzelne Jobs schneller, Wiederholungsversuche bei Fehlern günstiger, und wenn Sie später eine längere Sequenz benötigen, können Sie mehrere Clips aneinanderreihen. Wenn eine Einstellung acht Sekunden Bildschirmzeit benötigt, sind zwei Vier-Sekunden-Generierungen oft leichter zu kontrollieren als eine lange Generierung.
Wie das aufs Budget einzahlt
Dieser Endpunkt wird nach der von Ihnen erzeugten Ausgabe abgerechnet – höhere Auflösung und längere Dauer erhöhen die abrechenbare Ausgabe eines einzelnen Jobs. Da die Preisgestaltung nach Generierungseinheiten erfolgt und sich die Stufen im Laufe der Zeit ändern, lesen Sie die aktuellen Zahlen im HiAPI-PreisDashboard, statt Erwartungen fest einzukodieren. Eine Planungsregel, die bei jeder Preisänderung gilt: Multiplizieren Sie die erwartete Anzahl an Jobs mit dem Ausgabevolumen, prototypisieren Sie mit minimalen Einstellungen und skalieren Sie die Auflösung zuletzt.
Natives Audio steuern
Das Flag audio bestimmt, ob das zurückgegebene Video eine native Tonspur enthält, die zusammen mit dem Bild generiert wird.
{
"prompt": "Rain hammering a tin roof, a door creaks open slowly",
"audio": true
}
Was sich bei Aktivierung ändert
Mit audio: true erzeugt das Modell Geräusche, die zur im Prompt beschriebenen Szene passen – Umgebungsgeräusche, Ambiente-Texturen und Klangereignisse, die durch die Handlung angedeutet werden. Das Ausgabevideo bringt eine Audiospur mit, sodass die heruntergeladene Datei bereits vollständig ist und keine separate Soundeffekt-Nachbearbeitung benötigt.
Was sich bei Deaktivierung ändert
Mit audio: false erhalten Sie ein stummes Video. Das ist sinnvoll, wenn:
- Sie Ihre eigene Musik oder Voiceover im Editor über den Clip legen werden.
- Der Clip ein Hintergrundelement in einer größeren Komposition ist.
- Sie nur das Bild iterieren und nicht möchten, dass die Audiogenerierung in den Zyklus eingeht.
Prompts für Audio schreiben
Wenn Sie Audio aktivieren, beschreiben Sie die Klangkulisse ebenso wie das Bild. Klanghinweise im Prompt – Regen, Schritte, mechanische Geräusche, eine bestimmte Raumatmosphäre – geben dem Audiomodell eine Grundlage. Ein rein visueller Prompt erzeugt trotzdem Audio, aber eher generisches Ambiente statt zum Shot passende Geräusche.
Ein Hinweis, den es sich lohnt, früh zu testen: Audio verändert den Charakter des Clips erheblich. Generieren Sie denselben Prompt einmal mit aktiviertem und einmal mit deaktiviertem Flag, sehen Sie sich beide an und entscheiden Sie, welchen Modus Ihr Projekt tatsächlich benötigt, bevor Sie Batch-Jobs darauf aufbauen.
Den asynchronen Job-Lebenszyklus behandeln
Die Videogenerierung dauert länger, als eine typische HTTP-Anfrage offen bleiben sollte, daher ist der Endpunkt asynchron. Jeder Aufruf folgt demselben dreistufigen Zyklus.
Schritt 1: Einreichen
Senden Sie den JSON-Körper per POST an den Endpunkt. Eine erfolgreiche Einreichung gibt sofort eine Job-Kennung zurück – in der Regel die Job-id – sowie einen Status, der angibt, dass der Job in der Warteschlange steht oder verarbeitet wird. Zu diesem Zeitpunkt ist noch nichts gerendert.
Schritt 2: Pollen
Mit der Job-ID fragen Sie den Job-Status-Endpunkt in festen Intervallen ab. Jede Abfrage liefert den aktuellen Status: queued, processing, completed oder failed. Sie müssen alle vier Zustände behandeln. Ein einfaches exponentielles Backoff – beginnend bei etwa zwei Sekunden mit einer Obergrenze für das Intervall – vermeidet, die API bei langen Jobs zu überlasten, während kurze Jobs dennoch schnell erfasst werden.
Schritt 3: Abrufen
Wenn der Status als abgeschlossen gemeldet wird, enthält die Antwort die URL des fertigen Videos sowie Metadaten zum Job. Laden Sie es herunter, speichern Sie es oder geben Sie die URL an das Frontend weiter. Wenn der Status als fehlgeschlagen gemeldet wird, erfassen Sie die Fehlermeldung aus der Antwort und entscheiden Sie, ob Sie den Prompt anpassen und erneut versuchen oder den Fehler sichtbar machen.
Schutzmechanismen, die Sie einbauen sollten
- Obergrenze für die Zeitüberschreitung. Begrenzen Sie die gesamte Polling-Zeit (z. B. auf einige Minuten) und markieren Sie den Job in Ihrem eigenen Code als fehlgeschlagen, statt in einer Endlosschleife zu hängen.
- Maximale Anzahl an Abfragen. Verhindern Sie eine außer Kontrolle geratene Schleife, wenn der Status dauerhaft unklar bleibt.
- Job-ID dauerhaft speichern. Schreiben Sie sie sofort nach Erhalt in eine Datenbank oder ein Log. Wenn der Prozess mitten im Polling abstürzt, können Sie wiederaufnehmen, statt neu zu generieren und doppelt zu zahlen.
- Idempotentes Einreichen. Reichen Sie aufgrund von Netzwerkproblemen nicht erneut ein, bevor Sie bestätigt haben, dass die erste Anfrage fehlgeschlagen ist; doppelte Jobs verbrauchen echte Ausgabe.
Wenn Sie diesen Zyklus einmal richtig hinbekommen, funktioniert er für alle asynchronen Endpunkte auf HiAPI.
Lauffähige curl- und Python-Beispiele
curl: Einreichen, Pollen, Abrufen
Setzen Sie Schlüssel und Basis-URL aus Umgebungsvariablen und reichen Sie dann ein:
curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}'
Die Antwort enthält die Job-ID. Entnehmen Sie der Antwort den Status-Endpunkt und pollen Sie:
curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Wiederholen Sie dies, bis der Status completed ist, entnehmen Sie dann die Video-URL aus dem Antwortkörper und laden Sie sie herunter:
curl -sS -o clip.mp4 "<VIDEO_URL>"
Python: derselbe Zyklus, gekapselt
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
def generate_video(prompt, image_url=None, resolution="720p",
duration=5, audio=False, timeout=300):
payload = {
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"audio": audio,
}
if image_url:
payload["image"] = image_url
resp = requests.post(
f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
headers=HEADERS, json=payload, timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"submitted: {task_id}")
deadline = time.time() + timeout
interval = 2
while time.time() < deadline:
status_resp = requests.get(
f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
)
status_resp.raise_for_status()
data = status_resp.json()
state = data.get("status")
if state == "completed":
return data["video_url"]
if state == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
interval = min(interval * 1.5, 10)
raise TimeoutError(f"job {task_id} did not finish in {timeout}s")
if __name__ == "__main__":
url = generate_video(
"A slow dolly-in on a glass coffee cup as steam curls upward, "
"morning light, shallow depth of field",
)
print("video ready:", url)
Das Skript reicht einen reinen Text-Job ein, pollt mit Backoff, erzwingt eine Obergrenze für die Zeitüberschreitung und gibt die fertige URL zurück. Übergeben Sie image_url=, um die Generierung an ein Anfangsbild zu verankern, oder setzen Sie audio=True, um natives Audio einzubeziehen. Von hier aus können Sie generate_video in eine Worker-Queue, eine FastAPI-Route oder eine Batch-Schleife einfügen – die Funktion ist eigenständig und zustandslos, abgesehen von der Job-ID, die sie erzeugt.
Häufige Fehlerstellen und wie man sie vermeidet
Die meisten fehlgeschlagenen Integrationen stoßen auf eines der folgenden fünf Probleme.
Ablehnung beim Einreichen wegen ungültiger Parameter
Die häufigste Ursache ist, dass die API den Anfragekörper nicht analysieren kann: fehlender prompt, Dauer außerhalb des unterstützten Bereichs oder eine nicht unterstützte Auflösungszeichenkette. Prüfen Sie die Endpunktreferenz auf zulässige Werte und validieren Sie vorab lokal. Ein kleines Hilfsmittel, das zulässige Werte vor dem Aufruf prüft, spart einen Roundtrip und eine verwirrende Fehlermeldung.
Anfangsbild nicht erreichbar
Die API ruft image serverseitig ab, daher kann eine URL, die im Browser funktioniert, dennoch fehlschlagen – private Buckets, signierte Links, die ablaufen, und Hotlink-Schutz verursachen dies. Verwenden Sie eine öffentlich lesbare HTTPS-URL und bestätigen Sie vor dem Einreichen, dass sie von außerhalb Ihres Netzwerks aufgelöst werden kann.
Polling aufgeben
Zwei Varianten desselben Fehlers: Nach der ersten processing-Antwort aufgeben und einen Fehler annehmen oder so aggressiv pollen, dass ein Rate Limit erreicht wird. Lösen Sie beides mit der oben gezeigten Backoff-Schleife mit Obergrenze: Pollen Sie nach Plan, behandeln Sie Nicht-Endzustände als normal und werfen Sie nur bei eindeutigem Fehlschlag oder Zeitüberschreitung eine Ausnahme.
Job-ID verloren
Wenn der Prozess nach dem Einreichen, aber vor dem Speichern des Ergebnisses abstürzt, ist der Job bezahlt, aber unzugänglich. Schreiben Sie die Job-ID sofort nach dem Einreichen in den persistenten Speicher und prüfen Sie beim Start, ob noch laufende IDs vorhanden sind, bevor Sie neue Jobs einreichen.
Zu große Ausgabe bei Skalierung
Große Batches mit hoher Auflösung und langer Dauer vervielfachen das Ausgabevolumen schnell, und die erzeugten Dateien sind teuer zu speichern und langsam auszuliefern. Prototypisieren Sie in kleinem Maßstab, rendern Sie das Finale einmal und halten Sie Regeln für den Speicher-Lebenszyklus bereit. Da die Abrechnung an die generierte Ausgabe gekoppelt ist, ist die günstigste Lösung fast immer ein kleinerer Prototyp-Iterationszyklus.
Gehen Sie diese Checkliste in einer Pre-Release-Umgebung durch, dann ist Ihr Produktionspfad reibungslos.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen