So nutzen Sie die MiniMax H3 Max API für Text-zu-Video und Bild-zu-Video

Dieser Leitfaden zeigt den kürzesten Weg zu einer erfolgreichen Anfrage und ergänzt Validierung, Polling, Callback, Speicherung und Fallback für die Produktion. Bis die eigenen H3-Max-Dokumentationsseiten erscheinen, prüfen Sie exakte Felder im aktuellen Routenvertrag der Modellseite.

Erstellen Sie einen EvoLink API-Schlüssel, prüfen Sie die Live-Schätzung auf der MiniMax H3 Max Modellseite und halten Sie den Leitfaden H3 Max vs H3 bereit, falls Ihr Workflow 2K oder breitere Referenzen benötigen könnte.

Voraussetzungen

Bestätigen Sie vor der ersten Anfrage:

Die richtige H3 Max Modell-ID wählen

Schritt 1: Eine Text-zu-Video-Anfrage senden

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-text-to-video",
    "prompt": "A premium running shoe rotates on a clean studio pedestal while soft daylight moves across the fabric. Slow camera push-in, realistic material detail, no text or logos added.",
    "duration": 5,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

Die wichtigsten T2V-Parameter sind:

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "video"
}

Schritt 2: Eine Bild-zu-Video-Anfrage mit erstem/letztem Frame senden

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-image-to-video",
    "prompt": "The camera makes a slow half-orbit as the box opens and the product rises smoothly. Preserve the packaging shape, colors, and lighting; end exactly on the supplied final composition.",
    "image_start": "https://cdn.example.com/h3-max/start.webp",
    "image_end": "https://cdn.example.com/h3-max/end.webp",
    "duration": 8,
    "quality": "768p"
  }'

Jedes übergebene Bild muss eine direkt erreichbare HTTP(S)-URL verwenden und dem aktuellen Vertrag entsprechen:

• JPG, JPEG, PNG, WEBP, HEIC oder HEIF.
• Maximal 30 MB pro Bild.
• Breite und Höhe zwischen 256 und 5.760 Pixeln.
• Verhältnis von Breite zu Höhe von 0,4 bis 2,5.
• Höchstens ein erster Frame und ein letzter Frame.
• Vollständiger JSON-Body nicht größer als 64 MB; Base64 und mm_file:// werden nicht akzeptiert.

Schritt 3: Den Task-Status abfragen

Fragen Sie den Task mit demselben Bearer-Token ab:

curl --request GET \
  --url "https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123" \
  --header "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://files.example.com/generated-video.mp4"],
  "type": "video"
}

Eine einfache Polling-Richtlinie sollte begrenztes exponentielles Backoff mit Jitter verwenden, statt kontinuierlich abzufragen. Zum Beispiel: bei etwa zwei Sekunden beginnen, auf 10-15 Sekunden anwachsen, bei einer anwendungsdefinierten Frist stoppen und einem späteren Worker erlauben, mit der gespeicherten Task-ID fortzusetzen. Der API-Vertrag bietet für H3 Max keinen Abbruch, daher sollte ein Client-Timeout nicht mit einem Upstream-Abbruch verwechselt werden.

Schritt 4: Einen Callback für die Produktion hinzufügen

{
  "model": "minimax-h3-max-text-to-video",
  "prompt": "A cinematic overhead shot of a city block transitioning from morning to night.",
  "duration": 5,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "callback_url": "https://api.example.com/webhooks/evolink/video"
}

Der aktuelle EvoLink-Vertrag erfordert HTTPS, lehnt private IP-Ziele ab, wartet bis zu 10 Sekunden und wiederholt einen fehlgeschlagenen Callback bis zu dreimal. Ihr Handler sollte:

1. Die Anfrage mit dem von Ihrer Anwendung konfigurierten Verifizierungsmechanismus authentifizieren.
2. Die Task-ID als Idempotenzschlüssel verwenden.
3. Schnell eine 2xx-Antwort zurückgeben.
4. Downloads und aufwendige Nachverarbeitung in eine Queue verlagern.
5. Den Callback-Status bei Bedarf vor der endgültigen Kundenauslieferung mit dem Task-Endpoint abgleichen.

Halten Sie Polling als Wiederherstellungspfad verfügbar. Webhooks können verzögert, durch Netzwerkrichtlinien abgelehnt oder von der Anwendungsinfrastruktur doppelt verarbeitet werden.

Anfragen vor der Übermittlung validieren

Fehler nach Kategorie behandeln

Trennen Sie HTTP-Fehler von asynchronen Task-Fehlern. Ein Erstellungsaufruf kann erfolgreich sein, während die Generierung später fehlschlägt. Protokollieren Sie Task-ID, Route, Eingabeklasse, Dauer, Qualität, finalen Status, Fehlercode, Wiederholungszähler und Fallback-Ergebnis, ohne Secrets oder sensible Quell-URLs zu protokollieren.

