Der MiniMax H3 Prompt-Leitfaden: filmische Kamerabewegungen per API formulieren
Zielmodell:
minimax-h3
Inferenz-Endpunkt:https://api.toapis.com/v1/videos/generations
Verwandt: MiniMax H3 API-Leitfaden · Auswahl zwischen H3 und Turbo · Automatisierte R2V-Pipeline
1. Kurzüberblick und Leistungsübersicht
- Aufgabe: Eine Shot-Liste in wiederholbare MiniMax H3 Prompts übersetzen – Motiv, Aktion, Kamerapfad, Objektiv und Licht – und diese am Generierungs-Endpunkt von ToAPIs senden.
- Prompt-Handwerk: Beginnen Sie mit der Kameraabsicht, dann folgt das Motiv. Kombinieren Sie eine Richtungsangabe mit einer Brennweite (zum Beispiel 35 mm gegenüber 85 mm) und einem Licht-Hinweis.
- Vertrag: Das Basis-Modell
minimax-h3akzeptiert ganzzahlige Clips von 4–15 s. Verwenden Sieratio(16:9,9:16und die weiteren unten gelisteten Seitenverhältnisse). Das ist der Request-Vertrag des Frontends, kein Latenz- oder Qualitätsbenchmark. - Vorsicht bei der Syntax: Tags in eckigen Klammern sind Prompt-Hilfen. Behandeln Sie
[Pan Left]nicht als dokumentierten nativen Befehl, solange die Upstream-Modell Dokumentation das nicht sagt. - Protokoll: REST mit Bearer. Einmal senden, Task-Kennung speichern und den dokumentierten Task-Status-Endpunkt mit begrenzter Frist abfragen.
2. Prompt-Muster für Kamerabewegungen
Ein nützlicher H3-Prompt beschreibt eine Szene und eine Hauptaktion, bevor Kameraanweisung, Objektiv oder Stil hinzukommen. Halten Sie diese Bausteine stabil, wenn Sie ein Modell oder eine Dauer im A/B-Test vergleichen; sonst kann eine geänderte Formulierung einen anderen Take erklären.
Die Tags in der folgenden Tabelle sind Prompt-Hilfen, keine garantierte Befehlsgrammatik. Der Frontend-Vertrag von ToAPIs prüft den Prompt als Text (bis zu 7.000 Unicode-Zeichen). Er belegt nicht, dass Zeichenketten wie [Pan Left] native H3-Befehle sind. Nutzen Sie sie als konsistentes Vokabular in Ihren Vorlagen und prüfen Sie anschließend die Ausgabe.
| Prompt-Hilfe | Visuelle Bahn | Typischer Einsatz |
|---|---|---|
[Pan Left] / [Pan Right] | Horizontale Drehung um eine feste Achse | Landschaftsaufdeckungen, Skyline-Schwenks |
[Tilt Up] / [Tilt Down] | Vertikale Neigung von einer festen Position | Türme, hohe Motive, Himmelsaufdeckungen |
[Dolly In] / [Dolly Out] | Kamera bewegt sich auf das Motiv zu oder davon weg | Emotionale Betonung verdichten |
[Truck Left] / [Truck Right] | Laterale Mitlaufbewegung | Neben einem Fahrzeug oder einer gehenden Person herfahren |
[Crane Shot] / [Pedestal Up] | Vertikale Erhöhung der Kamera | Establishing-Shots aus hohem Winkel |
[Orbit 180] / [Arc Shot] | Halbkreisförmige Bewegung um das Motiv | Produktdrehungen, Helden-Enthüllungen |
[Hitchcock Zoom] | Dolly In bei gleichzeitigem Zoom Out (oder umgekehrt) | Psychologischer Schock, plötzliche Erkenntnis |

