HiAPI
Blog

Tutorial

So rufen Sie die veo-3.1 Text-zu-Video-API auf: curl- und Python-Beispiele

Ein praxisorientierter Integrationsleitfaden für Entwickler

Nov 17, 2026
Flächiges, facettiertes Mineralquerschnitt-Cover-Artwork in tiefen Petrol-, Türkis- und Malachittönen für das veo-3.1-Text-to-Video-API-Tutorial.
Auf dieser Seite

Was veo-3.1/text-to-video für Sie tun kann

veo-3.1/text-to-video ist ein Text-zu-Video-Generierungsmodell, das über die einheitliche HiAPI-API bereitgestellt wird. Sie senden einen Text-Prompt, wählen einige Ausgabeoptionen und erhalten dann das generierte Video. Es befindet sich zusammen mit anderen Generierungs-Endpunkten auf HiAPI, sodass Ihnen die Integration vertraut vorkommen wird, wenn Sie bereits Bild- oder Chat-Funktionen auf der Plattform nutzen: Eine authentifizierte HTTP-Anfrage gibt einen Auftrag zurück, den Sie durch Polling abfragen, bis er abgeschlossen ist.

Dieser Endpunkt ist die richtige Wahl, wenn Sie eine Textbeschreibung einer Szene haben und ein kurzes Video generieren möchten, ohne selbst Infrastruktur verwalten zu müssen. Sie müssen sich nicht um GPU-Zuweisung, Modellgewichte oder Warteschlangen kümmern. Der Preis dafür ist, dass die Generierung asynchron erfolgt: Sie reichen den Auftrag ein und schauen später nach dem Ergebnis. Das ist bei Videos üblich, da das Rendern länger dauert als ein einzelner Request/Response-Zyklus.

Verwenden Sie Text-zu-Video, wenn die Kerneingabe ein Prompt ist. Wenn Sie später bild- oder videokonditionierte Generierung benötigen, sehen Sie sich die entsprechenden Endpunkte im Modellkatalog an. Die Request-Struktur hier (Authentifizierung, Auftragseinreichung, Polling) entspricht dem Muster, das Sie bei den HiAPI-Medien-Endpunkten wiederverwenden werden, sodass sich das einmalige Erlernen langfristig auszahlt. Die vollständigen Modelldetails finden Sie auf der veo-3.1/text-to-video-Modellseite.

Endpunkt, Authentifizierung und Request-Struktur

Alle HiAPI-Anfragen verwenden HTTPS und ein Bearer-Token. Bewahren Sie Ihren API-Schlüssel in einer Umgebungsvariable auf, statt ihn fest zu kodieren, und senden Sie ihn im Authorization-Header:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Eine Text-zu-Video-Anfrage ist ein JSON-Objekt mit einem model-Feld und einem input-Objekt. Das input-Objekt enthält den Prompt sowie beliebige Ausgabesteuerungen. Der minimale Request-Body sieht so aus:

{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "Nachts durch eine regennasse Neon-Gasse, langsame Dolly-in-Fahrt"
  }
}

Zurückgegeben wird nicht das endgültige Video, sondern ein Auftrags-Envelope. Er enthält in der Regel eine Auftragskennung, ein Statusfeld und einen Zeitstempel. Die Struktur sieht ungefähr so aus:

{
  "id": "job_abc123",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z"
}

Die genauen Feldnamen entnehmen Sie der tatsächlichen Antwort, aber die Struktur ist konsistent: Sie benötigen die id für das Polling, und status sagt Ihnen, ob der Auftrag in der Warteschlange steht, läuft oder abgeschlossen ist. Gehen Sie nicht davon aus, dass der Auftrag abgeschlossen ist, nur weil der Einreichungsaufruf 200 zurückgibt – das bedeutet lediglich, dass der Auftrag angenommen wurde.

Parameter auswählen: natives Audio und Auflösungsstufen

Neben dem Prompt sind die wichtigsten Parameter für Text-zu-Video, ob natives Audio generiert wird und welche Zielauflösungsstufe gewählt wird. Beide beeinflussen die Generierungszeit und die Art der Ausgabe, daher sollten Sie bewusst wählen, statt blind Standardwerte zu verwenden.

Natives Audio