Die Produktionsübergabe gestalten

Die Beziehung zwischen Anfrage und Task speichern

Erstellen Sie vor der Übermittlung Ihre eigene Job-ID. Speichern Sie die EvoLink-Task-ID, Modell-ID, normalisierte Parameter, Kunden-/Workspace-ID, Zeitstempel und Auslieferungsstatus. Das ermöglicht Wiederholung, Audit und Support, selbst wenn ein Worker neu startet.

Fertige Ergebnisse zeitnah herunterladen

H3 Max Ergebnis-URLs sind 24 Stunden lang verfügbar. Kopieren Sie akzeptierte Ergebnisse in dauerhaften Speicher und erfassen Sie die Prüfsumme oder den Objektschlüssel. Machen Sie die temporäre Quell-URL nicht zum permanenten Kunden-Asset.

Wiederholungen explizit machen

Senden Sie keine neue Generierung, nur weil eine Polling-Anfrage ein Timeout hatte. Fragen Sie zuerst die gespeicherte Task-ID ab. Erstellen Sie nur dann einen neuen Task, wenn der ursprüngliche einen endgültigen Fehlerzustand erreicht hat und Ihre Wiederholungsrichtlinie einen weiteren abgerechneten Versuch erlaubt.

Inkompatible Jobs vor dem Aufruf routen

Akzeptierte Ausgabe messen

Verfolgen Sie:

• Task-Erfolgsrate und Abschlusslatenz;
• First-Pass-Akzeptanz und Wiederholungsrate;
• Kosten pro akzeptiertem Clip;
• Prompt-, Identitäts- und Keyframe-Treue;
• Moderations- und Ungültige-Anfrage-Rate;
• Fallback-Häufigkeit und Wiederherstellungsrate;
• Download-Abschluss vor Ablauf der URL.

Häufige Integrationsfehler

Go-Live-Checkliste

1. Der API-Schlüssel liegt serverseitig und kann rotiert werden.
2. T2V und I2V verwenden getrennte Validierungsschemata.
3. Dauer, Qualität, Seitenverhältnis und Bildlimits werden lokal durchgesetzt.
4. Die id der Erstellungsantwort wird gespeichert, bevor der Worker beendet wird.
5. Polling verwendet begrenztes Backoff und kann fortgesetzt werden.
6. Die Callback-Verarbeitung ist idempotent und Polling bleibt verfügbar.
7. Fertige MP4-Dateien werden innerhalb von 24 Stunden kopiert.
8. Logs trennen Anfragefehler, Task-Fehler und Ablehnung im Review.
9. Preise stammen von der aktuellen Modellseite oder dem Preisdienst, nicht aus einem fest kodierten Blog-Wert.
10. H3 und ein unabhängiges Fallback sind für inkompatible oder fehlgeschlagene Jobs getestet.

Häufig gestellte Fragen

Welchen Endpoint verwendet MiniMax H3 Max auf EvoLink?

Welche Modell-ID sollte ich verwenden?

Ist die H3 Max API synchron?

Kann ich ein vier Sekunden langes H3 Max Video generieren?

Nein. Die unterstützte Dauer ist eine ganze Zahl von 5 bis 15 Sekunden. MiniMax H3, nicht H3 Max, unterstützt auf EvoLink die untere Grenze von vier Sekunden.

Kann ich nur einen letzten Frame verwenden?

Ja. Das Bild-zu-Video-Modell akzeptiert Anfragen nur mit erstem Frame, nur mit letztem Frame sowie mit erstem und letztem Frame.

Kann ich Base64-Bilder senden?

Akzeptiert Bild-zu-Video ein Seitenverhältnis?

Senden Sie keines. Die Ausgabe folgt dem Verhältnis des übergebenen Frames. Bereiten Sie den Quellframe für das vorgesehene Auslieferungsformat vor.

Wie lange bleiben Ergebnis-URLs gültig?

Vierundzwanzig Stunden. Kopieren Sie fertige MP4-Dateien als Teil des Auslieferungs-Workflows in dauerhaften Speicher.

Wo sollte ich die aktuellen Preise prüfen?

Nutzen Sie den Live-Preisbereich und den Kalkulator auf der H3 Max Produktseite. Vermeiden Sie es, einen Blog-Tarif fest in die Produktionsbudgetierung zu kodieren.

API-Referenzen und Prüfumfang

• EvoLink MiniMax H3 Max Modellseite und aktueller Routenvertrag
• EvoLink-Referenz zum asynchronen Task-Status
• Offizielle MiniMax Video Generation V2-Dokumentation