Mehrwinkel-Prompts für die Bild-zu-Video-Generierung mit minimax-h3-max über die hiapi API erstellen

minimax-h3-max verwandelt ein Foto in ein 5–15 Sekunden langes Video, aber der Endpoint bietet überhaupt keine Parameter für „Kamerawinkel“, „Mehrfachansicht“ oder „Aufnahmeanzahl“ – die Parameterreferenz listet als unterstützte Eingabefelder prompt, first_frame_image, last_frame_image, duration, resolution und aspect_ratio. Die Kameraanweisungen müssen in prompt geschrieben werden, das Feld akzeptiert bis zu 7.000 Zeichen.

Ein „Mehrwinkel“-Clip – der von einer weiten Einstellung zum Close-up und dann zur Tracking-Aufnahme wechselt – ist also kein Parameter, den man setzt, sondern ein Prompt, den man schreibt. Dieses Tutorial behandelt die Request-Struktur, Prompt-Muster für mehrere Kamerawinkel innerhalb eines generierten Clips sowie einen produktionsreifen Ablauf darum herum.

Mit diesem Prompt generieren → Wähle 10 Sekunden und 768P. Für Bild-zu-Video füge dein Frame-Bild hinzu und lasse aspect_ratio weg.

Voraussetzungen

Hole einen API-Schlüssel aus deiner hiapi-Konsole. Jeder untenstehende Aufruf authentifiziert sich mit Authorization: Bearer YOUR_API_KEY am gemeinsamen asynchronen Task-Endpoint POST https://api.hiapi.ai/v1/tasks.

Minimalbeispiel: ein Foto, drei Kamerawinkel

first_frame_image verankert Motiv und Szene, damit das Modell konkreten Inhalt hat, von dem es wegschneiden und zu dem es zurückschneiden kann. Der Prompt beschreibt jede Aufnahme als expliziten, nummerierten Schnitt. Dieser Motorrad-Prompt ist ein Codebeispiel ohne mitgeliefertes Rendering-Beispiel.

Ein rotes Vintage-Motorrad steht in der Abenddämmerung auf einer nassen Stadtstraße, Neonreklamen spiegeln sich auf dem Asphalt. Aufnahme 1 – niedriger Weitwinkel: Die Kamera hält eine statische Weitwinkelaufnahme des gesamten Motorrads, leichter Regen fällt. Schnitt zu Aufnahme 2 – Nahaufnahme: Die Kamera fährt dicht an den verchromten Scheinwerfer und das Vorderrad heran und schwenkt langsam nach rechts. Schnitt zu Aufnahme 3 – Draufsicht von oben: Die Kamera blickt von oben senkrecht auf das Motorrad herab und dreht sich langsam. Kein Text und keine Untertitel.

Mit diesem Prompt generieren → Füge dein eigenes öffentlich zugängliches Motorrad-Bild hinzu, wähle 10 Sekunden und 768P und lasse aspect_ratio weg.

import os
import requests
import time

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "minimax-h3-max",
    "input": {
        "prompt": (
            "A red vintage motorcycle parked on a wet city street at dusk, neon signs reflecting on the pavement. "
            "Shot 1 - low wide angle: the camera holds a static wide shot of the full motorcycle, rain lightly falling. "
            "Cut to Shot 2 - close-up: the camera pushes in tight on the chrome headlight and front wheel, tracking slowly right. "
            "Cut to Shot 3 - overhead top-down: the camera looks straight down at the motorcycle from above, slowly rotating. "
            "No text or subtitles."
        ),
        "first_frame_image": "https://your-cdn.example.com/motorcycle-source.jpg",
        "duration": 10,
        "resolution": "768P",
    },
}

# Frame images and aspect_ratio are mutually exclusive.
def response_data(response):
    response.raise_for_status()
    body = response.json()
    if not isinstance(body, dict) or body.get("code") != 200:
        raise ValueError("Expected a JSON object with code=200")
    data = body.get("data")
    if not isinstance(data, dict):
        raise ValueError("Expected data to be an object")
    return data

