Blog

Tutorial

Wie man mit der HiAPI API Videos mit gemini-omni-flash generiert

Die Anfragepfade für Text-zu-Video und Bild-zu-Video, die Modellwahl und eine praktische Integrations-Checkliste

Nov 9, 2026
Ein geometrisches Cover aus geteilten Prismen in Salbei- und tiefen Pinientönen, das das Titelbild des Artikels kennzeichnet.
Auf dieser Seite

Warum gemini-omni-flash zwei Video-Endpunkte hat

Bevor man die erste Codezeile schreibt, ist die wichtigste Entscheidung: Welchen der beiden Video-Endpunkte braucht man eigentlich? gemini-omni-flash wird auf HiAPI als zwei separate Modelle angeboten, nicht als ein Endpunkt mit einem Modus-Flag:

  • gemini-omni-flash/text-to-video – generiert Videos ausschließlich anhand eines Text-Prompts.
  • gemini-omni-flash/image-to-video – nutzt ein bereitgestelltes Quellbild als visuellen Anker und generiert das Video unter Anleitung eines Text-Prompts.

Die Aufteilung existiert, weil die beiden Aufgaben unterschiedliche Eingaben, unterschiedliche Validierungsregeln und unterschiedliche Fehlermuster haben. Text-zu-Video muss nur einen Prompt-String validieren. Bild-zu-Video muss zusätzlich das Quellbild abrufen und dekodieren, wodurch eine ganze Klasse von Fehlern entsteht (URL nicht erreichbar, Format nicht unterstützt, Ressource zu groß), die auf dem Textpfad gar nicht auftritt.

Faustregel: Wenn man bereits ein statisches Bild hat – Produktfoto, Storyboard-Frame, Aufnahme –, nutzt man Bild-zu-Video, weil das Modell von den eigenen visuellen Inhalten ausgeht und nicht aus dem Nichts kreiert. Wenn man nur eine Idee und keinerlei Referenzmaterial hat, nutzt man Text-zu-Video.

Trennt diese beiden Modell-IDs von Anfang an in der Codebasis. Sie als ein einziges „Video“-Konzept zu behandeln und später ein if has_image-Flag hinzuzufügen, ist genau der Grund, warum Integrationen am Ende unübersichtliche Payloads und schwer nachvollziehbare Bugs bekommen.

Was gleich bleibt

Beide Endpunkte teilen dasselbe Authentifizierungsschema, dieselbe Basis-URL, dieselben allgemeinen Request-/Response-Konventionen und dasselbe Abrechnungsmodell (Videos werden nach generiertem Output abgerechnet, nicht nach Anfrageanzahl). Genau diese gemeinsamen Teile machen einen einzigen Request-Builder machbar – dazu später mehr.

Was sich unterscheidet

Nur die Payload-Struktur und die Eingabevalidierung unterscheiden sich. Die Unterschiede sind klein genug, um beide Endpunkte zu unterstützen, ohne den gesamten Integrationscode zu duplizieren.

Voraussetzungen und API-Setup

Vor dem ersten Aufruf braucht man drei Dinge.

1. API-Schlüssel

Erstelle den Schlüssel im HiAPI-Konto und speichere ihn als Umgebungsvariable statt ihn fest zu kodieren:

export HIAPI_API_KEY="your_key_here"

Jede Anfrage wird über einen Bearer-Token im Authorization-Header authentifiziert. Es gibt keinen separaten Signaturschritt und keinen Nonce pro Anfrage.

2. Basis-URL und Modell-Namenskonvention

Alle Aufrufe gehen an dieselbe HiAPI-Basis-URL, das Modell wird über das Feld model im Request-Body gewählt. Modell-IDs folgen dem Muster family/variant, daher schreibt man die Videomodelle als gemini-omni-flash/text-to-video und gemini-omni-flash/image-to-video. Man ändert nur einen String, um den Endpunkt zu wechseln, nicht den Host.

3. Werkzeuge zum Senden der Anfragen

curl reicht aus, um die Konnektivität zu prüfen, Python (mit requests) reicht für eine echte Integration. Beide benötigen kein herstellerspezifisches SDK – die API ist einfach JSON über HTTPS.

Konnektivitätscheck

Bevor man ein Video generiert, ruft man einen leichtgewichtigen Endpunkt auf (z. B. zum Auflisten verfügbarer Modelle), um zu bestätigen, dass der Schlüssel funktioniert und der Netzwerkpfad stimmt. Wenn dieser Schritt bereits scheitert, debuggt man Anmeldedaten oder Konnektivität, nicht die Videogenerierung – herauszufinden, welches von beiden, spart enorm viel Zeit.