Einige Videomodelle können eine Tonspur zusätzlich zum Bild erzeugen. Wenn dieser Endpunkt einen Schalter für natives Audio bietet, bedeutet das Aktivieren, dass der generierte Clip synchronisierten Ton enthält. Das ist nützlich für Szenen, in denen Audio Teil des Erlebnisses ist – Umgebungsgeräusche, Musik oder Soundeffekte passend zur Handlung. Wenn Sie planen, später Ihre eigene Musik oder Erzählung hinzuzufügen, deaktivieren Sie es, damit sich die Ausgabe auf das Bild konzentriert. Die Audiogenerierung erhöht zudem die Verarbeitungszeit, aktivieren Sie sie also nur, wenn Sie sie wirklich benötigen.

Auflösungsstufen

Auflösungsstufen ermöglichen einen Kompromiss zwischen Bildtreue und Kosten bzw. Latenz. Höhere Stufen erzeugen klarere Ausgaben, dauern aber länger und verbrauchen mehr Ressourcen. Wählen Sie die niedrigste Stufe, die Ihr Lieferziel erfüllt: eine Entwurfsstufe für Iteration und Review, eine höhere Stufe für das finale Rendering. Wenn Sie viele Kandidaten für einen Prompt generieren, erkunden Sie mit einer niedrigeren Stufe und generieren Sie den Gewinner anschließend in voller Qualität neu. Die Abrechnung richtet sich nach der generierten Ausgabe, daher ist die bewusste Wahl der Stufe Ihr wichtigster Hebel.

Wenn Sie unsicher sind, welche Werte dieser Endpunkt derzeit akzeptiert, senden Sie zuerst eine Anfrage nur mit dem Prompt und prüfen Sie dann die Antwort oder Fehlermeldung. HiAPI gibt strukturierte Validierungsfehler zurück, die die akzeptablen Felder auflisten, sodass Sie entsprechend anpassen können, ohne zu raten.

Ausführbare curl-Anfrage

Dieser curl-Befehl reicht einen Text-zu-Video-Auftrag ein. Er setzt den JSON-Inhaltstyp, übergibt das Bearer-Token aus einer Umgebungsvariable und sendet den Request-Body mit model und input.

curl -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1/text-to-video",
    "input": {
      "prompt": "Nachts durch eine regennasse Neon-Gasse, langsame Dolly-in-Fahrt",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Ein erfolgreicher Aufruf gibt ein JSON-Objekt mit der Auftrags-id und dem status zurück. Notieren Sie sich diese id – Sie benötigen sie für das Polling. Wenn Sie ein Skript schreiben, können Sie die Ausgabe durch einen JSON-Prozessor leiten, um die id zu extrahieren:

JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1/text-to-video","input":{"prompt":"Nachts durch eine regennasse Neon-Gasse, langsame Dolly-in-Fahrt"}}' \
  | jq -r '.id')
echo "$JOB_ID"

Passen Sie den Endpunktpfad, die Parameternamen und alle optionalen Felder an die Erwartungen der tatsächlichen API an. Dieses Muster – einen JSON-Body per POST senden und die id aus der Antwort lesen – bildet die Grundlage für jedes weitere Beispiel.

Dieselbe Anfrage mit Python senden

Die Python-Version verwendet die Standard-requests-Bibliothek, um dasselbe zu tun. Lesen Sie den Schlüssel aus der Umgebung, bauen Sie die Payload auf und senden Sie sie ab.

import os
import requests

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

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

payload = {
    "model": "veo-3.1/text-to-video",
    "input": {
        "prompt": "Nachts durch eine regennasse Neon-Gasse, langsame Dolly-in-Fahrt",
    },
}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json=payload,
    timeout=60,
)
response.raise_for_status()

job = response.json()
job_id = job["id"]
print(f"Auftrag eingereicht: {job_id} (Status: {job.get('status')})")

Zwei Punkte verdienen Hervorhebung. Erstens wandelt response.raise_for_status() HTTP-Fehler in Ausnahmen um, sodass Fehler sofort sichtbar werden, statt dass eine fehlerhafte Payload stillschweigend weiterläuft. Zweitens verhindert timeout=60, dass eine hängende Verbindung Ihr Skript blockiert. Die Einreichung selbst ist schnell; das eigentliche Video wird asynchron gerendert, Sie warten hier also nicht auf die Datei. Als Nächstes verwenden Sie die job_id, um den Abschluss abzufragen.

Den asynchronen Auftrag abfragen, bis das Video bereit ist

Nach der Einreichung fragen Sie den Auftrags-Endpunkt ab, bis der Status den Abschluss oder ein Scheitern anzeigt. Eine einfache Schleife mit kurzer Pause reicht für den Anfang aus.

