MiniMax H3 API: PoYo-Integration, Preise und Prompts

Mit der MiniMax H3 API von PoYo können Sie aus Text, Anfangs- und Endbildern oder Referenzmedien 5–15 Sekunden lange 2K-Videos erzeugen. Ohne Referenzmedien kostet ein 5-Sekunden-Video voraussichtlich 105 Credits ($0.525).

Dieser Leitfaden beginnt mit Ihrer ersten Anfrage. Danach folgen Preise, Eingabemodi, Python- und Node.js-Beispiele sowie Prompts für verschiedene Szenen. Alle hier genannten Endpunkte und Preise gelten für PoYo.

Schnellstart: Aufgabe übermitteln und Video abrufen

1. Eine Aufgabe für ein 5-Sekunden-Video übermitteln

Holen Sie sich einen API-Schlüssel in der PoYo-Konsole, ersetzen Sie unten YOUR_POYO_API_KEY und führen Sie den Befehl im Terminal oder auf Ihrem Server aus. Bewahren Sie den Schlüssel serverseitig auf; er gehört weder in Browsercode noch in öffentliche Repositories.

In PoYo-Anfragen lautet der model-Wert für MiniMax H3 hailuo-03. Das folgende Beispiel übermittelt eine kostenpflichtige Generierungsaufgabe.

export POYO_API_KEY="YOUR_POYO_API_KEY"

curl --fail-with-body --max-time 30 \
  --request POST 'https://api.poyo.ai/api/generate/submit' \
  --header "Authorization: Bearer ${POYO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "hailuo-03",
    "input": {
      "prompt": "A golden retriever walks through a sunlit autumn park. One slow tracking shot, natural movement, warm afternoon light.",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9"
    }
  }'

Lesen Sie nach erfolgreicher Übermittlung die Aufgaben-ID aus data.task_id. Dieses Beispiel zeigt die Antwortstruktur mit einer Platzhalter-ID:

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}

2. Das Aufgabenergebnis abfragen

Setzen Sie TASK_ID auf die zurückgegebene Aufgaben-ID und verwenden Sie denselben API-Schlüssel:

TASK_ID="YOUR_TASK_ID"

curl --fail-with-body --max-time 30 \
  --request GET "https://api.poyo.ai/api/generate/status/${TASK_ID}" \
  --header "Authorization: Bearer ${POYO_API_KEY}"

Eine erfolgreiche Übermittlung bedeutet, dass die Aufgabe angenommen wurde; auf die Fertigstellung des Videos müssen Sie noch warten. Das Feld data.status in der Abfrageantwort kann vier Werte annehmen:

Hier ein Beispiel für eine abgeschlossene Aufgabe. URL und Zeitstempel dienen nur zur Veranschaulichung:

