Luma

Ray 3.2

ray-3.2/image-to-video

Luma-Modell zur Erzeugung filmischer Videos mit nativer Unterstützung für HDR und EXR-Export, geeignet für atmosphärische Establishing-Shots sowie für Werbe- und Konzeptfilme in der Vorproduktion von Film und Fernsehen; bei strukturierten Kameraanweisungen bleibt die Prompt-Treue stabil

ray-3.2/image-to-video ray-3.2/text-to-video

Preise

ray-3.2/image-to-video per video

Spezifikationen	Einzelpreis
540P	$0.2145
720P	$0.429
1080P	$1.7145

Positionsübersicht

Das Ray 3.2 Bild-zu-Video-Modell verwendet ein öffentliches Bild als erstes Frame und erzeugt zusammen mit einer Textbeschreibung einen filmischen Kurzfilm; das Ausgabeformat folgt automatisch dem Seitenverhältnis des ersten Frames. Optional kann ein Endframe-Bild angegeben werden, damit das Bild vom ersten Frame zum festgelegten Endpunkt übergeht; die Auflösung ist wählbar zwischen 540p, 720p und 1080p, das Ergebnis ist ein 5-Sekunden-Clip. Geeignet für Entwickler und Kreativteams, die aus einem einzelnen Keyframe eine Kamerafahrt erweitern, Konzept-Previews erstellen oder atmosphärische Leeraufnahmen (Establishing Shots) produzieren möchten.

Kernhighlights

Bidirektionale Steuerung über Start- und Endframe – Es kann nur ein Startframe angegeben werden, oder zusätzlich ein Endframe-Bild, damit das Video am festgelegten Endpunkt endet und der Kameraweg kontrollierbarer wird.
Bildformat folgt automatisch dem ersten Frame – Das Ausgabeverhältnis wird durch das erste Frame-Bild bestimmt; ohne zusätzliche Einstellungen passt es zur Komposition des vorhandenen Materials.
Drei Auflösungsstufen wählbar – 540p, 720p und 1080p nach Bedarf auswählbar, um Kosten zwischen Vorschau und finalem Ergebnis zu verteilen.

Funktionsbeschreibung

Vom ersten Frame gesteuertes Bild-zu-Video: Eine öffentliche Bild-URL als erstes Frame übergeben und mit einem Prompt Bewegung und Szene beschreiben – so entsteht ein 5-Sekunden-Video, das mit diesem Bild beginnt.

Endframe-Übergangsbedingung: Optional kann ein Endframe-Bild übergeben werden; das Modell erzeugt den Übergang vom ersten zum letzten Frame, ideal zur Steuerung des Kameranendpunkts und des Bildabschlusses.

Strukturierte Prompt-Verarbeitung: Reagiert stabiler auf konkrete, strukturierte Bewegungs- und Kamerabeschreibungen; das Prompt-Limit liegt bei 6000 Zeichen und bietet Platz für eine recht vollständige Kamerabeschreibung.

Auflösungs- und Formatsteuerung: Die Ausgabeauflösung ist wählbar zwischen 540p, 720p und 1080p; das Seitenverhältnis übernimmt das erste Frame-Bild, wodurch nachträgliches erneutes Zuschneiden reduziert wird.

Anwendungsszenarien

Konzept-Preview: einzelner Keyframe + Kamerabeschreibung – Aus einem Konzeptbild oder Storyboard-Keyframe einen 5-Sekunden-Kurzclip erweitern, für dynamische Previews in der Film- und Werbepräsentationsphase.
Atmosphärische Leeraufnahme: Szenenbild + Umgebungsbewegung – Ein statisches Szenenbild in Umgebungsaufnahmen umwandeln, als Hintergrundbildschirm, Übergang oder atmosphärische Untermalung.
Start-End-Frame-Verknüpfung: zwei Bilder für Anfang und Ende – Mit gegebenem Start- und Endbild einen Übergangsclip dazwischen erzeugen, für Szenenübergänge und Rhythmussteuerung.
Marketing-Clip: Produktbild + Bewegungsprompt – Mit einem Produktbild als erstem Frame kurzes dynamisches Material erzeugen, für die schnelle Produktion von Social- und Marketinginhalten.

Einschränkungen und Auswahlhinweise

