Tutorial
So rufen Sie gemini-omni-1.1-flash über die HiAPI-API auf: curl- und Python-Leitfaden
Auf dieser Seite
Was Sie vor der ersten Anfrage vorbereiten müssen
Bevor Sie eine einzige Codezeile schreiben, bestätigen Sie vier Dinge. Jedes davon erspart Ihnen eine Debug-Runde.
Ein API-Schlüssel
Jede Anfrage an HiAPI muss mit einem API-Schlüssel authentifiziert werden. Erzeugen Sie einen in Ihrer Kontokonsole und stellen Sie sicher, dass er nicht in die Versionsverwaltung gelangt. Die folgenden Beispiele lesen ihn aus einer Umgebungsvariable, sodass der Schlüssel weder in der Shell-Historie noch in committeten Dateien auftaucht:
export HIAPI_API_KEY="your_key_here"
Basis-URL und Endpunktpfad
Die Basis-URL ist für alle HiAPI-Modelle gleich; nur der Modellbezeichner ändert sich. Den Endpunktpfad und die Anfragemethode entnehmen Sie der API-Referenzdokumentation und nicht einem Blogbeitrag, denn Pfade sind versioniert und können sich ändern. Legen Sie die Basis-URL als Konstante im Client ab, sodass künftige Änderungen nur eine Zeile erfordern.
Der Modellbezeichner
gemini-omni-1.1-flash wird als String im Anfrage-Payload übergeben. Kopieren Sie ihn exakt – Bindestriche und Versionssuffix zählen. Bei einem Tippfehler ist der Fehler meist ein Validierungsfehler und kein Routing-Fehler, was verwirrend ist; siehe den Debugging-Abschnitt weiter unten.
Die Modellseite als Lesezeichen speichern
Die Modellseite von gemini-omni-1.1-flash ist die maßgebliche Quelle dafür, welche Parameter es gibt, welche Werte akzeptiert werden und wie die Antwort strukturiert ist. Behandeln Sie sie als Referenz, die Sie vor jeder Änderung prüfen, und nicht als etwas, das man einmal liest und dann abhakt.
Sobald diese vier Punkte bereit sind, können Sie den Aufruf starten.
Eine minimale Anfrage mit curl senden
Beginnen Sie mit einer möglichst kleinen Anfrage. Ihr Zweck ist nicht, gute Ergebnisse zu erzeugen – sondern zu beweisen, dass Schlüssel, Endpunkt und Payload-Struktur zusammenpassen. Sobald das funktioniert, ist jede weitere Änderung inkrementell.
curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Langsame Kamerafahrt auf eine Keramiktasse auf einem Holztisch zu, weiches Morgenlicht"
}
}'
Die einzelnen Teile bedeuten Folgendes:
- Methode und URL – Der Aufruf ist ein
POSTan den Endpunktpfad aus der API-Referenzdokumentation, vorangestellt Ihre Basis-URL. Authorization-Header – Trägt das Bearer-Token. Eine fehlende oder leere Variable ist hier die häufigste Ursache für 401.Content-Type-Header – Mussapplication/jsonsein. Ohne ihn parst der Server den Request-Body möglicherweise gar nicht.model– Der exakte Modellbezeichner-String.input– Ein Objekt mit den Generierungsparametern. Der Prompt steht hier; Auflösung und Dauer werden ebenfalls hier ergänzt, siehe unten.
Wenn der Aufruf eine Aufgabenkennung oder eine Accepted-Status-Antwort statt der endgültigen Ausgabe zurückgibt, ist das normal – die Generierung ist asynchron. Speichern Sie die Kennung; der Polling-Schritt benötigt sie.
Denselben Aufruf nach Python portieren
Die Python-Version sollte exakt denselben JSON-Request-Body senden. Den Payload konsistent zu halten macht diese Portierung glaubwürdig: Wenn curl erfolgreich ist und Python nicht, liegt das Problem in Ihrem Python-Code und nicht in Ihrem Verständnis der API.
import json
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Langsame Kamerafahrt auf eine Keramiktasse auf einem Holztisch zu, weiches Morgenlicht"
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())
Einige Gewohnheiten lohnen sich, sofort anzunehmen:
- URLs aus Konstanten aufbauen, statt String-Konkatenation über den Code zu verteilen.
- Explizite Timeouts setzen. Ohne sie kann eine hängende Anfrage einen Worker unbegrenzt blockieren.
raise_for_status()aufrufen, damit Fehlerantworten als Exception sichtbar werden, statt stillschweigend als Erfolgs-Response-Body geparst zu werden.- Mit
json.dumpsserialisieren, statt sich auf Formular-Encoding zu verlassen, das das verschachtelteinput-Objekt nicht korrekt erzeugen kann.
Sobald das läuft, haben Sie eine wiederverwendbare Anfragestruktur. Die nächsten beiden Abschnitte fügen die Parameter hinzu, die die Ausgabe wirklich steuern.
Auflösung und Dauer in der Anfrage konfigurieren
Auflösung und Dauer sind gewöhnliche Felder im input-Objekt, neben dem Prompt. Konzeptionell sieht der Payload so aus:
{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "...",
"resolution": "<supported-value>",
"duration": "<supported-value>"
}
}
Entscheidende Regel: Hardcodieren Sie diese Werte nicht aus dem Gedächtnis oder aus einem vor Monaten gelesenen Tutorial. Unterstützte Werte ändern sich mit Modell-Updates, und das Übergeben eines nicht unterstützten Werts erzeugt einen Validierungsfehler, der wie ein Payload-Fehler aussieht. Bevor Sie sie setzen, prüfen Sie stets die aktuell akzeptierten Werte auf der Modellseite.
Ein praktisches Muster
Legen Sie die Werte in die Konfiguration statt in den Code:
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": prompt,
"resolution": settings.resolution,
"duration": settings.duration,
},
}
Das bringt drei Vorteile. Sie können die Ausgabequalität anpassen, ohne die Logik zu ändern. Sie können während der Entwicklung günstige Tests mit niedriger Auflösung laufen lassen und die Auflösung nur beim Final-Rendering erhöhen. Wenn die Plattform neue unterstützte Werte hinzufügt, ändern Sie nur ein Konfigurationsfeld, statt die ganze Codebasis zu durchsuchen.
Zwei subtilere Fallstricke lohnen eine Erwähnung. Erstens korrelieren Auflösung und Dauer meist mit den Kosten – die Abrechnung richtet sich in der Regel nach dem Output, längere und höher aufgelöste Clips sind also nicht kostenlos. Zweitens: Wenn ein Feld optional ist, lassen Sie es weg, statt einen leeren String oder null zu senden; manche Validatoren lehnen explizites null ab, auch wenn das Feld selbst optional ist.
Asynchrone Generierung handhaben: erst einreichen, dann abfragen
Generierung braucht Zeit, daher folgt die API dem Muster „erst einreichen, dann abfragen“. Ihr Client muss dies als zwei getrennte Vorgänge mit unterschiedlicher Retry-Semantik behandeln.
Schritt 1: Einreichen
Der Einreichungsaufruf ist die Anfrage, die Sie bereits aufgebaut haben. Er gibt die Kennung der Aufgabe zurück – je nach Endpunkt kann das eine Task-ID, eine task ID oder ein ähnliches Feld sein. Parsen Sie sie defensiv:
created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier in response: {created}")
Schritt 2: Abfragen
Fragen Sie dann mit dieser Kennung den Status-Endpunkt ab, bis die Aufgabe einen Endzustand erreicht. Eine robuste Schleife hat vier Eigenschaften: eine maximale Wartezeit, Backoff, eine Prüfung auf Endzustände und eine Prüfung auf Fehler.
import time
def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
deadline = time.time() + timeout
delay = initial_delay
while time.time() < deadline:
status = fetch_status(job_id) # GET on the status endpoint
state = status.get("status")
if state in ("succeeded", "completed"):
return status
if state in ("failed", "error", "cancelled"):
raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
time.sleep(delay)
delay = min(delay * 2, max_delay)
raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
Warum diese Details wichtig sind
- Exponentielles Backoff verhindert, dass der Status-Endpunkt bei einer Aufgabe, deren Rendering eine Minute dauert und die noch in der Warteschlange steht, unablässig getroffen wird.
- Eine harte Frist verhindert, dass eine hängende Aufgabe einen Worker für immer blockiert. Protokollieren Sie bei Timeout die Task-ID, damit Sie manuell nachprüfen können.
- Explizite Endzustände bedeuten, dass Sie niemals in einer unerwarteten Status-Endlosschleife drehen. Behandeln Sie unbekannte Zustände als „weiter warten“, aber protokollieren Sie sie einmal.
- Getrennte Retry-Richtlinien: Den Einreichungsaufruf erneut zu versuchen ist riskanter als den Statusaufruf erneut zu versuchen, weil er doppelte Aufgaben erzeugen kann. Polling können Sie bedenkenlos erneut versuchen; den Einreichungsaufruf nur bei eindeutigen Transportfehlern.
Häufige Fehlermuster beheben
Die meisten Fehler fallen in wenige Kategorien. Untersuchen Sie sie in dieser Reihenfolge, denn spätere Symptome werden oft durch frühere Probleme verursacht.
Authentifizierungsfehler
Symptom: 401 oder 403.
Zuerst prüfen: Existiert der Schlüssel tatsächlich in der Umgebung, in der der Prozess läuft? Das Ausgeben von len(API_KEY) fängt den klassischen Fall ab, in dem die Variable nicht gesetzt ist und das Bearer-Token leer bleibt. Prüfen Sie dann, dass das Header-Format Bearer <key> ist, mit genau einem Leerzeichen, und dass der Schlüssel nicht widerrufen oder auf ein anderes Projekt beschränkt ist.
Fehlerhafte Payload-Struktur
Symptom: 400 mit Beschwerde über den Request-Body oder fehlende Felder.
Zuerst prüfen: Vergleichen Sie Ihren Request-Body mit der funktionierenden curl-Anfrage. Häufige Ursachen sind ein fehlender Content-Type: application/json-Header, das Senden von Formular-encodierten Daten statt JSON, ein input-Objekt, das flach ist, während die API verschachtelt erwartet (oder umgekehrt), und unbeabsichtigte Typkonvertierungen – eine numerische Dauer, die als String mit Anführungszeichen gesendet wird, kann die Validierung fehlschlagen lassen.
Nicht unterstützte Parameterwerte
Symptom: 400 oder 422 mit Nennung eines bestimmten Feldes wie resolution oder duration.
Zuerst prüfen: die Modellseite, auf der die aktuell unterstützten Werte aufgeführt sind. Das ist fast immer ein veralteter hardcodierter Wert und kein Defekt im Code. Wenn ein zuvor funktionierender Wert jetzt fehlschlägt, gehen Sie zuerst davon aus, dass das Modell aktualisiert wurde, und lesen Sie die Dokumentation neu, bevor Sie einen Dienstdefekt annehmen.
Tippfehler beim Modellbezeichner
Symptom: Ein Validierungsfehler oder Nicht-gefunden-Fehler, ohne dass Ihr Prompt erwähnt wird.
Zuerst prüfen: Geben Sie den model-String aus und vergleichen Sie ihn Zeichen für Zeichen mit der Dokumentation. Ein zusätzliches Leerzeichen am Ende oder eine verdrehte Versionsnummer sind leicht zu übersehen.
Timeouts und vorübergehende Fehler
Symptom: Verbindungs-Timeouts, 429- oder 5xx-Antworten. Zuerst prüfen: Haben Sie Timeouts gesetzt? Fügen Sie Timeouts hinzu und dann begrenzte Retries mit Backoff nur für 429 und 5xx – wiederholen Sie keine 4xx-Fehler außer 429, denn die Anfrage wird jedes Mal auf dieselbe Weise fehlschlagen. Denken Sie bei langen Aufgaben daran, dass das Endergebnis per Polling abgeholt wird; ein Timeout des Einreichungsaufrufs bedeutet nicht, dass die Generierung fehlgeschlagen ist.
Technisch gültig, aber falsches Ergebnis
Die Anfrage ist erfolgreich, aber die Ausgabe entspricht nicht den Erwartungen. Das ist ein Prompt-Problem, kein API-Problem. Machen Sie den Prompt konkret in Bezug auf Motiv, Kamerabewegung, Beleuchtung und Tempo, und ändern Sie immer nur eine Variable auf einmal, damit Sie Unterschiede zuordnen können.
Als wiederverwendbare Client-Funktion kapseln
Das Ziel der Kapselung ist einfach: Ihre Geschäftslogik sollte keine Modellbezeichner, Parameternamen oder Polling-Schleifen enthalten. Alle modellbezogenen Details sind an einer Stelle gebündelt.
def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
payload = {
"model": "gemini-omni-1.1-flash",
"input": {"prompt": prompt},
}
if resolution is not None:
payload["input"]["resolution"] = resolution
if duration is not None:
payload["input"]["duration"] = duration
created = post_json(ENDPOINT, payload)
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier: {created}")
return wait_for_job(job_id, timeout=timeout)
Was Ihnen das bringt
- Ein Modellwechsel erfordert eine Zeile. Wenn ein neueres Modell kommt, ändern Sie die Konstante und die Standardparameter; die Aufrufstellen bleiben unberührt.
- Optionale Parameter werden korrekt behandelt. Weggelassene Werte werden nicht gesendet, wodurch das zuvor beschriebene Problem der null-Ablehnung vermieden wird.
- Das Polling ist für den Aufrufer unsichtbar. Der Aufrufer erhält entweder ein Ergebnis oder eine Exception, niemals eine Task-ID, die er selbst verwalten muss.
- Tests werden einfach. Sie können
post_jsonundwait_for_jobseparat stubben und so den Payload-Aufbau und die Polling-Logik isoliert testen.
Schichtenweise Organisation
Halten Sie die Struktur flach und explizit: Transportschicht (HTTP, Header, Timeouts, Retries), Modellschicht (Payload-Aufbau für gemini-omni-1.1-flash) und Aufgabenschicht (Einreichen und Abfragen). Eine einzelne generate_video-Funktion kombiniert sie, und jede Schicht ist klein genug, dass sie sich im Fehlerfall leicht analysieren lässt.
Bestätigen Sie die Verbindungskonfiguration zuerst mit curl, wechseln Sie dann für die eigentliche Arbeit zu Python, lesen Sie bei Parameteränderungen stets die Modellseite, und platzieren Sie die Polling-Schleife hinter einer Schnittstelle, damit sie niemals in den Anwendungscode gelangt.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
kling-image-4.0 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzgebiete und Integrationspunkte
-
Tutorial
So verwenden Sie qwen-image-2.0-pro über die HiAPI API: curl, Python und eine funktionierende Anfrage
Eine praktische Integrationsübung für Entwickler: erster erfolgreicher Aufruf, Aufbau der Anfrage und Fehlersuche
-
Tutorial
So rufen Sie die veo-3.1 Text-zu-Video-API auf: curl- und Python-Beispiele
Ein praxisorientierter Integrationsleitfaden für Entwickler