{
  "code": 200,
  "data": {
    "task_id": "YOUR_TASK_ID",
    "status": "finished",
    "credits_amount": 105,
    "files": [
      {
        "file_url": "https://example.com/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-09-22T08:30:00",
    "progress": 100,
    "error_message": null
  }
}

Felddefinitionen und Antworten für weitere Zustände finden Sie in der PoYo-Dokumentation zur Aufgabenabfrage. Falls eine Abfrage vorübergehend fehlschlägt oder Ihre Wartefrist endet, behalten Sie die Aufgaben-ID und fragen später erneut ab. Übermitteln Sie deshalb nicht automatisch eine weitere kostenpflichtige Generierung.

So wird MiniMax H3 bei PoYo abgerechnet

Die folgenden Preise wurden am 21. September 2026 geprüft. Alle Beträge sind in USD angegeben, mit 1 Credit = $0.005. Prüfen Sie vor größeren Generierungsläufen die aktuellen Preise auf der Modellseite.

Geschätzte Credits = 21 × (Ausgabesekunden + abrechenbare Referenzvideosekunden) + 6.4 × Anzahl der Referenzbilder über 5. Bei höchstens 5 Referenzbildern betragen die zusätzlichen Bildkosten 0. Multiplizieren Sie die geschätzten Credits mit $0.005, um den USD-Betrag zu erhalten. Bei Referenzvideos mit Sekundenbruchteilen wird die vom Server ermittelte Dauer abgerechnet.

Das letzte Beispiel wird mit 21 × (10 + 5) + 6.4 × (7 − 5) berechnet. Die Kosten gelten pro Generierung. Benötigt eine Einstellung mehrere Versuche, muss Ihr Budget jede Generierung berücksichtigen.

Eingabemodus und Referenzmedien wählen

Die übermittelten Medienfelder bestimmen den Eingabemodus. Das Schnellstartbeispiel oben verwendet Text-zu-Video. Ergänzen Sie die passenden Felder, wenn Sie Anfangs- und Endbilder vorgeben oder Referenzmedien verwenden möchten.

Kombinieren Sie image_urls nicht mit einem Feld reference_*_urls. Alle Medien-URLs müssen öffentlich zugänglich und direkt herunterladbar sein.

Parameter- und Medienlimits

Die folgenden Grenzen stammen aus der PoYo-API-Dokumentation für MiniMax H3:

• prompt ist erforderlich und erlaubt bis zu 2000 Zeichen.
• duration ist eine ganze Zahl von 5–15 Sekunden, standardmäßig 5; resolution unterstützt nur 2K.
• Text-zu-Video unterstützt 21:9, 16:9, 4:3, 1:1, 3:4 und 9:16, standardmäßig 16:9. Der Referenzmodus unterstützt zusätzlich adaptive und verwendet diesen Wert standardmäßig.
• Zulässig sind bis zu 9 Referenzbilder, 3 Referenzvideos und 3 Referenzaudioclips. Jeder Video- oder Audioclip muss 2–15 Sekunden lang sein; die Gesamtdauer der Videos und die Gesamtdauer der Audioclips dürfen jeweils 15 Sekunden nicht überschreiten.

Anfragebeispiel mit Anfangs- und Endbild

Verwenden Sie das folgende JSON als Body von POST /api/generate/submit. Die Medien-URLs unter example.com sind Platzhalter. Ersetzen Sie sie vor dem Senden durch eigene herunterladbare Medien. Soll nur ein Anfangsbild verwendet werden, entfernen Sie die zweite URL aus dem Array.

{
  "model": "hailuo-03",
  "input": {
    "prompt": "The camera slowly moves through the temple doorway, starting at the entrance and ending inside the hall. Dust floats in the sunlight.",
    "duration": 6,
    "resolution": "2K",
    "image_urls": [
      "https://example.com/assets/temple-entrance.jpg",
      "https://example.com/assets/temple-interior.jpg"
    ]
  }
}

Anfragebeispiel mit Bild- und Videoreferenz

Verwenden Sie Image 1 für das Aussehen der Figur und Video 1 für die gewünschte Kamerabewegung. Gemeint ist jeweils das erste Element im Bild- beziehungsweise Videoarray. Ersetzen Sie vor dem Senden die Medien-URLs und prüfen Sie die Dauer des Referenzvideos.

{
  "model": "hailuo-03",
  "input": {
    "prompt": "Use Image 1 for the character appearance and outfit. The character turns and walks toward the window. Use Video 1 as the camera movement reference.",
    "duration": 8,
    "resolution": "2K",
    "aspect_ratio": "adaptive",
    "reference_image_urls": [
      "https://example.com/assets/character.png"
    ],
    "reference_video_urls": [
      "https://example.com/assets/camera-motion.mp4"
    ]
  }
}

Integrationsbeispiele für Python und Node.js

Die Beispiele trennen Übermittlung und Abfrage in zwei Funktionen: Zuerst erhalten und speichern Sie die Aufgaben-ID, anschließend warten Sie auf das Ergebnis. Wird die Abfrage unterbrochen, können Sie sie mit der ursprünglichen ID fortsetzen, ohne erneut zu generieren. Nur Statusabfragen werden bei Verbindungsfehlern, Zeitüberschreitungen, HTTP 429 und ausgewählten 5xx-Fehlern wiederholt; Übermittlungen werden nicht automatisch wiederholt.

Beide Implementierungen warten zwischen Abfragen 10 Sekunden, führen höchstens 60 Abfragen durch und verwenden ein Timeout von 30 Sekunden pro Anfrage. Die gesamte Wartezeit umfasst somit auch die Anfragedauer. Dies sind Anwendungseinstellungen der Beispiele, keine Zusage zur Generierungsdauer. Passen Sie Intervalle und Wiederholungsregeln an Ihre Anwendung an.

Python: Aufgabe übermitteln und Ergebnis abfragen

Installieren Sie die Abhängigkeit mit python -m pip install requests und setzen Sie die oben beschriebene Umgebungsvariable POYO_API_KEY. Das synchrone Python-Skript fragt eine asynchrone Generierungsaufgabe ab.

import os
import time
import requests

BASE_URL = "https://api.poyo.ai"
API_KEY = os.environ["POYO_API_KEY"]
if not API_KEY.strip():
    raise ValueError("Set POYO_API_KEY")
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
RETRYABLE_HTTP = {429, 500, 502, 503, 504}


def response_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200 or not isinstance(body.get("data"), dict):
        raise RuntimeError(f"Unexpected API response: {body}")
    return body["data"]


def submit_h3(prompt, duration=5):
    response = requests.post(
        f"{BASE_URL}/api/generate/submit",
        headers=HEADERS,
        json={"model": "hailuo-03", "input": {
            "prompt": prompt, "duration": duration,
            "resolution": "2K", "aspect_ratio": "16:9",
        }},
        timeout=30,
    )
    task_id = response_data(response).get("task_id")
    if not isinstance(task_id, str) or not task_id:
        raise RuntimeError("Submission response is missing a task ID; check records instead of resubmitting automatically")
    return task_id


def wait_for_h3(task_id, max_polls=60):
    for _ in range(max_polls):
        time.sleep(10)
        try:
            response = requests.get(
                f"{BASE_URL}/api/generate/status/{task_id}",
                headers=HEADERS, timeout=30,
            )
        except (requests.Timeout, requests.ConnectionError):
            continue
        if response.status_code in RETRYABLE_HTTP:
            continue
        task = response_data(response)
        status = task.get("status")
        if status == "finished":
            for item in task.get("files") or []:
                if item.get("file_type") == "video" and item.get("file_url"):
                    return item["file_url"]
            raise RuntimeError(f"Task {task_id} finished, but the response has no video URL")
        if status == "failed":
            raise RuntimeError(f"Task {task_id} failed: {task.get('error_message')}")
        if status not in {"not_started", "running"}:
            raise RuntimeError(f"Task {task_id} returned an unknown status: {status}")
    raise TimeoutError(f"Query limit reached; keep the task ID and query again later: {task_id}")


if __name__ == "__main__":
    task_id = submit_h3("A golden retriever walks through a sunlit autumn park.")
    # In your application, save task_id to the database here before polling.
    print(f"Task ID: {task_id}", flush=True)
    print(wait_for_h3(task_id))

Rufen Sie zum Fortsetzen direkt wait_for_h3(saved_task_id) auf. HTTP-Fehler wie 401 und 403, API-Fehler oder unerwartete Antworten beenden das Polling. Beheben Sie zunächst die Ursache.

Node.js: integriertes fetch verwenden

Das folgende JavaScript nutzt das integrierte fetch von Node.js 20 oder neuer. Eine zusätzliche HTTP-Client-Abhängigkeit ist nicht nötig. Speichern Sie es als .mjs-Datei und führen Sie es auf dem Server aus.

const BASE_URL = 'https://api.poyo.ai';
const apiKey = process.env.POYO_API_KEY;
if (!apiKey?.trim()) throw new Error('Set POYO_API_KEY');
const headers = {
  Authorization: `Bearer ${apiKey}`,
  'Content-Type': 'application/json',
};
const retryableHttp = new Set([429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function responseData(response) {
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const body = await response.json();
  if (body.code !== 200 || !body.data || typeof body.data !== 'object') {
    throw new Error(`Unexpected API response: ${JSON.stringify(body)}`);
  }
  return body.data;
}

export async function submitH3(prompt, duration = 5) {
  const response = await fetch(`${BASE_URL}/api/generate/submit`, {
    method: 'POST', headers,
    body: JSON.stringify({
      model: 'hailuo-03',
      input: { prompt, duration, resolution: '2K', aspect_ratio: '16:9' },
    }),
    signal: AbortSignal.timeout(30_000),
  });
  const data = await responseData(response);
  if (typeof data.task_id !== 'string' || !data.task_id) {
    throw new Error('Submission response is missing a task ID; check records instead of resubmitting automatically');
  }
  return data.task_id;
}

export async function waitForH3(taskId, maxPolls = 60) {
  for (let attempt = 0; attempt < maxPolls; attempt++) {
    await sleep(10_000);
    let response;
    try {
      response = await fetch(
        `${BASE_URL}/api/generate/status/${encodeURIComponent(taskId)}`,
        { headers, signal: AbortSignal.timeout(30_000) },
      );
    } catch (error) {
      if (error instanceof Error &&
          (error.name === 'TimeoutError' || error.name === 'TypeError')) {
        continue;
      }
      throw error;
    }
    if (retryableHttp.has(response.status)) {
      await response.body?.cancel();
      continue;
    }
    const task = await responseData(response);
    if (task.status === 'finished') {
      const video = task.files?.find((file) => file.file_type === 'video' && file.file_url);
      if (!video) throw new Error(`Task ${taskId} finished, but the response has no video URL`);
      return video.file_url;
    }
    if (task.status === 'failed') {
      throw new Error(`Task ${taskId} failed: ${task.error_message || 'No error details provided'}`);
    }
    if (!['not_started', 'running'].includes(task.status)) {
      throw new Error(`Task ${taskId} returned an unknown status: ${task.status}`);
    }
  }
  throw new Error(`Query limit reached; keep the task ID and query again later: ${taskId}`);
}

const taskId = await submitH3('A golden retriever walks through a sunlit autumn park.');
// In your application, save taskId to the database here before polling.
console.log(`Task ID: ${taskId}`);
console.log(await waitForH3(taskId));

Ersetzen Sie zum Fortsetzen die Übermittlungs- und Abfrageaufrufe am Dateiende durch waitForH3(savedTaskId). Das Polling-Beispiel eignet sich für Skripte oder Hintergrundaufgaben. Geben Sie in einer Webanwendung die Aufgaben-ID an das Frontend zurück und verfolgen Sie die Generierung im Hintergrund, statt eine Seitenanfrage so lange warten zu lassen.

Ergebnisse per Webhook empfangen

Sie können callback_url auch auf oberster Ebene der Übermittlungsanfrage neben model und input angeben, etwa https://your-domain.com/webhooks/poyo. PoYo sendet das Ergebnis bei Erfolg oder Fehlschlag der Aufgabe an diese URL.

Der Empfänger sollte die Aufgaben-ID mit lokalen Datensätzen abgleichen und doppelte Benachrichtigungen anhand der ID behandeln, damit nachgelagerte Vorgänge nicht mehrfach ausgeführt werden. Aufwendige Arbeiten wie Videodownload oder Transcodierung können im Hintergrund laufen. Während der Callback-Integration können Sie Ergebnisse weiterhin per Statusabfrage überprüfen.

Prompts und Szenenbeispiele

Beschreiben Sie zuerst Motiv und Handlung, danach Kamerabewegung, Umgebung, Licht und Ton. Benennen Sie bei Referenzmedien die Rolle von Image 1, Video 1 oder Audio 1, damit eine einzelne Referenz keine widersprüchlichen Anforderungen erfüllen muss.

Die vier englischen Beispiele veranschaulichen das Schreiben von Prompts; getestete Generierungsergebnisse sind nicht beigefügt. Englische Begriffe erleichtern die Wiederverwendung, bedeuten aber nicht, dass Englisch grundsätzlich besser funktioniert als Chinesisch. Zeitangaben und Vorgaben zum Erhalt des Aussehens beschreiben Ziele. Prüfen Sie das tatsächliche Ergebnis.

Produktwerbung: 8 Sekunden, Referenzbildmodus

Setzen Sie das Produktbild an die erste Stelle in input.reference_image_urls, verwenden Sie duration: 8 und aspect_ratio: "16:9" und tragen Sie den folgenden Text als prompt ein. Nutzen Sie die oben gezeigte Struktur für den Referenzmodus. Entfernen Sie reference_video_urls, wenn kein Referenzvideo benötigt wird.

Use Image 1 as the product reference. A clear glass perfume bottle rests on
wet black stone after rain. Preserve the bottle shape, cap, and label placement.
One continuous 8-second shot: begin close to the water droplets, then slowly
pull back to reveal the bottle in warm rim light. Realistic glass reflections,
no added text. Soft rain ambience.

Prüfen Sie zunächst mit einer einfachen Einstellung, ob Flakon und Etikett konsistent bleiben. Versuchen Sie danach komplexere kreisende Kamerabewegungen.

Figurendialog: 8 Sekunden, Referenzbildmodus

Setzen Sie das Figurenbild an die erste Stelle in input.reference_image_urls und verwenden Sie duration: 8 sowie aspect_ratio: "16:9". Ein kurzer Dialogsatz erleichtert die Kontrolle von Lippensynchronität, Sprechtempo und Aussehen.

Use Image 1 as the character reference. An 8-second medium close-up of a pastry
chef in a quiet kitchen at sunrise. She looks into the camera and says:
"Every detail matters in baking." Natural breathing, a subtle smile,
soft window light. Preserve her face, hairstyle, and apron. A steady camera,
clear speech, quiet room tone.

Vertikale Spielewerbung: 10 Sekunden, Text-zu-Video

Setzen Sie duration: 10 und aspect_ratio: "9:16". Zeitabschnitte geben die gewünschte Reihenfolge der Handlungen an. Wirkt die Szene überladen, reduzieren Sie zunächst die Zahl der Handlungen und Figuren.

A 10-second vertical fantasy game trailer.
0-3s: An armored knight walks through a ruined stone gate.
3-6s: One creature charges; the knight blocks once with a shield.
6-9s: The camera rises to reveal the fortress walls.
9-10s: Hold the final composition.
Readable action, consistent armor, wind and impact sounds, no UI or captions.

Durchgehende Kamerafahrt: 10 Sekunden, Text-zu-Video

Setzen Sie duration: 10 und aspect_ratio: "16:9". Bauen Sie die Einstellung um ein Motiv und einen Bewegungsweg auf. Prüfen Sie anschließend auf Schnitte, Veränderungen des Motivs und unterbrochene Bewegungsabläufe.

One unbroken 10-second tracking shot follows a cyclist through a night market.
Begin behind the rear wheel, rise to shoulder height, then move alongside
without cutting. Wet pavement reflections, a clear path between stalls,
consistent bicycle geometry, no speed ramps or scene transitions.
Natural street ambience and bicycle tires rolling on wet pavement.

Häufige Fragen und Fehlerbehebung

Kann ich direkt das Anfrageformat der MiniMax-eigenen API verwenden?

Diese Beispiele nutzen PoYos POST /api/generate/submit und GET /api/generate/status/{task_id}. Endpunkte, Modellkennungen und Feldstrukturen können sich je nach Plattform unterscheiden. Maßgeblich ist die Dokumentation der verwendeten Plattform.

Sollte ich eine Aufgabe erneut übermitteln, wenn sie in not_started bleibt?

not_started bedeutet, dass die Aufgabe auf Verarbeitung wartet; der Status ist für sich genommen kein Fehler. Behalten Sie die ID und fragen Sie weiter ab. Ist die Wartefrist Ihrer Anwendung erreicht, speichern Sie die Aufgabe und prüfen sie später. Wenden Sie sich bei Bedarf mit der Aufgaben-ID an den Support.

Was tun, wenn die Übermittlung vor Erhalt einer Aufgaben-ID abbricht?

Ein Timeout beweist nicht, dass der Server die Aufgabe nicht angenommen hat. Prüfen Sie zunächst die Aufgabenaufzeichnungen. Kontaktieren Sie bei Bedarf den Support mit Angaben wie dem Übermittlungszeitpunkt. Für die Statusabfrage benötigen Sie eine Aufgaben-ID. Eine fehlgeschlagene Abfrage sollte nicht durch erneute Übermittlung ersetzt werden.

Kann ich Bilder, Video und Audio als Referenzen kombinieren?

Ja, im Referenzmodus innerhalb der oben genannten Mengen- und Dauergrenzen. Referenzaudio erfordert ein Referenzbild oder -video. Diese Felder dürfen nicht mit image_urls des Anfangs-/Endbildmodus kombiniert werden.

Was kostet ein 10-Sekunden-Video?

Zu den hier genannten Preisen kostet es ohne Referenzmedien 10 × 21 = 210 Credits, also $1.05. Referenzvideos und Referenzbilder über die ersten 5 hinaus erhöhen die Kosten.

Prüfen Sie vor der Integration, ob Medien-URLs direkte Downloads erlauben, speichern Sie Aufgaben-IDs und setzen Sie geeignete Limits für Generierungen und parallele Aufgaben pro Nutzer. Kontrollieren Sie vor der Veröffentlichung, ob Figuren, Produktform, Text, Bewegung und Ton zum vorgesehenen Einsatz passen.

Probieren Sie die Generierung auf der MiniMax H3 Modellseite aus oder beginnen Sie über die API-Schlüsselseite mit der Integration. Weitere Informationen finden Sie im MiniMax H3 Review und im Vergleich von MiniMax H3 und Seedance 2.5.