import time

while True:
    res = requests.get(
        f"{BASE_URL}/videos/generations/{job_id}",
        headers=headers,
        timeout=30,
    )
    res.raise_for_status()
    state = res.json().get("status")
    print(f"Status: {state}")

    if state == "succeeded":
        video_url = res.json().get("output", {}).get("url")
        print(f"Video ist bereit: {video_url}")
        break
    if state == "failed":
        raise RuntimeError(f"Auftrag fehlgeschlagen: {res.json()}")

    time.sleep(5)

Einige praktische Verbesserungen: Beginnen Sie mit einem kurzen Intervall und erhöhen Sie es schrittweise, um verschwendete Anfragen zu reduzieren; fügen Sie eine maximale Anzahl von Versuchen oder eine Frist hinzu, damit hängende Aufträge nicht endlos schleifen; und behandeln Sie unerwartete Zustände mit Vorsicht, statt anzunehmen, dass sie „weiter warten“ bedeuten. Häufige Statuswerte sind queued, running, succeeded und failed. Bei einem erfolgreichen Auftrag enthält die Antwort in der Regel eine Ausgabe-URL; laden Sie die Datei zeitnah herunter und speichern Sie sie, da signierte URLs ablaufen können.

Gestalten Sie das Polling idempotent und protokollieren Sie die Auftrags-ID bei jedem Status. Wenn Ihr Prozess neu startet, können Sie anhand der ID fortsetzen, ohne erneut einzureichen. In der Produktion sollten Sie Webhooks in Betracht ziehen, falls die Plattform sie anbietet, und Polling als Fallback verwenden.

Häufige Fehler beheben

Die meisten Fehler fallen in einige wenige Kategorien. Gehen Sie die folgende Checkliste der Reihe nach durch, statt blind zu wiederholen.

Authentifizierungsfehler (401/403)

Prüfen Sie, ob der Authorization-Header vorhanden und korrekt als Bearer <key> formatiert ist und ob die Umgebungsvariable tatsächlich in der Shell oder dem Prozess gesetzt ist, der die Anfrage sendet. Eine häufige Falle ist, das Skript in einer Umgebung auszuführen, in der der Schlüssel in einer Shell vorhanden, in einer anderen aber nicht gesetzt ist.

Validierungsfehler (400/422)

Diese Fehler liefern strukturierte Details dazu, welches Feld fehlerhaft ist. Häufige Ursachen: fehlender prompt, nicht unterstützte resolution- oder duration-Werte oder eine falsche Verschachtelungsebene von Parametern. Nehmen Sie die Fehlermeldung wörtlich – sie benennt in der Regel das problematische Feld. Senden Sie zuerst eine minimale Payload und fügen Sie dann jeweils einen Parameter hinzu.

Ratenbegrenzung (429)

Sie senden Anfragen zu schnell. Implementieren Sie exponentielles Backoff und eine Obergrenze für Wiederholungen. Wenn Sie viele Aufträge starten, staffeln Sie die Einreichungen und verfolgen Sie laufende Aufträge.

Timeouts und Netzwerkfehler

Ein Client-Timeout bei der Einreichung ist selten ein Problem des Auftrags selbst – der Auftrag läuft serverseitig. Verwenden Sie angemessene Timeouts sowohl für Einreichungs- als auch für Polling-Anfragen und wiederholen Sie idempotente GET-Anfragen. Wiederholen Sie niemals blind ein POST, ohne zu prüfen, ob der ursprüngliche Auftrag bereits erstellt wurde.

Auftrag wird nie abgeschlossen

Wenn ein Auftrag deutlich länger als erwartet im Zustand queued oder running bleibt, prüfen Sie Statuscode und Meldung, statt erneut einzureichen. Lange Prompts oder höhere Auflösungsstufen benötigen mehr Zeit; das ist normal. Wenn ein Auftrag als failed gemeldet wird, protokollieren Sie den vollständigen Antwort-Body – die Fehlermeldung benennt in der Regel die Ursache.

Wenn Sie unsicher sind, reproduzieren Sie mit der kleinstmöglichen Anfrage und prüfen Sie jede Antwort. Das ist viel besser, als mehrere Parameter gleichzeitig zu ändern und dann zu raten, welcher wichtig war. Endpunktspezifische Details finden Sie auf der Modellseite.

Ä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