HiAPI
De
Blog

Tutorial

So verwenden Sie veo-3.1-lite/text-to-video über die hiapi API: curl, Python und eine ausführbare Anfrage

Aug 27, 2026
So verwenden Sie veo-3.1-lite/text-to-video über die hiapi API: curl, Python und eine ausführbare Anfrage

veo-3.1-lite/text-to-video erzeugt allein aus einem Text-Prompt einen kurzen Videoclip – ohne Ausgangsbild. Dieser Leitfaden enthält direkt kopierbare curl- und Python-Beispiele für die echte hiapi-Task-API, das exakte Input-Schema (gegen den Live-Endpunkt verifiziert) sowie die Fehlerformen, die Ihnen in der Produktion tatsächlich begegnen werden.

1. Voraussetzungen

  • Ein hiapi-Konto und ein API-Key (sk-...), den Sie im API-Keys-Dashboard erhalten.
  • curl oder Python 3 mit installiertem requests (pip install requests).
  • Mehr ist nicht nötig – text-to-video benötigt nur einen Prompt-String.

Jedes Generierungsmodell auf hiapi läuft über dieselbe einheitliche asynchrone Task-API: POST /v1/tasks erstellt eine Aufgabe, anschließend rufen Sie das Ergebnis per Polling ab oder warten auf einen Callback. veo-3.1-lite/text-to-video wird genau wie jedes andere Videomodell aufgerufen – gleiche Auth-Header, gleicher Task-Lebenszyklus –, nur model und input unterscheiden sich. Die Modell-ID lautet veo-3.1-lite/text-to-video mit dem Suffix /text-to-video; dieselbe Familie bietet außerdem veo-3.1-lite/image-to-video, eine separate Modell-ID, die stattdessen ein Ausgangsbild animiert.

2. Minimales ausführbares Beispiel

2.1 Aufgabe erstellen (curl)

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "a paper boat drifting down a rain-slicked city street at night, neon signs reflecting on wet asphalt",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'

Bei erfolgreichem Aufruf wird sofort eine Task-ID zurückgegeben – die Generierung erfolgt asynchron:

{"code":200,"data":{"taskId":"tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX"},"message":"success"}

2.2 Ergebnis per Polling abfragen

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer sk-<your-api-key>"

Während der Clip gerendert wird, ist status gleich "handling". Nach Abschluss:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX",
    "model": "veo-3.1-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {"artifactId": "...", "type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786932195}
    ]
  },
  "message": "success"
}

output[0].url ist ein temporärer, ablaufender Link – laden Sie die Datei herunter (oder überführen Sie die Ausgabe in persistenten Speicher), bevor expireAt abläuft.

2.3 Vollständiges Python-Beispiel

import time
import requests

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


def create_task(prompt: str) -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "veo-3.1-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": 6,
            "resolution": "720p",
            "aspect_ratio": "16:9",
        },
    }, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, poll_seconds: int = 5, timeout_seconds: int = 600) -> str:
    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(poll_seconds)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_seconds}s")


if __name__ == "__main__":
    tid = create_task("a paper boat drifting down a rain-slicked city street at night")
    video_url = wait_for_result(tid)
    print(video_url)

3. Input-Schema

Alle folgenden Felder liegen unter input. Das Schema ist strikt – ein nicht existierendes Feld führt zu einem 400 (additional properties '<field>' not allowed), was eine gute Möglichkeit ist, die Anfrage schnell vor dem Rendern zu validieren.

Feld Typ Erforderlich Beschreibung
prompt string Ja Szenenbeschreibung; geben Sie Motiv, Bewegung und Kameraführung konkret an.
duration integer Nein Einer der Werte 4, 6, 8 (Sekunden).
resolution string Nein "720p" oder "1080p".
aspect_ratio string Nein "16:9" oder "9:16".
generate_audio boolean Nein Fügt beim Rendern synchronisiertes Umgebungs-/Soundeffekt-Audio hinzu.
negative_prompt string Nein Inhaltselemente, die das Rendering vermeiden soll.
seed integer Nein Fester Wert, um zwischen Wiederholungen dieselbe Komposition/Bewegung zu reproduzieren.