Abbildung 1: Betrachten Sie Pan, Tilt, Dolly und Orbit als Bahnen im Prompt-Raum um ein Motiv und senden Sie dann eine einzelne Generierungsanfrage über das ToAPIs Gateway.
Eine kompakte Vorlage, die testbar bleibt:
[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES
Beispiel: [Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur.
Bei Jobs mit Startbild (R2V) beschreibt dieselbe Prompt-Sprache, wie sich die Kamera um das Ankerbild herum oder davon weg bewegen soll. Die Request-Felder stehen im R2V-Pipeline-Tutorial. Frame-Eingaben und Referenzmaterial bleiben sich gegenseitig ausschließende Modi.
Unterstützte ratio-Werte im aktuellen Frontend sind adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 und 9:16. Frame-Eingaben erzwingen adaptive. Senden Sie nicht aspect_ratio; das Vertragsfeld heißt ratio.
3. Produktionsumsetzung: cURL und Python
Schritt 1: Versand per cURL
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur",
"duration": 6,
"ratio": "16:9"
}'
Schritt 2: Prompt-Hilfe und Polling in Python
Passen Sie Feldnamen und Antwortstruktur an die API-Referenz Ihres Kontos an. Der Ausschnitt nutzt den Task-Status-Pfad, der auch in anderen ToAPIs Video-Guides erscheint; bestätigen Sie task_id, status und video_url gegen dieses Schema, bevor Sie ausliefern.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
ENDPOINT = "https://api.toapis.com/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def build_cinematic_prompt(
subject: str,
camera_move: str,
lighting: str,
lens: str = "35mm anamorphic",
) -> str:
return (
f"[{camera_move}] {subject}, {lighting}, "
f"shot on {lens}, photorealistic, cinematic motion blur."
)
def dispatch_camera_shot(prompt: str, duration: int = 6, ratio: str = "16:9") -> str:
payload = {
"model": "minimax-h3",
"prompt": prompt,
"duration": duration,
"ratio": ratio,
}
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 180) -> str:
poll_url = f"https://api.toapis.com/v1/videos/tasks/{task_id}"
interval = 3.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status in {"succeeded", "success"}:
return data["video_url"]
if status in {"failed", "error"}:
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
prompt = build_cinematic_prompt(
subject="Matte black mechanical wristwatch resting on volcanic stone",
camera_move="Orbit 180 + Slow Dolly In",
lighting="Moody low-key rim lighting, subtle steam haze",
lens="85mm macro lens",
)
task_id = dispatch_camera_shot(prompt)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Speichern Sie die Version der Prompt-Vorlage neben dem Task-Datensatz, damit Sie einen Modellwechsel von einer Formulierungsänderung unterscheiden können. Eine clientseitige Zeitüberschreitung beweist nicht, dass der Upstream-Task fehlgeschlagen ist – prüfen Sie den Status, bevor Sie einen zweiten kostenpflichtigen Job senden.
Die Dauer des Basis-H3 ist eine Ganzzahl von 4 bis 15 Sekunden. IDs der Max-Familie beginnen bei 5 Sekunden und haben eigene Auflösungslisten; Turbo akzeptiert kein Referenzmaterial. Prüfen Sie den API-Leitfaden, bevor Sie die ID wechseln.
4. Fehlerbehandlung und Statusmatrix
Die folgenden Kategorien sind Ausgangspunkte für die Diagnose und keine Garantie für exakte ToAPIs Fehlercodes.
| HTTP-Status | Häufige Kategorie | Empfohlene Maßnahme |
|---|---|---|
400 | Ungültiges Feld, nicht unterstützter Wert oder Konflikt im Medienmodus | Prüfen Sie Modell-ID, Dauer, ratio, Auflösung und ob Frame-Eingaben mit Referenzmaterial gemischt sind |
401 | Fehlender oder ungültiger API-Schlüssel | Rotieren Sie den Schlüssel im ToAPIs Dashboard und prüfen Sie den Authorization-Header |
429 | Rate- oder Parallelitätslimit | Weichen Sie mit Jitter zurück; wiederholen Sie nur, wenn es sicher ist |
5xx oder Netzwerk-Zeitüberschreitung | Vorübergehendes Gateway- oder Upstream-Problem | Prüfen Sie den Task-Status vor dem erneuten Senden und nutzen Sie eine begrenzte Wiederholungsstrategie |
5. Preise und FinOps-ROI
- Verwenden Sie keine Stückpreise aus Planungsentwürfen. Preise pro Sekunde, Abrechnungseinheiten und der Umgang mit fehlgeschlagenen Tasks variieren je nach Modell, Route und Konto. Lesen Sie den aktuellen ToAPIs Katalog und das Angebot Ihres Kontos, bevor Sie eine Shot-Liste kalkulieren.
- Offizielle Anbieterverträge enthalten oft Jahresverpflichtungen, Kontingente pro Nutzer und Vorauszahlungsuntergrenzen. Die ToAPIs Abrechnung erfolgt typischerweise als Bezahlung nach Verbrauch – bestätigen Sie die aktiven Bedingungen Ihres Kontos.
- Steuern Sie die Kosten in der Prompt-Ebene: versionierte Vorlage, jeweils nur eine Variable ändern und nach einer clientseitigen Zeitüberschreitung erst den Task-Status prüfen, bevor Sie erneut senden.
- Für den Abwägung zwischen Varianten (Basis-H3, kanonisches Max, Turbo) nutzen Sie den Auswahl-Leitfaden statt eines nicht verifizierten Geschwindigkeits- oder Qualitätswerts.
6. Häufig gestellte Fragen
Siehe den FAQ-Block im Frontmatter. Kurzfassung: Kameraabsicht an den Prompt-Anfang; zusammengesetzte Kameraformulierungen sind Prompt-Text und keine garantierte Grammatik; dieselbe Formulierung gilt im Startbild-Modus; Tags in eckigen Klammern sind keine offiziellen API-Parameter.
7. Aktionscheckliste
- Erstellen Sie einen Schlüssel im ToAPIs Developer Portal.
- Testen Sie den cURL-Ausschnitt kurz mit
minimax-h3,ratio: "16:9"und einer Dauer von 6 Sekunden. - Übernehmen Sie die Prompt-Hilfe, speichern Sie Vorlagenversionen und fragen Sie mit einer Frist von 180 s ab.
- Nächster Schritt: der Request-Vertrag der H3 API und die automatisierte R2V-Pipeline.







