So verwendest du veo-3.1-lite/image-to-video über die hiapi API

Veo 3.1 Lite verwandelt ein einzelnes Referenzbild plus einen Text-Prompt in ein kurzes Video, und auf hiapi wird es über dieselbe asynchrone Task-API bereitgestellt, die alle Modelle der Plattform gemeinsam nutzen. Diese Anleitung geht einen real nutzbaren Anfrageablauf durch: Schlüssel besorgen, POST /v1/tasks aufrufen, das Ergebnis abholen und die Details beachten, die relevant werden, wenn du diesen Ablauf von einem einmaligen Skript in die Produktion überführst (Callbacks, Idempotenz, Fehlerbehandlung).

Was du baust und was du vorher vorbereitest

Du sendest eine Bild-URL und einen Prompt an das Modell veo-3.1-lite/image-to-video und bekommst eine extern gehostete .mp4-URL zurück. Alles läuft über den einheitlichen Task-Endpunkt von hiapi, sodass dieselbe Anfragestruktur für jedes Video- und Bildmodell der Plattform gilt – nur die model-ID und die input-Felder ändern sich.

Bevor du beginnst:

1. Erstelle ein hiapi-Konto und hole dir einen API-Schlüssel aus dem Dashboard. Der Schlüssel hat die Form sk-....
2. Halte eine öffentlich erreichbare Bild-URL bereit – die API ruft sie serverseitig ab, daher funktionieren localhost-Pfade oder private Buckets nicht.
3. Prüfe vor dem Ausführen echter (nicht testweiser) Anfragen die aktuellen Preise für veo-3.1-lite/image-to-video auf der Preisseite, da die Kosten von Dauer und Auflösung abhängen.

Es gibt keine kostenlose Stufe und keinen schlüssellosen Modus – jeder Aufruf benötigt Authorization: Bearer sk-<your-key>.

Minimal funktionierendes Beispiel

Die Task-API von hiapi besteht aus zwei Aufrufen: Task erstellen und dann entweder ihn abfragen oder einen Callback melden lassen, wann der Task fertig ist. Unten ist die Polling-Variante in Python, die nur requests und time verwendet:

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until it's done
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        video_url = task["output"][0]["url"]
        print("done:", video_url)
        break
    if status == "fail":
        raise RuntimeError(task.get("error"))
    time.sleep(5)

Wenn du nur das Übertragungsformat auf der Leitung sehen möchtest, ist hier dieselbe Sache als rohes curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/image-to-video",
    "input": {
      "prompt": "the camera slowly pushes in as steam rises from the cup",
      "image_url": "https://example.com/your-reference-image.jpg",
      "duration": 6,
      "aspect_ratio": "16:9"
    }
  }'

# then poll:
curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-your-key-here"

Ein paar Dinge am input-Schema solltest du besonders kennen, denn es ist strenger als ein generischer Endpunkt, der „einfach alles durchlässt“ – überflüssige Felder werden direkt abgelehnt statt stillschweigend ignoriert:

• prompt und image_url sind die einzigen beiden Pflichtfelder. image_url steht im Singular – dieses Modell akzeptiert genau ein Referenzbild, kein Array.
• duration akzeptiert nur 4, 6 oder 8 (Sekunden) – keine anderen Ganzzahlen.
• aspect_ratio akzeptiert auto, 16:9 oder 9:16.
• resolution akzeptiert 720p oder 1080p.
• Optionale Zusätze: seed (Ganzzahl, zur Reproduzierbarkeit), generate_audio (Boolescher Wert), negative_prompt (Zeichenkette).

Beachte, dass die Modell-ID eine nackte ID ist, also veo-3.1-lite/image-to-video – stelle ihr keinen Präfix oder Namespace voran.

Sobald status zu "success" wird, liegt das Ausgabevideo unter data.output[0].url. Diese URL ist temporär (sie hat ein expireAt), lade sie also sofort herunter oder hoste sie neu, statt den Hotlink zu speichern.

Hinweise für die Produktion: Callbacks, Idempotenz und Fehler

Alle 5 Sekunden zu pollen ist für ein Skript in Ordnung, aber in einem Server, der viele Tasks gleichzeitig verarbeitet, verschwenderisch. Für Produktionsverkehr sind Callbacks die bessere Wahl: Übergib ein callback-Objekt in derselben Task-Erstellungsanfrage, und hiapi POSTet das Endergebnis an deinen Endpunkt, statt dass du nachfragst.

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
    },
    "callback": {
        "url": "https://yourapp.example.com/hooks/hiapi",
        "when": "final",
    },
}

Die entscheidende Einstellung hier ist when: "final" – sie bedeutet, dass du nur einmal benachrichtigt wirst, wenn der Task einen Endzustand erreicht (success oder fail), statt bei jeder Zwischenzustandsänderung. Dein Webhook-Handler sollte die Task-ID validieren und dann den lokalen Task-Datensatz nachschlagen, den du beim ursprünglichen Aufruf von POST /v1/tasks angelegt hast.