Längere Dauern und höhere Auflösungen erhöhen die Rendering-Kosten – bevor Sie Batch-Aufgaben skalieren, prüfen Sie die aktuellen modellbasierten Preise auf der Preisseite.

4. Produktionsmuster

Im großen Maßstab Callbacks statt Polling bevorzugen

Für alles, was über ein einmaliges Skript hinausgeht, registrieren Sie einen Callback, anstatt in einer Schleife zu pollen:

{
  "model": "veo-3.1-lite/text-to-video",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-app.example.com/webhooks/hiapi", "when": "final"}
}

callback.url muss eine erreichbare http(s)-URL sein, und when akzeptiert nur "final" – hiapi sendet ein einziges POST, wenn die Aufgabe einen Endzustand (success oder failed) erreicht. So vermeiden Sie, Ihr Anfragekontingent in Polling-Schleifen zu verschwenden, und erhalten das Ergebnis genau in dem Moment, in dem es fertig ist – was bei Video wichtiger ist (Rendering dauert länger als Bildgenerierung).

Idempotenz und Wiederholungen

Falls Ihr Task-Runner die Übermittlung wiederholen kann (Absturz, Timeout, erneutes Deployment), zeichnen Sie vor dem Absenden Ihren eigenen Idempotenz-Schlüssel zusammen mit der zurückgegebenen taskId auf, damit eine Wiederholung prüfen kann: „Habe ich das bereits übermittelt?“, anstatt ein doppeltes Rendering zu erzeugen und dafür zweimal zu bezahlen.

Fehlerbehandlung

In der Praxis treten zwei unterschiedliche Fehlerformen auf:

  • Fehlerhafte Eingabe (400) – Validierungsfehler im Request-Body: 
    {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}
  • Authentifizierungs-/Berechtigungsfehler (401) – Schlüssel fehlt, ist ungültig oder hat unzureichende Berechtigungen: 
    {"error":{"code":"permission_denied","message":"This API key cannot use the selected model...","request_id":"...","type":"hiapi_error"}}

Verzweigen Sie zuerst nach HTTP-Statuscode und prüfen Sie dann den Response-Body – 400 bedeutet fast immer einen falschen Feldnamen oder Wert (Anfrage korrigieren), während 401 bedeutet, dass der Schlüssel selbst behandelt werden muss (Dashboard-Berechtigungen oder ein neuer Schlüssel).

5. Verwandte Seiten

Häufige Fragen

Benötigt veo-3.1-lite/text-to-video ein Ausgangsbild? Nein. Es generiert ausschließlich aus dem prompt-String. Wenn Sie ein Ausgangsbild haben, das animiert werden soll, verwenden Sie stattdessen die separate Modell-ID veo-3.1-lite/image-to-video.

Welche Auflösungen und Dauern werden unterstützt? resolution ist "720p" oder "1080p"; duration ist 4, 6 oder 8 Sekunden. Jeder andere Wert führt zu einem 400 mit Auflistung der zulässigen Werte.

Können die erzeugten Clips Audio enthalten? Ja – setzen Sie "generate_audio": true in input, um synchronisiertes Umgebungs-/Soundeffekt-Audio einzubeziehen.

Wie vermeide ich Polling in einer Schleife? Übergeben Sie ein callback-Objekt mit Ihrer Webhook-url und "when": "final". hiapi sendet nach Abschluss der Aufgabe ein POST an diese URL, statt dass Sie regelmäßig GET /v1/tasks/<id> erneut prüfen müssen.

Warum gibt meine Anfrage 401 statt 400 zurück? 401 mit error_code/code gleich "permission_denied" bedeutet, dass der API-Key selbst ungültig ist oder keinen Zugriff auf das Modell hat – prüfen Sie das API-Keys-Dashboard. 400 bedeutet, dass der Request-Body für einen an sich gültigen Key fehlerhaft formatiert ist.

Ist die zurückgegebene Video-URL dauerhaft? Nein – output[0].url ist ein temporärer Link mit einem expireAt-Zeitstempel. Laden Sie ihn vor dem Ablaufen herunter oder überführen Sie ihn in persistenten Speicher.

TagsveoText-zu-VideoAPI-TutorialVideogenerierunghiapi

Ä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