Schnelle Checkliste:

  • Der Schlüssel ist in der Shell exportiert, in der die Anfrage ausgeführt wird.
  • Die Basis-URL ist dokumentiert und wird überall konsistent verwendet (kein Drift bei abschließenden Schrägstrichen zwischen Skripten).
  • Bei jedem POST sind Content-Type: application/json gesetzt.
  • Es gibt eine Möglichkeit, die rohe JSON-Antwort ohne Abschneiden zu sehen.

Eine Text-zu-Video-Anfrage senden

Beginne mit der kleinstmöglichen Anfrage, der eine Erfolgschance eingeräumt wird. Nicht sofort alle optionalen Parameter ausfüllen – schlägt die minimale Anfrage fehl, weiß man, dass das Problem strukturell ist; gelingt sie, ist jeder danach hinzugefügte Parameter eine separat zuordenbare Änderung.

Minimale Struktur

Eine Text-zu-Video-Anfrage sendet Modell-ID und Prompt:

{
  "model": "gemini-omni-flash/text-to-video",
  "prompt": "Eine langsam vorwärtsfahrende Kamerafahrt durch eine regennasse Neonstraße bei Nacht, Reflexionen auf nassem Asphalt, filmisch"
}

Das ist die vollständige Payload. Sende sie, bestätige, dass ein erfolgreiches Antwortobjekt zurückkommt, und erst dann reichere den Inhalt an.

Die Anfrage schrittweise erweitern

Nachdem der minimale Aufruf funktioniert, füge jeweils einen Parameter hinzu und validiere nach jeder Ergänzung erneut. Typische Erweiterungen auf dem Textpfad:

  • Prompt-Details – Motiv, Bewegung, Kamerverhalten, Beleuchtung und Atmosphäre. Vage Prompts erzeugen vage Bewegung; beschreibe, was sich bewegt und wie sich die Kamera bewegt.
  • Dauer / Ausgabelänge – Videos werden nach generiertem Output abgerechnet, die Länge wirkt sich also direkt auf die Kosten aus. Lege sie explizit fest, statt sich auf Standardwerte zu verlassen, die man noch nicht überprüft hat.
  • Seitenverhältnis oder Auflösung (falls vom Modell unterstützt), um zum Downstream-Player oder Social-Media-Format zu passen.

Worauf es beim Prompt-Schreiben wirklich ankommt

Die Qualität von Text-zu-Video wird hauptsächlich durch die Konkretheit des Prompts bestimmt. Drei gute Gewohnheiten:

  1. Bewegung beschreiben, nicht nur Inhalt. „Ein Papierboot treibt einen Abfluss hinunter“ gibt dem Modell etwas Animierbares; „ein Papierboot“ nicht.
  2. Die Kamera angeben. Statisch, schwenkend, vorwärtsfahrend, handgehalten – Kamerasprache beseitigt eine Menge Mehrdeutigkeit.
  3. Auf eine Szene beschränken. Mehrere Einstellungen in einem einzelnen Kurzfilm zu beschreiben, führt oft zu einem verschwommenen Ergebnis.

Wenn die Text-zu-Video-Ergebnisse schlecht sind, ändere zuerst den Prompt und dann erst technische Parameter.

Eine Bild-zu-Video-Anfrage senden

Der Bildpfad ist strukturell identisch mit dem Textpfad, nur mit einer Ergänzung: dem Quellbild. Die gelernte „Minimal zuerst“-Testmethode gilt auch hier.

Minimale Struktur

{
  "model": "gemini-omni-flash/image-to-video",
  "prompt": "Sanfte handgehaltene Drift, das Motiv dreht sich leicht zur Kamera, weiches Fensterlicht",
  "image": "https://your-cdn.example.com/source-frame.jpg"
}

Der Prompt beschreibt hier Bewegung und Kamerverhalten relativ zum Bild, nicht den Szeneninhalt – das Bild liefert den Inhalt bereits. Das ist der häufigste konzeptionelle Fehler: Man schreibt eine vollständige Szenenbeschreibung und wundert sich, warum die Ausgabe den Quellframe ignoriert.

So liefert man das Quellbild