Eine einzelne Generierung ergibt fest einen 5-Sekunden-Clip; längere Dauern werden nicht unterstützt. Die maximale Auflösung liegt bei 1080p, daher nicht für lange Einstellungen oder hochauflösende Master-Direktausgabe geeignet. Die Ergebnisse hängen von konkreten, strukturierten Bewegungs- und Szenenbeschreibungen ab; bei vagen Anweisungen lässt die Qualität nach, und zeitliche Konsistenz sowie Bewegungsqualität gehören nicht zu den Stärken. Wenn Text-zu-Video gewünscht ist, kann ein Text-zu-Video-Modell derselben Serie gewählt werden; für längere fertige Videos ist eine gesonderte Bewertung erforderlich. Die Abrechnung erfolgt pro Video.

Häufige Fragen

Alle Fragen ansehen →

Welche Eingaben benötigt Ray 3.2 für die Bild-zu-Video-Generierung?

Zwei Pflichtangaben: prompt (1–6000 Zeichen) und das Startbild image_url. Optional end_image_url als Endbild sowie resolution (540p, 720p, 1080p, Standard 540p). Im Playground können lokale Bilder direkt hochgeladen werden.
Kann die Videodauer festgelegt werden?

Nein. Bei der Bild-zu-Video-Generierung beträgt jedes Video fest 5 Sekunden; im Request gibt es keinen Parameter duration. Wenn Sie eine 10-sekündige Einstellung benötigen, können Sie stattdessen Ray 3.2 Text-zu-Video verwenden, das 5 und 10 Sekunden unterstützt.
Wodurch wird das Ausgabeseitenverhältnis bestimmt?

Durch das erste Frame; es gibt keinen Parameter aspect_ratio. Die Ausgabe wird an das nächstgelegene der Verhältnisse 16:9, 9:16, 1:1, 4:3, 3:4 und 21:9 angepasst; wenn das Verhältnis nicht exakt übereinstimmt, werden die Ränder beschnitten. Das Wüstenbeispiel auf dieser Seite hat ein Originalbild von etwa 3:2 (1024×687) und wird als 4:3 mit 1104×832 ausgegeben; das Eiskaffee-Beispiel hat ein Originalbild im Verhältnis 9:16 und wird als Hochformat-Video im Verhältnis 9:16 ausgegeben, praktisch ohne Beschnitt. Wenn Sie das Ausgabeverhältnis vollständig kontrollieren möchten, schneiden Sie das erste Frame vorab auf eines dieser sechs Verhältnisse zu.
Wie verwendet man Start- und Endbild?

Über image_url wird das Startbild übergeben, über end_image_url das Endbild. Das Video geht dann vom Startbild zum Endbild über, und der Prompt muss nur die dazwischen stattfindende Veränderung beschreiben. Je ähnlicher Kameraausrichtung, Licht und Position des Motivs in beiden Bildern sind, desto flüssiger ist der Übergang; bei unterschiedlicher Bildkomposition fügt das Modell Kamerabewegungen hinzu, um die Verbindung herzustellen – genau das ist beim Pfingstrosen-Beispiel auf dieser Seite der Fall.

Generierungsaufgabe erstellen

POST https://api.hiapi.ai/v1/tasks

Header

AuthorizationstringPflicht

Account-API-Schlüssel. Bei jeder Anfrage erforderlich. Beispiel: Bearer YOUR_HIAPI_API_KEY. API-Schlüssel holen

Content-TypestringOptional

Der Anfragekörper wird immer als JSON geparst; beim Senden ist nur application/json (optional mit charset) zulässig — andere Werte liefern 415. Beispiel: application/json.

Idempotency-KeystringOptional

Idempotenz-Schlüssel, bis 255 Bytes. Wiederholungen mit demselben Schlüssel desselben Kontos erstellen die Aufgabe nur einmal; Replays liefern die ursprüngliche taskId.

Idempotenz-Schlüssel

Bei Netzwerk-Timeouts oder Client-Wiederholungen erstellt derselbe Schlüssel die Aufgabe nur einmal — keine doppelte Abbuchung (Geltungsbereich = das Konto des API-Schlüssels). Empfohlen: geschäftsseitig eindeutige Kennung (z. B. "order-42"); Replays liefern die ursprüngliche taskId, Schlüssel laufen 24 Stunden nach der ersten Anfrage ab. Die vollständige Szenariomatrix steht in der Übersicht der Unified Async API.

Body

modelstringPflicht

Aktueller Festwert: ray-3.2/image-to-video

routestringOptional

Aktueller Festwert: default

inputobjectPflicht

Geschäftsparameter für ray-3.2/image-to-video und Route default — siehe Parametertabelle unten.

promptstringPflichtminLength 1maxLength 6000

Text-Prompt, der die gewünschte Dynamik und den Szeneninhalt beschreibt, der auf Basis des Eingabebilds generiert werden soll.

image_urlstringPflicht

Öffentliche Bild-URL als erstes Frame des Videos; das Seitenverhältnis des Ausgabevideos entspricht dem des Bildes.

resolutionstringOptionalStandard: "540p"

Auflösung des Ausgabevideos, Standard 540p; jedes Videosegment ist 5 Sekunden lang.

Optionen:540p720p1080p

end_image_urlstringOptional

Optionale öffentliche Bild-URL als letztes Frame des Videos; das Video geht vom ersten Frame zu diesem Frame über.

callbackobjectOptional

Konfiguration der Endzustands-Benachrichtigung. Ohne Angabe wird kein Callback gesendet — selbst abfragen.

Callbacks (Webhook)

Beim Erstellen callback.url angeben, dann POSTet HiAPI im Endzustand an Ihren Service — kein Polling nötig. Der Callback-Body entspricht der Aufgaben-Detailstruktur; Signaturprüfung, Wiederholungen und Idempotenz sind in der Übersicht der Unified Async API beschrieben.

urlstringPflicht

Pflicht, wenn callback angegeben ist. Nach dem Endzustand wird an diese URL gepostet; muss eine gültige http(s)-URL sein.

whenstringOptionalStandard: "final"

Derzeit wird nur final unterstützt — Benachrichtigung bei success und fail.

Optionen:final

storagestringOptionalStandard: "temp"

Speicherstufe für Artefakte: temp (Standard, ca. 7 Tage) oder persistent (langfristig, nach Größe abgerechnet). Bei unzureichendem Guthaben oder Überschreitung des Speicherlimits erfolgt ein stiller Downgrade auf temp; die wirksame Stufe steht in der Aufgaben-Detailantwort.

Optionen:temppersistent

Anfragebeispiele

# Asynchrone Aufgabe senden; gibt sofort eine taskId zurück (wartet nicht auf die Generierung)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ray-3.2/image-to-video",
  "input": {
    "prompt": "…",
    "image_url": "…",
    "resolution": "540p"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "ray-3.2/image-to-video",
    input: {
      "prompt": "…",
      "image_url": "…",
      "resolution": "540p"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "ray-3.2/image-to-video",
        "input": {
          "prompt": "…",
          "image_url": "…",
          "resolution": "540p"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Aufgabendetails abrufen

GET https://api.hiapi.ai/v1/tasks/:id

Antwortfelder

taskIdstringPflicht

Aufgaben-ID, stets mit Präfix tk-hiapi-.

modelstringPflicht

Aufgelöster vollständiger Modellname. Mit route-Parameter eingereichte Aufgaben geben base@route zurück (z. B. gpt-image-2/text-to-image@ext); sonst identisch mit dem übermittelten Namen.

routestringOptional

Erscheint nur bei explizitem route-Parameter; gibt den übermittelten Wert zurück.

statusstringPflicht

Aufgabenstatus.

Statuswerte

queued Eingereiht, noch nicht gestartet. handling In Verarbeitung. archiving Verarbeitung abgeschlossen, Artefakte werden vorbereitet. success Endzustand: abgeschlossen, Artefakte verfügbar (output wird zurückgegeben). fail Endzustand: fehlgeschlagen (error wird zurückgegeben). Nach dem Senden den status prüfen: success und fail sind Endzustände, alles andere nicht. Alle 1–3 Sekunden bis zum Endzustand pollen. Nach Erfolg Artefakte aus output[].url laden und vor expireAt übertragen; für Langzeitaufbewahrung storage: "persistent" beim Erstellen angeben.

creatednumberPflicht

Zeitpunkt der Aufgabenerstellung (Unix-Sekunden).

completednumberPflicht

Unix-Sekunden des Endzustands; vor Abschluss stets 0.

outputarrayOptional

Nur bei status == success. Artefaktliste — immer ein Array; eine Aufgabe kann mehrere Typen gleichzeitig liefern (z. B. video + first_frame).

Array [ object ]

Array-Elemente

urlstringPflicht

Artefakt-URL, direkt herunterladbar.

typestringPflicht

Aktuell mögliche Werte: video, image, audio, first_frame, last_frame, thumbnail; später können weitere folgen.

expireAtnumberPflicht

Unix-Sekunden, bis wann das Artefakt verfügbar ist; vorher herunterladen oder übertragen.

errorobjectOptional

Nur bei status == fail.

codestringPflicht

Business-Fehlercode.

messagestringPflicht

Fehlerbeschreibung.

Antwortbeispiele

Erfolg

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

In Bearbeitung (nicht final)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Fehlgeschlagen

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}