# Submit once. An uncertain POST response is not a reason to submit again.
try:
    resp = requests.post(
        f"{BASE}/tasks", headers=HEADERS, json=payload, timeout=(10, 60)
    )
    created = response_data(resp)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing data.taskId")
except (requests.RequestException, ValueError) as exc:
    raise RuntimeError(
        "Could not confirm task creation. Check task records before resubmitting."
    ) from exc

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        resp = requests.get(
            f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=(10, 60)
        )
        task = response_data(resp)
    except (requests.RequestException, ValueError) as exc:
        raise RuntimeError(
            f"Query failed; retain taskId={task_id} and resume GET for this ID."
        ) from exc

    state = task.get("status")
    if state == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task.get('error')}")
    if state == "success":
        outputs = task.get("output")
        if not isinstance(outputs, list):
            raise RuntimeError(f"Task {task_id}: missing output array")
        video = next(
            (item for item in outputs
             if isinstance(item, dict) and item.get("type") == "video"
             and isinstance(item.get("url"), str) and item["url"]),
            None,
        )
        if video is None:
            raise RuntimeError(f"Task {task_id}: no video URL in output")
        print(video["url"])
        print("expireAt (Unix seconds):", video.get("expireAt"))
        break
    if state not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Task {task_id}: unexpected status {state!r}")
    time.sleep(min(3, max(0, deadline - time.monotonic())))
else:
    raise TimeoutError(f"Polling timed out; continue GET with taskId={task_id}")

Ersetze first_frame_image durch eine echte, öffentlich zugängliche HTTPS-Bild-URL oder entferne es ganz und generiere dieselbe Mehrwinkel-Sequenz nur aus Text – minimax-h3-max verarbeitet Text-zu-Video und Bild-zu-Video über dasselbe prompt-Feld.

Prompt schreiben: das nummerierte Aufnahme-Muster

Drei Entscheidungen machen deine gewünschte Aufnahmefolge eindeutig:

1. Ein satz, der die Szene etabliert, dann nummerierte Aufnahmen. Beschreibe zuerst einmal Motiv und Szene und liste dann jeden Kamerawinkel als eigenen gekennzeichneten Takt auf: Aufnahme 1 – [Bildkomposition]: [Aktion]. Schnitt zu Aufnahme 2 – [Bildkomposition]: [Aktion]. „Schnitt zu Aufnahme N“ fordert ausdrücklich einen Wechsel des Kamerawinkels.
2. Verwende gängiges filmisches Vokabular. Weitwinkelaufnahme aus niedriger Perspektive, Draufsicht von oben, Nahaufnahme, langsamer Push-in, seitliche Tracking-Aufnahme, Handkamera – diese Begriffe geben die gewünschte Komposition und Bewegung an. Vage Formulierungen wie „noch ein cooler Winkel“ führen zu inkonsistenten Ergebnissen.
3. Plane die Anzahl der Aufnahmen nach der Dauer. duration ist eine ganze Zahl von 5 bis 15 Sekunden. Zwei bis drei Aufnahmen sind realistisch; fünf verschiedene Winkel in einen 5-Sekunden-Clip zu quetschen lässt jede Aufnahme unter einer Sekunde dauern und wirkt oft wie ein Fehler statt wie ein Schnitt.

first_frame_image und last_frame_image sind beide optional und unabhängig voneinander – du kannst eines, beide oder keines setzen. Wenn du eines davon angibst, lasse aspect_ratio weg: Diese Felder schließen sich gegenseitig aus, und die Frame-Bilder bestimmen das Seitenverhältnis der Ausgabe. Beachte außerdem, dass über verschiedene Winkel hinweg keine strikte dreidimensionale oder geometrische Konsistenz garantiert ist – dies ist ein generatives Videomodell, keine Photogrammetrie-Pipeline, also ist selbst mit verankertem ersten Frame eine leichte Drift der Motivdetails zwischen den Schnitten zu erwarten.

Produktionstauglich machen

