Tutorial

Wie verwendet man die Ray 3.2 API? In 5 Minuten das erste Video generieren

Online-Test in 4 Schritten, API-Integration in 4 Schritten, mit direkt ausführbarem curl und Python, Anfangs-/Endframe-Methode und Hinweisen für den Produktivbetrieb.

Oct 21, 2026

Modell: ray-3.2

TL;DR

Was ist das: Luma AI's Ray 3.2, bei HiAPI in zwei Varianten unterteilt: ray-3.2/text-to-video nimmt nur Prompts entgegen, ray-3.2/image-to-video wird durch ein Anfangsbild (optional Endbild) gesteuert. Ist bereits auf HiAPI verfügbar, Text-zu-Video-Modellseite öffnen und direkt generieren, neue Nutzer erhalten bei Registrierung 200 Credits.
Was kostet es: Abrechnung pro Video, 5 Sekunden 540p $0.2145, 720p $0.429, 1080p $1.7145; 10 Sekunden gibt es nur bei Text-zu-Video, 540p $0.643, 720p $1.286, 1080p $5.143. Bei Fehlschlag automatische Rückerstattung.
Wie ruft man die API auf: POST https://api.hiapi.ai/v1/tasks, model auf die entsprechende Variante setzen, nach Erhalt der taskId pollen oder auf callback.url warten, dann das stumme MP4 von data.output[0].url herunterladen.

Die Ausgabe von Ray 3.2 ist ein stummes MP4. Bei Text-zu-Video kann man Dauer und Seitenverhältnis im Request wählen; Bild-zu-Video ist fest auf 5 Sekunden, das Seitenverhältnis folgt dem Anfangsbild. Im Folgenden vom Online-Test über curl, Python, Bild-zu-Video bis zu Hinweisen für den Produktivbetrieb – alles in einem Durchgang.

Was ist Ray 3.2? Wie wählt man die Variante?

Text-zu-Video: Nur prompt übergeben, optional duration (5 oder 10 Sekunden), resolution (540p / 720p / 1080p), aspect_ratio (16:9, 9:16, 1:1, 4:3, 3:4, 21:9). Prompt maximal 6000 Zeichen.
Bild-zu-Video: Pflichtfelder prompt und Anfangsbild image_url, optional Endbild end_image_url, resolution. Jedes Video fest 5 Sekunden, Seitenverhältnis folgt dem Anfangsbild, wird automatisch auf das nächstliegende unterstützte Verhältnis abgestimmt.
Gemeinsamkeiten: Beide laufen über /v1/tasks, beide werden pro Video abgerechnet, beide geben ein MP4 ohne Tonspur aus.

Text-zu-Video eignet sich für Szenen, bei denen nur eine textliche Vorstellung existiert und 10 Sekunden oder ein bestimmtes Seitenverhältnis benötigt werden; Bild-zu-Video eignet sich, wenn bereits Produktbilder, Poster, Konzeptbilder vorliegen oder das Endbild festgelegt werden soll. Die gemeinsamen 5-Sekunden-Optionen in allen drei Auflösungen kosten gleich viel, 10 Sekunden gibt es nur bei Text-zu-Video.

Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.

Mit diesem Prompt generieren →, Seitenverhältnis 21:9 wählen, 540p kostet $0.2145 pro Video.

Zwei Einstiegswege: Online-Test oder API?

Online-Test (ca. 1 Minute)

Ray 3.2 Text-zu-Video-Modellseite öffnen oder den vorbefüllten Link oben anklicken.
Registrieren oder anmelden, neue Konten erhalten 200 Credits; ein 5-Sekunden-540p-Video kostet 429 Credits, nach Aufladen kann generiert werden.
Prompt schreiben, Dauer, Auflösung und Seitenverhältnis wählen, auf Ausführen klicken.
Zufriedenstellendes Ergebnis herunterladen; wenn man die API benötigt, im Dashboard einen Key erstellen.

API-Integration (ca. 5 Minuten)

Im HiAPI-Dashboard einen API Key erstellen (sk-...).
POST /v1/tasks zum Erstellen einer Aufgabe, aus der Antwort data.taskId entnehmen.
Mit GET /v1/tasks/{id} abfragen oder im Request-Body auf oberster Ebene callback.url mitgeben und auf Benachrichtigung warten.
Nachdem data.status zu success geworden ist, das Video von data.output[0].url herunterladen.

5 Sekunden 540p kostet $0.2145 pro Video, mit $10 lassen sich etwa 46 Videos generieren – genug, um die Bewegung einer Szenengruppe gründlich zu testen. Zur Modellseite und das erste Video testen →

Das erste Video: curl-Version

Text-zu-Video-Aufgabe erstellen:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/text-to-video",
    "input": {
      "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "21:9"
    }
  }'

Die zurückgegebene Task-ID steht in data.taskId:

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

Ergebnis abfragen:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Nur prompt ist Pflichtfeld. duration ist standardmäßig 5, resolution standardmäßig 540p, aspect_ratio standardmäßig 16:9. Alle drei Felder werden streng validiert, falsche Werte führen direkt zu 400, es wird nicht automatisch gerundet.

Das erste Video: Python-Version

Erstellen, Pollen und Herunterladen in einem Durchgang:

import time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "ray-3.2/text-to-video",
    "input": {
        "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
        "duration": 5,
        "resolution": "540p",
        "aspect_ratio": "21:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video_url = task["output"][0]["url"]
    with open("ray32-clip.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
else:
    print(task.get("error"))

Videoaufgaben dauern in der Regel einige Dutzend Sekunden bis mehrere Minuten, Polling-Intervall auf 5 Sekunden setzen, Timeout-Obergrenze bei 10–15 Minuten. Ausgabelinks laufen ab, nach Erhalt sofort herunterladen und im eigenen Speicher ablegen.

Bild-zu-Video: ein Anfangsbild oder Anfangs- und Endbild hinzufügen

model auf ray-3.2/image-to-video ändern und das Anfangsbild image_url hinzufügen – derselbe Request wird zu Bild-zu-Video:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "The ribbon of milk keeps folding down through the iced espresso, the ice cubes settle and shift slightly, condensation beads slide down the outside of the glass, very slow push-in toward the glass, warm rim light stays steady, vertical product commercial shot",
      "image_url": "https://www.hiapi.ai/images/model-pages/ray-3-2/iced-coffee-first.jpg",
      "resolution": "1080p"
    }
  }'

Um das Endbild festzulegen, zusätzlich end_image_url hinzufügen. Je näher Kameraposition, Licht und Position des Motivs bei Anfangs- und Endbild beieinander liegen, desto stabiler die Übergänge; bei unterschiedlichen Bildausschnitten fügt das Modell selbst eine Kamerabewegung zur Verbindung hinzu. Beide Felder beeinflussen den Preis nicht.

Bild-zu-Video hat kein duration und kein aspect_ratio: Jedes Video ist fest 5 Sekunden, das Seitenverhältnis wird anhand des Anfangsbilds auf das nächstliegende von 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 abgestimmt, bei abweichendem Verhältnis werden Ränder abgeschnitten. Wenn das Ausgabeverhältnis vollständig kontrollierbar sein soll, das Anfangsbild vorher auf eines dieser sechs Verhältnisse zuschneiden.

Diese 3 Dinge vor dem Produktivbetrieb beachten

Serverseitig Callback verwenden. Im Request-Body auf oberster Ebene "callback": {"url": "https://yourapp.com/webhook", "when": "final"} hinzufügen, die Aufgabe benachrichtigt automatisch beim Erreichen des Endzustands und spart das Polling. Sowohl success als auch fail lösen einen Callback aus, serverseitig anhand taskId idempotent behandeln.
Bei Timeout nicht erneut POSTen. Jeder POST erstellt eine neue Aufgabe und wird separat abgerechnet. Zuerst taskId speichern, vor einem Retry im eigenen System deduplizieren; wenn der Prozess abstürzt, mit der gespeicherten ID weiter abfragen.
Parameter in jedem Request explizit angeben. resolution bestimmt direkt den Stückpreis, duration akzeptiert nur die Ganzzahlen 5 oder 10, bei Bild-zu-Video kein duration und aspect_ratio mitgeben. Im Request festschreiben, damit Abrechnung und Verhalten vorhersehbar bleiben.

Häufige Fehler, einer pro Zeile

400 INVALID_REQUEST, resolution-Wert ungültig → Akzeptiert nur 540p, 720p, 1080p, kein 2k, 480p.
400, duration-Wert ungültig → Akzeptiert nur die Ganzzahlen 5 und 10; String "5" oder Zahl 7 schlagen beide fehl.
400 additional properties 'aspect_ratio' not allowed → Bild-zu-Video hat dieses Feld nicht, entfernen; nur Text-zu-Video unterstützt es.
401 permission_denied → Key fehlt, falsch geschrieben oder widerrufen, Authorization: Bearer sk-... prüfen.
Erstellung gibt 200 zurück, Aufgabe schlägt später fail → Meist ist bei Bild-zu-Video die image_url nicht erreichbar oder kein Bild. Bei der Erstellung wird nur die Feldstruktur validiert, nicht ob die URL erreichbar ist.
Link funktioniert nach einigen Tagen nicht mehr → Ausgabe-URLs haben eine Gültigkeitsdauer, nach Erhalt sofort herunterladen.

Der vorab einbehaltene Betrag fehlgeschlagener Aufgaben wird automatisch vollständig zurückerstattet.

Häufige Fragen

Wie lang ist ein Ray 3.2 Video? Text-zu-Video wahlweise 5 oder 10 Sekunden; Bild-zu-Video fest 5 Sekunden.

Wie lang darf der Prompt sein? Beide Varianten 1–6000 Zeichen.

Hat das fertige Video Ton? Nein, die Ausgabe ist ein MP4 ohne Tonspur, Musik und Soundeffekte werden in der Postproduktion hinzugefügt.

Kann man bei Bild-zu-Video das Seitenverhältnis selbst wählen? Nein. Das Seitenverhältnis folgt dem Anfangsbild und wird automatisch auf das nächstliegende unterstützte Verhältnis abgestimmt.

Kann man bei Text-zu-Video ein Referenzbild übergeben? Nein. Wenn Bildsteuerung benötigt wird, ray-3.2/image-to-video verwenden.

Ray 3.2 Artikelserie

Jetzt testen: Unter dem Leuchtturm-Video oben auf Mit diesem Prompt generieren → klicken, der Prompt ist bereits eingefüllt, 5 Sekunden, 540p, 21:9 wählen und mit einem Klick dasselbe Ergebnis erhalten.

TagsAPI-Zugriff Tutorial