Das Bild wird als Referenz übergeben, der Dienst muss es abrufen können. Zwei praktische Konsequenzen:

  • Die Ressource muss öffentlich für den Dienst erreichbar sein, nicht hinter deinem localhost, VPN oder einem authentifizierten Bucket. Kurzzeitig ablaufende signierte URLs sind in Ordnung, solange sie bei Ausführung der Anfrage noch gültig sind.
  • Format und Größe müssen unterstützt werden. Bleibe bei gängigen Web-Formaten und vernünftigen Abmessungen. Ein 40-MB-TIFF wartet nur auf ein Debugging.

Liegt das Bild in privatem Speicher, generiere zum Zeitpunkt der Anfrage eine kurzlebige signierte URL, statt zu versuchen, den Bucket öffentlich zu machen.

Die praktischen Unterschiede zum Textpfad

  • Die Rolle des Prompts wechselt von Szenenbeschreibung zu Bewegungsbeschreibung.
  • Die Validierung hat einen zusätzlichen Ressourcen-Abrufschritt, wodurch eine ganze neue Klasse von Fehlern entsteht (siehe Debugging-Kapitel).
  • Die Ausgabekomposition ist durch das Seitenverhältnis des Quellbilds eingeschränkt, was die Planung des Downstream-Layouts beeinflusst.

Teste die Bild-URL zuerst im Browser. Wenn sie bei dir nicht sauber lädt, lädt sie auch beim Dienst nicht.

Die API mit curl und Python aufrufen

Bringe dieselbe Anfrage an beiden Stellen zum Laufen: im Terminal (für schnelle Iterationen und rohe Sichtbarkeit) und in deiner Codebasis (für den tatsächlichen Einsatz).

curl

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash/text-to-video",
    "prompt": "Eine langsam vorwärtsfahrende Kamerafahrt durch eine regennasse Neonstraße bei Nacht, filmisch"
  }'

Ersetze den model-String durch gemini-omni-flash/image-to-video und ergänze das Feld image, um den anderen Endpunkt zu treffen – sonst ändert sich nichts.

Verwende -sS, damit Fehler nicht stillschweigend verschluckt werden; leite die Antwort beim Prüfen durch einen JSON-Formatierer, damit verschachtelte Felder lesbar sind.

Python

import os
import requests

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gemini-omni-flash/text-to-video",
    "prompt": "Eine langsam vorwärtsfahrende Kamerafahrt durch eine regennasse Neonstraße bei Nacht, filmisch",
}

resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())

Zwei Details, die man getrost übernehmen sollte: den Schlüssel aus einer Umgebungsvariablen lesen und ein ausreichend großzügiges Timeout setzen. Videogenerierung ist keine sofortige Anfrage – ein Standard-Timeout von 10 Sekunden erzeugt falsche Fehler, die wie ein API-Fehler aussehen, obwohl der Client einfach zu früh aufgibt.

Für Bild-zu-Video fügt man eine Zeile hinzu:

payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"

Bei einem Nicht-2xx-Statuscode immer den rohen Response-Body ausgeben oder protokollieren, bevor man eine Exception wirft. Der Fehlertext benennt meist direkt das problematische Feld.

Den Integrationscode organisieren

Nachdem beide Pfade funktionieren, ist man leicht versucht, zwei nahezu identische Funktionen in der Codebasis zu lassen. Eine etwas bessere Struktur kostet kaum Aufwand und zahlt sich in dem Moment aus, in dem man ein zweites Videomodell hinzufügt.

Zwei gemeinsame Komponenten

Ein Request-Builder. Eine Funktion, die absichtsbezogene Parameter entgegennimmt und ein Payload-Dictionary zurückgibt:

def build_video_payload(prompt, image_url=None, duration=None):
    if image_url:
        payload = {
            "model": "gemini-omni-flash/image-to-video",
            "prompt": prompt,
            "image": image_url,
        }
    else:
        payload = {
            "model": "gemini-omni-flash/text-to-video",
            "prompt": prompt,
        }
    if duration:
        payload["duration"] = duration
    return payload

Die Endpunktauswahl wird zum Ergebnis der Frage „Habe ich ein Bild?“, was der tatsächlichen Produktentscheidung entspricht. Der Aufrufer kommt nie direkt mit Modell-IDs in Berührung.

Ein Response-Handler. Eine Funktion, die Transportfehler, Payload-Fehler und Fehler auf Modellebene getrennt behandelt und ein normalisiertes Ergebnisobjekt zurückgibt (Status, Video-Referenz, roher Response-Body für Logs). Alle Aufrufer gehen durch sie hindurch, sodass die Fehlersemantik beider Endpunkte konsistent bleibt.