• Sobald es über Skriptgröße hinausgeht, Callbacks statt Polling bevorzugen. Füge "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} in den Request-Body ein, und hiapi sendet eine POST-Benachrichtigung, wenn der Task einen Endzustand erreicht, statt dass du in einer Schleife GET /v1/tasks/{taskId} abfragst.
• Nach taskId deduplizieren. Sowohl Polling-Antworten als auch Callbacks verwenden dieselbe taskId als Schlüssel – behandle wiederholte Endzustands-Benachrichtigungen derselben ID als idempotent und nicht als mehrere eigenständige Tasks.
• Ausgaben sofort herunterladen. Erfolgreiche Tasks geben data.output[].url für temporären Speicher zurück. Wähle das Ausgabeelement, dessen type gleich video ist, und prüfe dessen expireAt-Unix-Zeitstempel (in Sekunden). Lade es im selben Handler, der den Endzustand verarbeitet, in deinen eigenen Speicher hoch.
• Beide Fehlerformen behandeln. Fehlerhafte Request-Bodys (nicht unterstützte Felder, duration außerhalb des Bereichs, fehlerhafte Bild-URLs) schlagen beim Einreichen schnell fehl und liefern 400 INVALID_REQUEST. Authentifizierungsprobleme liefern 401 mit error.code: "permission_denied". Während der Generierung fehlgeschlagene Tasks melden in der Polling-/Callback-Antwort "status": "fail" – prüfe status, bevor du output vertraust.

Verwandte Lektüre

• minimax-h3-max Modellseite – Live-Preise, Parameter und ein Playground, in dem du Prompts im Browser testen kannst, bevor du sie in Code integrierst.
• minimax-h3-max API-Dokumentation – vollständige Parameterreferenz und Callback-Details.
• H3- und H3-Max-Preise – Auflösungstarife und Budgets für kurze Videos.
• hiapi-Preise – aktuelle Sekundentarife pro Modell.

Häufige Fragen

Gibt es bei minimax-h3-max einen eigenen Mehrwinkel- oder Mehrkamera-Parameter? Nein. Die dokumentierten Eingabefelder sind prompt, first_frame_image, last_frame_image, duration, resolution und aspect_ratio. Beschreibe mehrere Aufnahmen innerhalb von prompt, statt ein Kamerawinkel-Feld hinzuzufügen.

Kann aspect_ratio zusammen mit first_frame_image oder last_frame_image gesetzt werden? Nein. aspect_ratio schließt sich mit jedem Frame-Bild-Feld gegenseitig aus. Das bereitgestellte Bild bestimmt das Ausgabeverhältnis. Lasse aspect_ratio weg, sobald du ein Frame-Bild übergibst.

Wie lang kann ein Mehrwinkel-Clip sein? duration akzeptiert ganzzahlige Sekunden von 5 bis 15. Zwei bis drei verschiedene Kamerawinkel passen recht entspannt in dieses Fenster; darüber hinaus wird jede Aufnahme oft auf einen Bruchteil einer Sekunde zusammengedrängt.

Bleibt das Motiv zwischen den Winkeln perfekt konsistent? Nicht garantiert. minimax-h3-max ist ein generatives Videomodell, daher können Details (genaue Texturen, feine Proportionen) zwischen den Schnitten driften, selbst wenn first_frame_image den Eröffnungsframe verankert. Betrachte es als starke kreative Konsistenz, nicht als pixelgenaue Mehransichts-Rekonstruktion.

Kann ich einen Mehrwinkel-Clip nur aus Text, ohne Quellbild generieren? Ja – lasse first_frame_image und last_frame_image weg und beschreibe Szene und Aufnahmen in prompt. Die reine Textgenerierung verwendet standardmäßig eine horizontale Leinwand. Für ein Hochformat stelle ein hochformatiges Frame-Bild bereit, ohne aspect_ratio zu setzen, oder schneide das gespeicherte Video im Editor zu bzw. fülle es auf.

Wie sieht ein Authentifizierungsfehler aus? HTTP 401 mit einem Antwort-Body wie {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}}. Prüfe den Authorization: Bearer-Header sorgfältig und ob der Schlüssel in der Konsole widerrufen wurde.

Kopiere die Motorrad-Aufnahmensequenz und generiere mit diesem Prompt → Wähle 10 Sekunden und 768P; füge dein Frame-Bild hinzu, um die Eröffnungskomposition zu steuern.