Idempotenz. Falls dein Dienst den Task-Erstellungsaufruf wiederholen könnte (Timeouts, At-least-once-Zustellung usw.), füge einen Idempotency-Key-Header mit bis zu 255 Byte hinzu:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Idempotency-Key: order-42-veo-submit" \
  -H "Content-Type: application/json" \
  -d '{...}'

Ein erneuter Versuch mit demselben Schlüssel unter demselben Konto gibt die ursprüngliche taskId zurück, statt einen zweiten (kostenpflichtigen) Task zu erstellen – du kannst also beruhigt aus Wiederholungsschleifen heraus aufrufen, ohne Kunden doppelt zu belasten.

Polling vs. Callback, kurz gesagt: Für Skripte, Notebooks oder interne Tools mit geringem Traffic verwende Polling, wenn du ohnehin blockierend auf das Ergebnis wartest. Für jede serverseitige und nebenläufige Szene verwende Callbacks – sie vermeiden offen gehaltene Verbindungen und skalieren auf viele laufende Tasks, ohne für jeden Task eine Polling-Schleife laufen zu lassen.

Fehlerbehandlung. Fehlerhafte oder widerrufene Schlüssel geben HTTP 401 und error.code: "permission_denied" zurück – prüfe das gezielt, statt anzunehmen, dass jedes Nicht-2xx bedeutet, die Videogenerierung selbst sei fehlgeschlagen. Fehlerhaftes input (fehlendes prompt, duration außerhalb der Enum-Werte, nicht erkannte Felder) gibt HTTP 400 und error_code: "INVALID_REQUEST" zurück, mit einer Meldung, die das konkrete Problemfeld benennt – es lohnt sich, diese direkt in deinen eigenen Logs sichtbar zu machen statt sie zu verschlucken, denn die Meldung sagt dir genau, was du korrigieren musst. Sobald der Task akzeptiert wurde, zeigen sich Fehler auf der Generierungsseite als status: "fail" und einem error-Objekt in der Polling-/Callback-Nutzlast – behandle es nur dann als wiederholbar, wenn die Meldung auf ein vorübergehendes Upstream-Problem hindeutet, nicht auf ein Schema-Problem.

Verwandte Ressourcen

• veo-3.1-lite/image-to-video Modelldokumentation – vollständige Parameterreferenz für dieses spezielle Modell
• Task erstellen und Task-Details abrufen – die beiden Endpunkte, auf denen diese Anleitung aufbaut
• Authentifizierungsdokumentation – Schlüsselformat und Header-Anforderungen
• Veo 3.1 Image-to-Video: Kurzvideos-Leitfaden – eine Erläuterung des Anwendungsfalls, falls du eine höhere Wiedergabetreue mit dem Nicht-Lite-Modell möchtest
• Preise – aktuelle Sekundensätze nach Dauer und Auflösung

Häufige Fragen

Muss ich image_url als Data-URI oder base64 übergeben? Nein – image_url muss eine öffentliche HTTP(S)-URL sein, die der hiapi-Server abrufen kann. Dieses Modell akzeptiert keine base64-kodierten Bilder.

Kann ich ein Video ohne Referenzbild generieren? Mit veo-3.1-lite/image-to-video nicht – es ist ein Image-to-Video-Modell, image_url ist Pflicht. Wenn du reine Textgenerierung möchtest, verwende stattdessen ein Text-to-Video-Modell; die Seite des Nicht-Lite-Modells Veo 3.1 listet die verfügbaren Modi auf.

Warum erhalte ich immer noch 400, obwohl ich alle Pflichtfelder übergeben habe? Prüfe, ob es zusätzliche Felder gibt – das Eingabeschema dieses Modells lehnt alles ab, was nicht in der Erlaubnisliste steht (prompt, image_url, duration, aspect_ratio, resolution, seed, generate_audio, negative_prompt). Die Fehlermeldung benennt das genaue Feld, das sie nicht kennt.

Wie lange dauert die Generierung tatsächlich? Das variiert je nach Dauer und aktueller Warteschlangentiefe – genau deshalb ist kurzes Polling oder ein Callback die richtige Vorgehensweise, statt eine feste Wartezeit anzunehmen.

Kann die Ausgabe Audio enthalten? Ja, über den booleschen Wert generate_audio – sieh in der Modelldokumentation nach den aktuellen Standardwerten und wie sie die Kosten beeinflussen.

Was passiert, wenn mein Callback-Endpunkt beim Abschluss des Tasks nicht erreichbar ist? Verlass dich nicht allein darauf, dass der Callback ankommt – behalte die taskId aus dem Erstellungsaufruf, und falls innerhalb eines angemessenen Zeitfensters kein Callback eintrifft, wechsle zum Polling von GET /v1/tasks/<id>.