Warum sich das lohnt

  • Modell-IDs ändern sich an nur einer Stelle. Beim Wechsel auf ein anderes Videomodell bearbeitet man nur den Builder, nicht fünfzehn Aufrufstellen.
  • Einheitliche Fehlerbehandlung. Fehlschläge beim Bildabruf und bei der Prompt-Validierung erscheinen in deiner UI auf dieselbe Weise.
  • Testbar ohne Netzwerk. Der Builder ist eine reine Funktion; die Payload-Struktur lässt sich günstig per Unit-Test prüfen.
  • Abrechnungssichtbarkeit. Da Videos nach generiertem Output abgerechnet werden, ist ein einziger Handler der natürliche Ort, um Dauer und Ausgabegröße zur Kostenverfolgung zu protokollieren.

Halte den Builder schlank. Die Geschäftslogik darüber, was generiert wird, gehört zum Aufrufer; der Builder muss nur wissen, wie er diese Absicht in der Form der API ausdrückt.

Häufige Anfragefehler debuggen

Nahezu alle frühen Fehlschläge fallen in eine von drei Kategorien. Bestimme zuerst die Kategorie, dann behebe sie.

Kategorie 1: Request-Struktur

Symptom: sofortiges 4xx, Fehlermeldung nennt fehlende oder unbekannte Felder oder beschwert sich über fehlerhaftes JSON.

Der Reihe nach prüfen:

  1. Ist das JSON gültig? Füge den Request-Body in einen Linter ein. Ein beim manuellen Bearbeiten zurückgebliebenes abschließendes Komma ist ein Klassiker.
  2. Ist die Modell-ID exakt identisch? gemini-omni-flash/text-to-video und gemini-omni-flash-text-to-video sind nicht derselbe String. Ein Tippfehler hier erzeugt einen „Modell nicht gefunden“-Fehler, der sich wie ein Authentifizierungsproblem liest.
  3. Sind die Header vollständig? Authorization und Content-Type: application/json sind beide gesetzt.
  4. Passen Modell und Endpunkt zusammen? Das Feld image an den Text-Endpunkt zu senden, liefert nicht das gewünschte Ergebnis – das Feld wird entweder abgelehnt oder ignoriert, in beiden Fällen erhält man ein falsches Ergebnis.

Kategorie 2: Eingabe-Ressource (nur Bildpfad)

Symptom: Anfrage wird angenommen, scheitert aber während der Verarbeitung, oder der Fehler nennt das Abrufen oder Dekodieren des Bilds.

Prüfen:

  1. Öffne die Bild-URL in einem privaten Browserfenster ohne Cookies. Lädt sie dort nicht, lädt der Dienst sie auch nicht.
  2. Stelle sicher, dass die URL keine localhost-Adresse, kein privater Netzwerk-Host und kein abgelaufener signierter Link ist.
  3. Stelle sicher, dass das Format ein gängiges Web-Format und die Dateigröße vernünftig ist.
  4. Stelle sicher, dass die Antwort tatsächlich ein Bild ist – ein CDN, das Status 200 zurückgibt, aber dessen Inhalt eine HTML-Fehlerseite ist, ist eine überraschend häufige Falle.

Kategorie 3: Der Modellaufruf selbst

Symptom: Anfrage ist gültig, Ressource erreichbar, aber die Generierung scheitert oder wird abgelehnt – meist im Zusammenhang mit Inhaltsrichtlinien oder Kapazität.

Prüfen:

  1. Auf einen minimalen Prompt reduzieren und erneut versuchen. Gelingt das, ist der Prompt die Variable.
  2. Prüfen, ob das Client-Timeout lang genug ist – in Logs sieht ein Client-Timeout genauso aus wie ein Serverfehler, es sei denn, man prüft, ob überhaupt eine Antwort eingegangen ist.
  3. Vollständige Request-/Response-Logs aktivieren (Schlüssel redigiert), sodass man die drei Problemkategorien auf einen Blick unterscheiden kann.

Die effektive Debugging-Reihenfolge

Minimale Payload → validieren → Bild hinzufügen → validieren → optionale Parameter einzeln hinzufügen → validieren. Geht etwas schief, ist die letzte Änderung der Übeltäter. Solange man nur eine Variable auf einmal debuggt, verschwindet der Großteil des Integrationsschmerzes.

Beginne mit dem minimal funktionierenden Aufruf pro Endpunkt, umschließe ihn mit gemeinsamem Builder und Handler und erweitere dann schrittweise – dieser Weg hält sowohl Text-zu-Video als auch Bild-zu-Video vorhersagbar, während die Integration wächst.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen