So verwenden Sie grok-imagine-1.5/image-to-video über die hiapi API: curl, Python und eine direkt ausführbare Anfrage

Kurzfassung

• Was das ist: Eine kopierfertige Anleitung, wie Sie mit grok-imagine-1.5/image-to-video über die einheitliche Aufgaben-API von hiapi ein Standbild in einen kurzen Clip animieren.
• Ablauf: Erstellen Sie eine Aufgabe über POST /v1/tasks, fragen Sie GET /v1/tasks/<taskId> wiederholt ab (oder registrieren Sie einen Callback) und laden Sie dann die MP4-Datei vor dem Ablaufen aus data.output[0].url herunter.
• Eingabe-Schema (gegen die Live-API verifiziert): Akzeptiert genau einen image_urls-Eintrag, optional prompt, duration von 1–15 Sekunden, resolution als 480p/720p, aspect_ratio als eines von auto, 1:1, 16:9, 9:16, 3:2, 2:3. Andere Felder werden nicht akzeptiert.

Was Sie erstellen und was Sie vorbereiten müssen

Ziel: Senden Sie ein Quellbild plus einen Bewegungsprompt und erhalten Sie einen kurzen MP4-Clip, der von Grok Imagine 1.5 generiert wurde.

Voraussetzungen:

• Ein hiapi-API-Schlüssel – erstellen Sie ihn im Dashboard. Der Schlüssel hat die Form sk-... und gehört in den Header Authorization: Bearer.
• Eine öffentlich erreichbare URL des Quellbilds (JPEG/PNG). Die API ruft das Bild serverseitig ab, daher funktionieren localhost-Links oder Dateien, die eine Authentifizierung erfordern, nicht.
• Ein beliebiger HTTP-Client. Die folgenden Beispiele verwenden curl und requests aus Python.

Die Modell-ID ist die reine Zeichenkette grok-imagine-1.5/image-to-video ohne Suffix.

Minimales ausführbares Beispiel: curl

Aufgabe erstellen:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
      "image_urls": ["https://example.com/product-shot.jpg"],
      "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Eine erfolgreiche Übermittlung liefert 200 und eine taskId:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5", "status": "queued" },
  "message": "success"
}

Fragen Sie wiederholt ab, bis die Aufgabe einen Endzustand erreicht (status durchläuft queued → handling → success oder fail):

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Eine abgeschlossene Aufgabe (echte Antwort, gekürzt):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5",
    "model": "grok-imagine-1.5/image-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/.../01KWVVSTX0TJ32AD45F6ZQ08W5-0.mp4",
        "expireAt": 1783951451
      }
    ]
  },
  "message": "success"
}

⚠️ storage: "temp" und expireAt bedeuten, dass die Download-URL temporär ist. Laden Sie die MP4-Datei sofort nach erfolgreichem Abschluss der Aufgabe herunter und speichern Sie sie in Ihrer eigenen Infrastruktur – kein Hotlinking.

Minimales ausführbares Beispiel: Python

Vollständiges Skript – erstellen, abfragen, herunterladen:

import time
import requests

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

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json={
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
        "image_urls": ["https://example.com/product-shot.jpg"],
        "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll for the result (image-to-video usually lands well within a few minutes)
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
    status = task["status"]
    if status == "success":
        break
    if status == "fail":
        raise RuntimeError(f"generation failed: {task.get('error')}")
    time.sleep(5)
else:
    raise TimeoutError(f"task {task_id} still not finished after 10 min")

# 3. Download immediately — the output URL expires
video_url = task["output"][0]["url"]
mp4 = requests.get(video_url, timeout=120)
mp4.raise_for_status()
with open("clip.mp4", "wb") as f:
    f.write(mp4.content)
print("saved clip.mp4,", len(mp4.content), "bytes")

Eingabereferenz (was das Schema tatsächlich akzeptiert)

Diese Einschränkungen stammen direkt aus dem Live-Validator und sind nicht geraten – wenn Sie etwas anderes senden, erhalten Sie 400 INVALID_REQUEST mit einer präzisen Meldung:

Feld	Typ	Regel
image_urls	String-Array	Erforderlich, genau 1 URL (maxItems: 1)
prompt	String	Optional – beschreibt Bewegung, Kamerafahrt und Stimmung
duration	Integer	1–15 Sekunden
resolution	String	480p oder 720p
aspect_ratio	String	auto, 1:1, 16:9, 9:16, 3:2, 2:3

Hinweise:

• Dieses Modell hat keine Felder seed, negative_prompt, fps, motion_strength oder camera_fixed. Das Schema lehnt unbekannte Eigenschaften ab (additional properties ... not allowed), daher steuern Sie Bewegung und Kamerafahrten vollständig über prompt.
• Pro Aufgabe ist nur ein Referenzbild zulässig. Bei zwei Bildern erhalten Sie image_urls: maxItems: got 2, want 1.
• aspect_ratio: "auto" übernimmt das Seitenverhältnis des Quellbilds – das ist in der Regel das, was Sie bei Produktbildern wollen.
• Das ältere grok-imagine/image-to-video akzeptiert bis zu 30 Sekunden pro Clip; 1.5 ist auf 15 Sekunden begrenzt. Beide kosten gleich viel pro Sekunde: $0.015 für 480p, $0.0282 für 720p.

Hinweise für den Produktivbetrieb

Verwenden Sie Callbacks statt Polling. Für alles, was über ein Skript hinausgeht, registrieren Sie beim Erstellen der Aufgabe einen Webhook und überspringen Sie die Polling-Schleife:

{
  "model": "grok-imagine-1.5/image-to-video",
  "input": { "image_urls": ["https://example.com/shot.jpg"], "duration": 6 },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

callback.url muss ein öffentlicher http(s)-Endpunkt sein, und when unterstützt nur "final" – Sie erhalten ein POST, wenn die Aufgabe success oder fail erreicht. Polling eignet sich für CLI und Batch-Aufgaben; Callbacks sind besser, wenn Sie viele Clips in großem Umfang generieren und nicht eine Schar von Pollern betreiben wollen. Behalten Sie ein Fallback-Polling bei (z. B. alle paar Minuten Aufgaben prüfen, für die kein Callback eingegangen ist), damit verlorene Webhooks keine Aufgaben stranden lassen.

Idempotenz. Die Aufgabenerstellung wird serverseitig nicht dedupliziert, daher kann ein einfacher Wiederholungsversuch nach einem Netzwerk-Timeout zu doppelten Übermittlungen und doppelter Abrechnung führen. Speichern Sie taskId sofort nach Rückkehr des Erstellungsaufrufs und prüfen Sie bei Wiederholungen zuerst Ihren eigenen Speicher; wenn Sie zwischen Übermittlung und Persistenz abstürzen, listen Sie die letzten Aufgaben auf (GET /v1/tasks) und gleichen Sie vor erneuter Übermittlung nach Modell + Erstellungszeit ab.

Fehlerbehandlung. Die Fehlermuster, die Ihnen tatsächlich begegnen werden:

• 401 mit {"error": {"code": "permission_denied", "type": "hiapi_error", ...}} – falscher Schlüssel oder der Schlüssel hat keinen Zugriff auf das Modell. Die Antwort enthält eine request_id für den Support.
• 400 mit error_code: "INVALID_REQUEST" – Schemaverletzung; die message nennt das konkrete Feld und die Regel (z. B. duration: maximum: got 99, want 15). Korrigieren Sie den Request-Body, wiederholen Sie nicht blind.
• 402 unzureichendes Guthaben – Videomodelle prüfen Ihr Kontingent beim Übermitteln. Laden Sie auf und übermitteln Sie erneut.
• Die Aufgabe selbst hat status: "fail" – ein Fehler auf der Generierungsseite; prüfen Sie data.error und wiederholen Sie mit Backoff. Ein nicht erreichbares Quellbild ist eine häufige Ursache.

Ausgaben sofort speichern. Das kann man nicht oft genug sagen: output[0].url liegt auf temporärem Speicher und trägt einen expireAt-Zeitstempel. Sobald Sie success sehen, streamen Sie die MP4-Datei sofort in Ihren eigenen Bucket. Wenn Ihre Pipeline nach dem Erfolg, aber vor dem Download abstürzt, rufen Sie die Aufgabe anhand der ID erneut ab – die URL bleibt bis expireAt gültig und nicht dauerhaft.

Weiterführende Lektüre

• Modellseite grok-imagine-1.5/image-to-video – Preise, Parameter und Playground im Browser
• So verwenden Sie grok-imagine/image-to-video – das Vorgängermodell, gleicher Aufgabenablauf, 30-Sekunden-Limit
• Grok Imagine Text-zu-Video-Anleitung – mit einem Prompt statt einem Bild beginnen
• hiapi API-Referenz – der vollständige Vertrag der Aufgaben-API

Häufig gestellte Fragen

Wie lang können grok-imagine-1.5-Videos sein? 1 bis 15 Sekunden, festgelegt über das Integer-Feld duration. Bei längeren Anfragen wird 400 zurückgegeben (duration: maximum: got X, want 15). Wenn Sie bis zu 30 Sekunden benötigen, verwenden Sie das ältere grok-imagine/image-to-video.

Welche Auflösungen und Seitenverhältnisse werden unterstützt? resolution ist 480p oder 720p; aspect_ratio ist auto, 1:1, 16:9, 9:16, 3:2 oder 2:3. 9:16 bei 720p ist die bevorzugte Kombination für vertikale Clips im Shorts/Reels-Stil.

Kann ich mehrere Referenzbilder übergeben? Nein – image_urls dieses Modells akzeptiert genau eine URL. Für Workflows mit mehreren Referenzen verketten Sie Aufgaben oder fügen Sie die Referenzbilder zuerst zu einem einzigen Eingabebild zusammen.

Gibt es einen Seed oder negativen Prompt? Nein. Das Eingabe-Schema lehnt seed, negative_prompt, fps und ähnliche Felder direkt ab. Bewegungsstil, Kamerafahrt und Stimmung werden vollständig über den prompt-String gesteuert.

Was kostet es? Die Abrechnung erfolgt nach Sekunden des generierten Videos: $0.015/Sekunde für 480p, $0.0282/Sekunde für 720p. Ein 6-Sekunden-Clip kostet $0.09 bei 480p und $0.1692 bei 720p. Wenn Sie duration nicht angeben, sind es standardmäßig 8 Sekunden. Weitere Beispiele finden Sie in der Preisaufschlüsselung für Grok Imagine 1.5.

Warum gibt meine Anfrage 401 permission_denied zurück? Entweder ist der API-Schlüssel falsch/widerrufen, oder er hat keinen Zugriff auf das Modell. Überprüfen Sie den Schlüssel im Dashboard und stellen Sie sicher, dass Sie Authorization: Bearer sk-... senden – ein fehlendes Bearer-Präfix erzeugt denselben Fehler.

Wie erfahre ich ohne Polling, dass das Video fertig ist? Fügen Sie beim Erstellen der Aufgabe "callback": {"url": "https://your-endpoint", "when": "final"} hinzu. Sobald die Aufgabe einen Endzustand erreicht, sendet hiapi ein POST an Ihren Endpunkt. Als Fallback fragen Sie GET /v1/tasks/<taskId> wiederholt ab.

Warum funktioniert meine Video-URL nach ein paar Tagen nicht mehr? Die Ausgaben liegen auf temporärem Speicher – jeder Ausgabeeintrag trägt einen expireAt-Zeitstempel. Laden Sie die Datei sofort nach success herunter und stellen Sie sie aus Ihrem eigenen Speicher bereit.