So verwenden Sie gemini-omni-1.2-flash über die HiAPI API: curl und Python

Wie eine gemini-omni-1.2-flash-Anfrage aussieht

Bevor Sie die erste Codezeile schreiben, ist es hilfreich zu verstehen, woraus ein gemini-omni-1.2-flash-Aufruf bei HiAPI tatsächlich besteht. Jede Anfrage, die Sie senden, ist ein JSON-Objekt, das an einen einzigen Endpunkt übermittelt und mit Ihrem HiAPI-API-Schlüssel authentifiziert wird. Diese Struktur ist über alle Modelle hinweg konsistent, das heißt, sobald Sie sie für dieses Modell beherrschen, können Sie dasselbe Muster auch anderswo wiederverwenden.

Auf hoher Ebene enthält eine Anfrage vier Arten von Informationen:

• Modellbezeichner – der String gemini-omni-1.2-flash, der HiAPI mitteilt, an welches Modell Ihre Aufgabe weitergeleitet werden soll.
• Eingabe – der Inhalt, den das Modell verarbeiten soll. Je nach Modalität, die Sie ansprechen, erscheint er als Prompt oder als strukturiertes Eingabefeld.
• Generierungsparameter – Optionen, die die Ausgabe formen, etwa Dauer und Auflösung. Das sind die Stellschrauben, die Sie später in diesem Leitfaden justieren werden.
• Anfrage-Metadaten – alle Informationen, die die Plattform zur Identifikation und Verfolgung Ihrer Aufgabe benötigt, etwa eine clientseitige Referenz zur Zuordnung.

Antwortstruktur

Die Antwort ist ebenso vorhersehbar. Synchrone Aufrufe geben das Ergebnis direkt in einem Ergebnisfeld zurück. Asynchrone Aufrufe geben stattdessen ein Aufgaben-Handle zurück – einen Bezeichner, mit dem Sie den Status abfragen und schließlich die Ausgabe abrufen können. Früh zu klären, mit welcher der beiden Varianten Sie es zu tun haben, erspart Ihnen später viel Debugging-Zeit.

Warum die Struktur wichtig ist

Die meisten Erstintegrationen scheitern an der Anfragestruktur: fehlende Felder, Parameter mit falschem Typ oder die Annahme, ein Aufruf sei synchron, obwohl er es nicht ist. Wenn Sie diese Anatomie verinnerlichen, bevor Sie Code schreiben, sind die curl- und Python-Beispiele weiter unten nur noch eine schlichte Übersetzung statt eines geheimnisvollen Zauberspruchs.

Eine nützliche Angewohnheit: Bewahren Sie den exakten JSON-Body, den Sie senden, in einer Variable oder Datei auf. Wenn etwas schiefgeht, möchten Sie sehen, was tatsächlich gesendet wurde, statt es aus dem Gedächtnis zu rekonstruieren.

Authentifizierung in einer Zeile

Jede Anfrage überträgt Ihren API-Schlüssel im Authorization-Header. Behandeln Sie den Schlüssel als Geheimnis: laden Sie ihn aus einer Umgebungsvariable statt ihn fest einzucodieren, und committen Sie ihn niemals in die Versionsverwaltung. Diese eine Disziplin vermeidet den häufigsten Sicherheitsfehler bei API-Integrationen.

Senden Sie Ihre erste funktionierende Anfrage mit curl

Der schnellste Weg, um zu bestätigen, dass Schlüssel, Endpunkt und Anfragestruktur korrekt sind, ist ein curl-Aufruf. Er entfernt jede Abstraktionsebene zwischen Ihnen und der API, sodass Sie bei Erfolg wissen, dass ein etwaiges Problem in Ihrem Code liegt und nicht in Ihrer Umgebungskonfiguration.

Schritt 1: Speichern Sie Ihren Schlüssel

Legen Sie den HiAPI-API-Schlüssel in einer Umgebungsvariable ab, damit er nicht in Ihrer Shell-Historie oder in gemeinsam genutzten Skripten auftaucht:

export HIAPI_API_KEY="your_key_here"

Schritt 2: Erstellen Sie den Anfrage-Body

Schreiben Sie den JSON-Body in eine Datei. Das hält den curl-Befehl lesbar und gibt Ihnen ein wiederverwendbares Artefakt:

cat > request.json <<'EOF'
{
  "model": "gemini-omni-1.2-flash",
  "input": {
    "prompt": "Beschreiben Sie, was das Modell generieren soll."
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}
EOF

Die konkreten Parameterwerte hängen von Ihrem Anwendungsfall ab; wichtig ist hier die Struktur. Halten Sie duration und resolution beim ersten Aufruf moderat, damit Sie schnell und kostengünstig ein verwertbares Signal erhalten, dass die Pipeline funktioniert.

Schritt 3: Senden Sie die Anfrage

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Schritt 4: Lesen Sie die Antwort

Ist die Anfrage synchron, sehen Sie das generierte Ergebnis im Antwort-Body. Ist sie asynchron, erhalten Sie ein Aufgaben-Handle – eine Aufgaben-ID plus ein Statusfeld. Notieren Sie sich diese ID; Sie werden sie beim Polling benötigen.

Wenn Ihr Terminal das unterstützt, leiten Sie die Ausgabe durch einen JSON-Formatierer oder speichern Sie sie zur genauen Prüfung in eine Datei:

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json > response.json

Schritt 5: Bestätigen Sie, bevor Sie skalieren

Bevor dieser schlichte Aufruf erfolgreich ist und Sie die Ausgabe verstehen, sollten Sie nicht beginnen, Dauer, Auflösung oder Stapelverarbeitung zu justieren. Die erste erfolgreiche Anfrage ist Ihre Basislinie; alles Weitere sind inkrementelle Änderungen, die Sie damit vergleichen können.

Portieren Sie den Aufruf nach Python

Sobald curl funktioniert, ist die Portierung nach Python mechanisch. Das Ziel ist ein kleiner, lesbarer Client, der die Anfrage exakt spiegelt, sodass Sie bei einem fehlgeschlagenen Python-Aufruf feldweise mit der curl-Version diffen können.

Ein minimaler Client

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/generate"

payload = {
    "model": "gemini-omni-1.2-flash",
    "input": {
        "prompt": "Beschreiben Sie, was das Modell generieren soll."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720p"
    },
}

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

response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

Worauf Sie achten sollten

• json=payload serialisiert das Dictionary für Sie – deshalb stimmt der Body mit der curl-Datei überein und ist kein handzusammengesetzter String.
• raise_for_status() verwandelt Nicht-2xx-Antworten in Ausnahmen, sodass Fehlschläge sofort sichtbar werden, statt still einen Fehler-Body zurückzugeben, den Sie anschließend als Ergebnis zu parsen versuchen.
• timeout=60 verhindert, dass das Skript bei einer stockenden Verbindung endlos hängt. Wählen Sie einen Wert entsprechend der Zeit, die Ihre Generierung voraussichtlich braucht.

Behandeln Sie beide Antwortstrukturen

Da ein Aufruf entweder ein Ergebnis oder ein Aufgaben-Handle zurückgeben kann, verzweigen Sie anhand der Antwort, statt eine der beiden Strukturen anzunehmen:

if "job_id" in data:
    print("Asynchrone Aufgabe gestartet:", data["job_id"])
else:
    print("Ergebnis ist bereit")

Diese kleine Prüfung ist der Unterschied zwischen einem Client, der in beiden Modi funktioniert, und einem, der abstürzt, wenn die Plattform beim ersten Mal entscheidet, dass Ihre Aufgabe asynchron laufen muss.

Packen Sie es in eine Funktion

Kapseln Sie den Aufruf in eine Funktion, die Prompt, Dauer und Auflösung als Parameter entgegennimmt. So wird es beim Justieren ein Leichtes, denselben Code mit verschiedenen Parametern auszuführen, und die Anfragestruktur ist nur an einer Stelle definiert.

Asynchrone Aufgaben und Ergebnis-Polling

Manche gemini-omni-1.2-flash-Anfragen sind schnell genug fertig, um Ergebnisse inline zurückzugeben. Andere dauern länger, und HiAPI gibt stattdessen ein Aufgaben-Handle zurück. Ihre Integration muss beide Fälle behandeln, und der asynchrone Pfad ist genau der Ort, an dem die meisten fragilen Clients zusammenbrechen.

Asynchrone Antworten erkennen

Eine asynchrone Antwort enthält einen Aufgabenbezeichner und einen Status. Sie erhalten nicht die fertige Ausgabe, sondern ein Versprechen: Die Arbeit wurde angenommen und wird verarbeitet. Ihre Aufgabe ist es, später nachzusehen.

Richtig pollen

Der naive Ansatz – den Status-Endpunkt in einer engen while True-Schleife zu hämmern – hat zwei Nachteile: Er verschwendet Ihr Rate-Limit-Budget und erzeugt unnötige Last auf der Plattform, ohne dass Sie Ihr Ergebnis schneller erhalten.

Ein besseres Muster verwendet ein begrenztes Intervall-Backoff:

import time

def poll_job(job_id, base_delay=1.0, max_delay=10.0, max_wait=300.0):
    elapsed = 0.0
    delay = base_delay
    while elapsed < max_wait:
        status = get_job_status(job_id)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "job failed"))
        time.sleep(delay)
        elapsed += delay
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"job {job_id} did not finish in time")

Drei Regeln für das Polling

• Klein anfangen, langsam wachsen. Ein kurzes Anfangsintervall erfasst schnelle Aufgaben kostengünstig; die Verdopplung bis zur Obergrenze verhindert, dass langsame Aufgaben zu häufig geprüft werden.
• Immer eine maximale Wartezeit festlegen. Ohne sie hängt eine festgefahrene Aufgabe Ihren Prozess für immer auf. Eine Ausnahme werfende Zeitüberschreitung ist weit besser als ein stilles Hängen.
• Erfolg, Fehlschlag und Ausstehend unterscheiden. Nur zwei davon sollten die Schleife beenden, und nur eine sollte ein Ergebnis zurückgeben.

Bevorzugen Sie Webhooks, wo verfügbar

Bei hoher Last skaliert das Polling jeder Aufgabe schlecht. Wo HiAPI einen Abschluss-Callback anbietet, nutzen Sie ihn, um Ergebnisse zu empfangen, statt wiederholt nachzufragen. Für interaktive Tools und Skripte mit geringem Volumen ist Polling mit Backoff völlig ausreichend.

Behandeln Sie in jedem Fall das Aufgaben-Handle als dauerhafte Kennung der Arbeit. Speichern Sie es, protokollieren Sie es und verwenden Sie es später, um Ergebnisse abzugleichen.

Dauer und Auflösung wählen

Dauer und Auflösung sind die beiden Parameter, die Ihre Ausgabe am direktesten beeinflussen – und auch Ihre Abrechnung und Ihre Wartezeit. Keiner von beiden hat einen einzig richtigen Wert; die richtige Wahl hängt davon ab, was Sie bauen. Wichtig ist, dass Sie sie bewusst wählen und nicht einfach Zahlen aus Beispielen kopieren.

Dauer

Die Dauer steuert die Länge der generierten Ausgabe. Längere Dauer gibt Ihnen mehr Inhalt, erfordert aber mehr Rechenleistung für die Generierung, was sowohl die Latenz als auch die Abrechnung der Anfrage beeinflusst (die Abrechnung basiert auf der Ausgabedauer). Einige praktische Hinweise:

• Fangen Sie beim Testen kurz an. Eine kurze Dauer beweist, dass die Pipeline durchgängig funktioniert, ohne dass Sie bei jeder Iteration Zeit verschwenden.
• Passen Sie die Dauer dem Zweck an. Ein kurzer Clip für eine Vorschau oder ein Thumbnail braucht nicht die Länge eines vollständigen Lieferobjekts.
• Verlängern Sie nicht spekulativ. Generieren Sie die Länge, die Sie tatsächlich verwenden werden; nachträgliches Kürzen bringt Ihnen nichts.

Auflösung

Die Auflösung steuert die Wiedergabetreue der Ausgabe. Höhere Auflösung bedeutet mehr Detail und eine größere Payload, mit entsprechend erhöhter Verarbeitungszeit und höheren Kosten. Abzuwägende Kompromisse:

• Vorschau- und Entwurfsarbeit braucht keine hohe Auflösung – sie ist eine Korrektheitsprüfung, kein Endprodukt.
• Endgültige Lieferobjekte rechtfertigen möglicherweise eine höhere Einstellung, insbesondere wenn die Ausgabe in voller Größe präsentiert wird.
• Bandbreite und Speicher zählen ebenfalls: Hochauflösende Ausgaben sind sowohl bei der Übertragung als auch bei der Aufbewahrung schwerer.

Justieren Sie jeweils nur eine Variable

Wenn Sie Parameter anpassen, ändern Sie jeweils nur einen und vergleichen Sie ihn mit Ihrer Basislinien-curl-Anfrage. Wenn Sie Dauer und Auflösung gleichzeitig ändern, können Sie Veränderungen bei Qualität, Latenz oder Kosten keinem der beiden zuordnen. Führen Sie eine kleine Matrix, in der Sie getestete Einstellungen und das beobachtete Verhalten festhalten.

Denken Sie über Kosten als Formel, nicht als Zahl

Da die Preisgestaltung im Preispaneel der Website liegt, behandeln Sie die Kosten als Funktion: Die Gesamtkosten skalieren mit der Ausgabedauer und bei höherer Auflösung zusätzlich mit der endgültigen Ausgabegröße und dem Verarbeitungsvolumen. Ihre Aufgabe ist es, zu wissen, welche Parameter diese Funktion treiben, und dann vor dem Zusagen eines Produktionsvolumens die aktuellen Preise einzusehen. So bleiben Ihre Schätzungen auch dann korrekt, wenn sich die Preise ändern.

Häufige Fehler und wie man sie behebt

Die meisten Erstintegrationen scheitern lassen sich in wenige Kategorien einordnen. Gehen Sie sie in dieser Reihenfolge durch – jeder Schritt setzt voraus, dass der vorherige korrekt ist, sodass ein übersprungenes Prüfen Sie auf Oberflächensymptome hetzen lässt.

1. Anfragestruktur

Symptom: Validierungsfehler oder Meldungen über fehlende oder unerwartete Felder.

Behebung: Vergewissern Sie sich, dass der Body gültiges JSON ist (abschließende Kommas sind der klassische Übeltäter), dass das Feld model exakt gemini-omni-1.2-flash lautet, und vergleichen Sie Ihre Payload Zeile für Zeile mit dem funktionierenden curl-Beispiel. Wenn curl funktioniert und Python nicht, diffen Sie die beiden Anfrage-Bodys.

2. Parameter

Symptom: Ein Fehler nennt duration oder resolution, oder die Ausgabegröße ist unerwartet.

Behebung: Prüfen Sie die Typen (Zahl, wo eine Zahl erwartet wird, String, wo ein String erwartet wird) und prüfen Sie, ob die Werte im akzeptablen Bereich liegen. Wenn ein Parameter stillschweigend ignoriert wird, vergewissern Sie sich, dass er genau dort verschachtelt ist, wo die API ihn erwartet, und nicht auf der obersten Ebene.

3. Authentifizierung

Symptom: 401- oder 403-Antworten.

Behebung: Vergewissern Sie sich, dass der Schlüssel im Authorization-Header mit dem Präfix Bearer vorhanden ist, dass die Umgebungsvariable tatsächlich einen Wert enthält (ein leerer String sieht einem falschen Schlüssel sehr ähnlich) und dass Sie keine umgebenden Leerzeichen oder Anführungszeichen in den Schlüssel kopiert haben. Wenn Sie einen Schlüssel-Leak vermuten, generieren Sie ihn neu.

4. Aufgabenstatus

Symptom: Sie pollen, sehen aber nie einen Erfolg, oder Sie behandeln ausstehende Aufgaben als Fehlschlag.

Behebung: Vergewissern Sie sich, dass Sie die richtige Aufgaben-ID pollen, dass Ihre Schleife alle Zustände erkennt (pending, running, succeeded, failed) und dass die maximale Wartezeit für realistische Aufgaben lang genug ist. Protokollieren Sie jeden Statusübergang, damit Sie sehen können, wo es hängt.

5. Rate-Limits und vorübergehende Störungen

Symptom: 429-Antworten oder sporadische 5xx-Fehler.

Behebung: Wiederholen Sie mit Backoff und Jitter statt sofort. Wenn Sie viele Aufgaben pollen, senken Sie die Nebenläufigkeit. Vorübergehende Fehler sind normal; Clients mit intelligenten Wiederholungsversuchen überstehen sie.

Eine Debugging-Disziplin

Wenn etwas schiefgeht, ändern Sie jeweils nur eine Sache und führen Sie die kleinstmögliche Anfrage erneut aus. Bewahren Sie den rohen Antwort-Body auf – Fehlermeldungen nennen oft genau das Feld oder die Bedingung, und sie sorgfältig zu lesen spart mehr Zeit als jede Vermutung.

Checkliste für die Produktionsintegration

Ein Skript, das einmal auf Ihrem Laptop lief, ist noch keine Integration. Schließen Sie diese Lücken, bevor Sie live gehen.

Wiederholungsversuche mit Backoff

Umschließen Sie Netzwerkaufrufe mit einer Wiederholungsstrategie, die vorübergehende Störungen behandelt – Zeitüberschreitungen, Verbindungsabbrüche, 429- und 5xx-Antworten. Verwenden Sie exponentielles Backoff mit Jitter, begrenzen Sie die Anzahl der Versuche und wiederholen Sie niemals Anfragen, die an der Validierung scheitern; einen fehlerhaften Body erneut zu senden, scheitert nur langsamer erneut.

Setzen Sie überall Zeitüberschreitungen

Legen Sie für jeden HTTP-Aufruf eine explizite Zeitüberschreitung fest. Unterscheiden Sie Verbindungs- und Lese-Zeitüberschreitung, und stellen Sie sicher, dass die Zeitüberschreitung für Generierungsanfragen mindestens so lang ist wie eine echte Generierung – aber mit einer Obergrenze.

Machen Sie Aufgaben idempotent

Netzwerk-Jitter kann genau zwischen dem Moment, in dem der Server Ihre Anfrage angenommen hat, und dem Moment, in dem Sie die Antwort sehen, auftreten. Wenn Sie blind wiederholen, könnten Sie doppelte Aufgaben erzeugen. Hängen Sie an jede logische Anfrage eine clientseitig erzeugte Referenz, sodass Sie eine bestehende Aufgabe erkennen und wiederverwenden können, statt eine neue zu erzeugen, und speichern Sie das Aufgaben-Handle unter dieser Referenz in einem dauerhaften Speicher.

Logs, die Fragen beantworten

Protokollieren Sie für jede Anfrage den Modellnamen, die Parameterwerte (Dauer, Auflösung), das Aufgaben-Handle, Statusübergänge und die Latenz. Protokollieren Sie niemals API-Schlüssel oder vollständige Prompt-Inhalte, die sensible Daten enthalten könnten. Wenn um 3 Uhr nachts etwas schiefgeht, sind genau diese Logs das, was Ihnen erlaubt, das Geschehene präzise zu rekonstruieren.

Observability und Alarmierung

Verfolgen Sie Erfolgsraten sowohl von Anfragen als auch von Aufgaben-Lebenszyklen, die Fehlerverteilung nach Typ und die End-to-End-Latenz. Alarmieren Sie bei anhaltenden Fehlerraten, nicht bei einzelnen Fehlschlägen. Ein Dashboard, das Validierungs- von vorübergehenden Fehlern trennt, sagt Ihnen sofort, ob Sie einen Bug haben oder das Netz gerade schlecht ist.

Konfigurationshygiene

Legen Sie Endpunkt, Modellnamen und Standardparameter in der Konfiguration ab, statt sie über den Code verstreut zu haben. Laden Sie den API-Schlüssel aus einem Secret-Manager oder aus Umgebungsvariablen. Wenn Preise und Limits für Ihre Planung relevant sind, sehen Sie im Preispaneel nach, statt Zahlen fest einzucodieren, denn diese ändern sich.

Gehen Sie diese Checkliste durch, und Ihre gemini-omni-1.2-flash-Integration kann echten Verkehr bewältigen, nicht nur den ersten Test. Beginnen Sie mit einem funktionierenden curl-Aufruf, portieren Sie ihn nach Python und bauen Sie von dort aus weiter.