> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# MiniMax H3 Videoerzeugungs-API-Integrationsleitfaden
> Minimax API guide - Ace Data Cloud
Dieser Artikel stellt die Integration und Nutzung der MiniMax H3 Videoerzeugungs-API vor. Diese Schnittstelle unterstützt Text-zu-Video, Steuerung über Anfangs- und Endframes sowie multimodale referenzbasierte Videoerzeugung und verwendet die einheitliche multimodale V2-`content`-Struktur zur Erstellung von Aufgaben.
## Antragsprozess
Um die MiniMax H3 Videoerzeugungs-API zu verwenden, rufen Sie zunächst die [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) auf, um Ihren API-Token zu erhalten, und bewahren Sie ihn zur späteren Verwendung auf.
Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück.
**Ein API-Token kann alle Dienste der Plattform aufrufen; es ist nicht erforderlich, ihn für jeden Dienst einzeln zu beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, das Sie kostenlos ausprobieren können; bei unzureichendem Kontingent können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufladen.
> 📘 Vollständige Dokumentation: [MiniMax H3 Videoerzeugungs-API →](https://platform.acedata.cloud/documents/minimax-videos-integration)
Es wird empfohlen, den Token als Umgebungsvariable zu speichern und ihn nicht in den Quellcode zu schreiben oder in das Versionskontrollsystem einzuchecken:
```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```
## Schnittstellenübersicht
* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/videos`
* **Authentifizierungsmethode**：`authorization: Bearer {token}` im HTTP-Header übermitteln
* **Request-Header**：
* `accept: application/json`
* `content-type: application/json`
* **Modell（model）**：`MiniMax-H3`
* **Eingabestruktur**：Text, Bilder, Videos und Audio werden einheitlich über `content` übergeben
* **Ausgabemodus**：Standardmäßig wird synchron auf den Abschluss der Erzeugung gewartet und die vollständige `task` zurückgegeben; bei Übergabe von `async: true` oder `callback_url` werden sofort `task_id` und `trace_id` zurückgegeben
* **Ergebnisabfrage**：Status und fertiges Video über die [MiniMax H3 Aufgabenabfrage-API](https://platform.acedata.cloud/documents/minimax-tasks-integration) abrufen
* **Asynchroner Callback**：Optional, das endgültige Aufgabenergebnis über `callback_url` empfangen
Sie müssen kein `action` übergeben, um den Erzeugungsmodus auszuwählen. Die Schnittstelle bestimmt den Verwendungszweck automatisch anhand der Materialtypen und `role` in `content`.
## Für welche Szenarien geeignet
| Szenario | Eingabekombination | Häufige Verwendung |
| - | - | - |
| Text-zu-Video | Text | Werbekreatives, Storyboard-Vorschau, Kurzvideos, atmosphärische Aufnahmen |
| Bild-zu-Video mit Anfangsframe | Text + Anfangsframe-Bild | Produktbilder, Poster, Personenfotos oder Illustrationen natürlich in Bewegung versetzen |
| Endframe / Video mit Anfangs- und Endframe | Text + Endframe oder Text + Anfangsframe + Endframe | Anfang und Ende, Übergänge, Wachstumsveränderungen und Vorher-Nachher-Vergleiche steuern |
| Multimodale referenzbasierte Videoerzeugung | Text + Referenzbild / -video / -audio | Charaktere und Produkte konsistent halten, Bewegungen, Kameraführung, Klangfarbe oder Schnittrhythmus nachbilden |
## Aufrufablauf
Wenn `async` standardmäßig nicht übergeben wird, wartet `/minimax/videos` auf den Abschluss der Erzeugung und gibt direkt die vollständige `task` zurück. Wenn die Verbindung sofort freigegeben werden soll, übergeben Sie `async: true` oder `callback_url`:
1. Speichern Sie `task_id` und `trace_id` aus der sofortigen Antwort.
2. Wenn kein Callback konfiguriert ist, rufen Sie etwa alle 10 Sekunden einmal `/minimax/tasks` zur Abfrage auf.
3. Wenn `task.status` zu `succeeded` wird, rufen Sie das Video über `task.content.url` ab.
4. Wenn der Status `failed` oder `cancelled` lautet, beenden Sie das Polling und lesen Sie `task.error`.
## Anfrageparameter der obersten Ebene
| Parameter | Typ | Erforderlich | Standardwert | Beschreibung |
| - | - | - | - | - |
| `model` | string | Ja | - | Fest auf `MiniMax-H3` gesetzt |
| `content` | object\[] | Ja | - | Multimodales Inhaltsarray, muss einen nicht leeren `text`-Eintrag enthalten |
| `resolution` | string | Ja | - | `768P` oder `2K` |
| `duration` | integer | Ja | - | Erzeugungsdauer, ganze Zahl von 4–15 Sekunden |
| `ratio` | string | Bedingt erforderlich | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `async` | boolean | Nein | `false` | Bei `true` wird sofort eine Aufgabenkennung zurückgegeben; Ergebnis über die Aufgabenschnittstelle abrufen |
| `callback_url` | string | Nein | - | Öffentlich erreichbare Callback-URL zum Empfang des endgültigen Aufgabenergebnisses; aktiviert nach Angabe automatisch den asynchronen Modus |
Die Regeln für `ratio` hängen vom Workflow ab:
* **Text-zu-Video**：Erforderlich und darf nicht `adaptive` sein.
* **Video mit Anfangsframe, Endframe oder Anfangs- und Endframe**：Das Seitenverhältnis wird durch das Eingabebild bestimmt; es wird empfohlen, es wegzulassen oder `adaptive` zu übergeben.
* **Multimodale referenzbasierte Videoerzeugung**：Kann weggelassen werden, Standard ist `adaptive`; alternativ kann ein festes Verhältnis explizit angegeben werden.
Die Schnittstelle akzeptiert keine alten oder kompatiblen Felder wie `prompt`, `image_urls`, `audio_urls`, `messages` und `first_frame_image`. Wenn Fehler bei solchen Parametern auftreten, löschen Sie die alten Felder und migrieren Sie zu `content`; ändern Sie beispielsweise `"prompt": "一只猫挥手"` zu `"content": [{"type": "text", "text": "一只猫挥手"}]`. Senden Sie nicht gleichzeitig das neue und das alte Format.
## Parameter der content-Inhaltselemente
Jedes Inhaltselement muss `type` haben; die übrigen Felder werden durch den Typ bestimmt:
| `type` | Datenfeld | `role` | Beschreibung |
| - | - | - | - |
| `text` | `text` | Nicht übergeben | Jede Anfrage muss ein nicht leeres Textelement enthalten, maximal 7000 Zeichen |
| `image_url` | `image_url.url` | `first_frame` | Anfangsframe-Bild; wenn nur ein Bild vorhanden ist und `role` weggelassen wird, wird es ebenfalls als Anfangsframe behandelt |
| `image_url` | `image_url.url` | `last_frame` | Endframe-Bild; kann allein verwendet oder mit `first_frame` kombiniert werden, um Start- und Endpunkt zu steuern |
| `image_url` | `image_url.url` | `reference_image` | Referenz für Motiv, Charakter, Produkt, Kleidung, Szene oder Stil |
| `video_url` | `video_url.url` | `reference_video` | Referenz für Bewegung, Kameraführung, Darstellung oder Schnittstruktur |
| `audio_url` | `audio_url.url` | `reference_audio` | Referenz für Klangfarbe, Dialog, Musik oder Rhythmus |
Medienadressen unterstützen drei Formen:
* Öffentlich zugängliche HTTPS-URL, empfohlen für große Dateien.
* `mm_file://{file_id}`, verweist auf bereits hochgeladene oder vorhandene Ergebnisdateien.
* Base64-Data-URI des entsprechenden Medientyps. Base64 erhöht die Größe um etwa ein Drittel; stellen Sie sicher, dass der gesamte Anfragekörper 64 MB nicht überschreitet.
## Materialvorgaben und Mengenbeschränkungen
| Material | Format | Limit pro Datei | Abmessungen / Dauer | Mengenbegrenzung |
| - | - | - | - | - |
| Bilder | JPG、JPEG、PNG、WEBP、HEIC、HEIF | Nicht mehr als 30 MB | Breite und Höhe jeweils 256–5760 px；Seitenverhältnis 0,4–2,5 | Erstes Bild maximal 1、letztes Bild maximal 1、Referenzbilder maximal 9 |
| Videos | MP4、MOV；H.264/AVC oder H.265/HEVC；Audiospur AAC oder MP3 | Nicht mehr als 50 MB | Jede Sequenz 2–15 Sekunden, insgesamt nicht mehr als 15 Sekunden；Breite und Höhe jeweils 256–5760 px；Seitenverhältnis 0,4–2,5；23,976–60 fps | Maximal 3 Referenzvideos |
| Audio | WAV、MP3 | Nicht mehr als 15 MB | Jede Sequenz 2–15 Sekunden, insgesamt nicht mehr als 15 Sekunden | Maximal 3 Referenzaudios |
Bilder, Videos und Audios in multimodalen Referenzszenarien umfassen zusammen maximal 12 Dateien. Das Szenario mit erstem und letztem Bild und das Szenario mit Referenzmaterial schließen sich gegenseitig aus: Sobald `reference_image`、`reference_video` oder `reference_audio` verwendet wird, dürfen `first_frame` oder `last_frame` nicht mehr verwendet werden, und umgekehrt.
## Präsentation produktionsreifer Fähigkeiten
Das Folgende sind keine Konzeptbilder oder Platzhaltermaterialien, sondern echte Referenzeingaben und tatsächliche Videoausgaben offizieller produktionsreifer MiniMax-H3-Fähigkeitsbeispiele. Die drei Fallbeispiele decken jeweils Marken-Kurzfilme, Realpersonen-Erzählungen und Fashion-E-Commerce ab und eignen sich zur Bewertung der wichtigsten Fähigkeiten des Modells in der kommerziellen Produktion.
| Fähigkeit | Wichtige Beobachtung |
| - | - |
| Konsistenz von Personen und Gesichtern | Ob Gesichtszüge, Frisur, Make-up und die Ausstrahlung der Person nach Wechseln zwischen mehreren Einstellungen stabil bleiben |
| Gesichtsausdruck | Blick, Mikroausdrücke, emotionale Spannung und natürliche Kopfbewegungen in Nahaufnahmen |
| Beibehaltung der Produktstruktur | Konturen, Materialien, Tragebeziehung und Spiegelungen von Produkten wie Brillen und Handtaschen |
| Umsetzung der Markenvisuals | Ob Szenenatmosphäre, Filmkorn, Farben, Logo und Schnittrhythmus einheitlich sind |
| Filmisches Erzählen | Ob Einstellungswechsel, Personenführung, Kamerabewegung, Rhythmus und Ton eine vollständige Sequenz bilden können |
Die „Gesichtsfähigkeiten“ hier beziehen sich auf die Konsistenz des Erscheinungsbilds von Personen, Gesichtsdetails und die Steuerung der Darstellung bei der Videogenerierung, nicht auf Identitätserkennung, Gesichtsabgleich oder Face-Swapping-Schnittstellen.
### Hochwertiger Marken-Kurzfilm: Einheit von Personen, Produkten und Marken-Assets
**Produktionsziel：** 16:9-High-Fashion-Markenfilm. Mit einer Wüstenstraße und einem Retroauto wird eine kühle Atmosphäre geschaffen, während das Erscheinungsbild der weiblichen Hauptfigur und die Struktur der schwarzen Handtasche beibehalten und das Markenlogo natürlich ins Ende integriert werden. Dieses Beispiel prüft vor allem die Personen-Konsistenz über mehrere Einstellungen hinweg, Produktbeibehaltung, filmische Qualität und die Fähigkeit zum Markenabschluss.
| Referenz für Atmosphäre und Szene | Personenreferenz |
| - | - |
| 
| 
|
| Handtaschen-Produktreferenz | Markenlogo-Referenz |
| - | - |
| 
| 
|
[Marken-Kurzfilm direkt öffnen oder herunterladen](https://cdn.acedata.cloud/uploads/6845b11d-1a58-4478-afd8-29e7e117772a)
Entsprechende Organisationsweise von `content`：
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒、16:9 高级时装品牌片。荒漠公路旁停着复古汽车，女主从后备箱取出黑色手袋，与男主短暂对视后独自离开。保持人物、手袋与品牌视觉一致；冷峻高级，电影颗粒，剪辑利落，结尾自然呈现品牌 Logo。"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/6e65f865-f1c2-4f80-8b51-9a98d4d930b1" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/88d89cc3-e6cb-42b4-ab4c-1bbbf6c9f7c8" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/e91f7fff-f8e3-4da5-b882-87edbc3c9473" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/b68dac43-fb14-42b5-bf8b-fd4d65506520" },
"role": "reference_image"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
```
### Vertikales Realpersonen-Kurzdrama: Gesichtskonsistenz und emotionale Darstellung
**Produktionsziel:** 15-sekündiger, 9:16 düster-romantischer Kurzdrama-Trailer. Die Referenzbilder der weiblichen und männlichen Hauptfiguren fixieren das Erscheinungsbild der Figuren, während das Referenzbild des alten Schlosses den Raum vorgibt; Mittelnaheinstellungen und Gesichtsnahaufnahmen werden verwendet, um Blickduelle, Angst, Beherrschung und ein Gefühl von Gefahr darzustellen. Dieses Beispiel eignet sich zur Beobachtung der Stabilität realistischer Gesichtszüge, Mikroausdrücke, Blickbeziehungen und zusammenhängender Darstellungen.
| Referenz der weiblichen und männlichen Hauptfiguren | Referenz der alten Schlosskulisse |
| - | - |
| 
| 
|
[Realistisches Kurzdrama direkt öffnen oder herunterladen](https://cdn.acedata.cloud/uploads/0f3e9bf2-5073-46f4-9a2d-7d8d912391cf)
Der Prompt sollte die Figurenbeziehung, Emotionen und Einstellungsgröße klar benennen, anstatt nur „Mann und Frau im Dialog“ zu beschreiben:
```text theme={null}
15 秒、9:16 真人暗黑浪漫短剧预告。女主误入禁忌古堡，唤醒沉睡的吸血鬼贵族；
他危险而克制地靠近，她恐惧但不屈服。保持两位角色的五官、发型与服装一致，
以中近景和面部特写表现眼神对峙与情绪张力，暗色电影光线，节奏紧凑。
```
### Modische Brillenwerbung: Erhalt von Gesichtsdetails und Produktstruktur
**Produktionsziel:** 9:16 hochwertige modische Brillenwerbung. Das Ganzkörperbild der Person ist für Körperform und Laufstil zuständig, das Gesichtsreferenzbild für Gesichtszüge und Make-up, und das Produktbild für umlaufende Kurven, Linsenreflexionen, Bügel und die Cat-Eye-Kontur. Dieses Beispiel prüft gleichzeitig Gesichtsnahaufnahmen, Konsistenz mehrerer Personen, Tragebeziehungen und die geometrische Struktur des Produkts.
| Referenz für Model und Styling | Referenz für Gesichtsdetails | Referenz für das Brillenprodukt |
| - | - | - |
| 
| 
| 
|
[Modische Brillenwerbung direkt öffnen oder herunterladen](https://cdn.acedata.cloud/uploads/55715089-b6bd-4ef6-a3c2-e762a672f751)
In der Produktwerbung sollte der Prompt die Aufgaben der Personenreferenz und der Produktreferenz getrennt und klar beschreiben: Das Personenmaterial legt Gesicht, Make-up, Körperform und Ausstrahlung fest; das Produktmaterial legt Kontur, Material, Reflexionen und Trageposition fest. Das ist stabiler, als allgemein „eine Brillenwerbung generieren“ zu schreiben.
## Text-zu-Video
Wenn es nur ein Textelement gibt, handelt es sich um Text-zu-Video. Es eignet sich dazu, direkt aus Kreativideen, Skripten oder Einstellungsbeschreibungen Bilder zu generieren. Der Prompt kann in der Reihenfolge „Subjekt + Aktion + Szene + Kamera + Licht + Ton“ organisiert werden.
```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/videos' \
-H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒电影级香水广告：清晨海岸的黑色礁石上，透明香水瓶被薄雾与海浪环绕。微距展现瓶身水珠和玻璃折射，镜头从产品特写缓慢拉升到广阔海面；银蓝色调，真实自然光，高级克制，结尾定格产品。"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}'
```
Der standardmäßige synchrone Modus gibt nach Abschluss der Generierung die vollständige Aufgabe zurück:
```json theme={null}
{
"task": {
"id": "f5977217-ed2c-40da-adbe-93d08235618f",
"model": "MiniMax-H3",
"status": "succeeded",
"content": { "url": "https://cdn.acedata.cloud/minimax/f5977217.mp4" },
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
}
```
Wenn `"async": true` zur Anfrage hinzugefügt wird, gibt die Schnittstelle sofort zurück:
```json theme={null}
{
"task_id": "f5977217-ed2c-40da-adbe-93d08235618f",
"trace_id": "trace_7f8c2b1a"
}
```
## Bild-zu-Video mit erstem Frame
Markieren Sie ein Bild als `first_frame`, dann generiert das Modell ausgehend von diesem Bild. Dies eignet sich dafür, Poster, Produktbilder, Figurenentwürfe und fotografische Werke auf natürliche Weise in Bewegung zu versetzen.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "人物自然呼吸并看向窗外，衣角被微风吹动，镜头缓慢推进"
},
{
"type": "image_url",
"image_url": {
"url": "https://cdn.acedata.cloud/b1c82e4937.png"
},
"role": "first_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## Letzter Frame sowie Videos mit erstem und letztem Frame
Die alleinige Bereitstellung von `last_frame` ermöglicht dem Modell, sich natürlich bis zum angegebenen Bild zu generieren; die gleichzeitige Bereitstellung von `first_frame` und `last_frame` ermöglicht eine eindeutige Steuerung von Start- und Endpunkt. Geeignet für Übergänge, Formveränderungen, Wachstumsprozesse oder Produktvergleiche vorher und nachher.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "女孩从童年自然成长为青年，时间流逝平滑，人物始终位于画面中央"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_FIRST_FRAME_URL" },
"role": "first_frame"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_LAST_FRAME_URL" },
"role": "last_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
Die Größe und das Seitenverhältnis des ersten und letzten Bildes sollten möglichst übereinstimmen, und die Unterschiede bei der Position des Hauptmotivs, der Komposition und der Beleuchtung sollten nicht zu groß sein, damit sich ein natürlicher Übergang leichter erzielen lässt.
## Multimodales Referenz-zu-Video
Referenzmaterialien können kombiniert verwendet werden: Referenzbilder steuern das Aussehen von Figuren oder Produkten, Referenzvideos steuern Bewegungen und Kameraführung, Referenzaudio steuert Dialogstimme, Musik oder Schnittrhythmus. Im Prompt sollte klar angegeben werden, was jede Art von Material steuern soll, um zu vermeiden, dass Materialien nur hochgeladen werden, ohne eine Zuordnung anzugeben.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "保持参考人物的五官、发型与服装一致，按照参考视频中的表演动作完成时尚短片；镜头节奏跟随参考音频，近景突出自然面部表情"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_CHARACTER_IMAGE_URL" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "YOUR_PERFORMANCE_VIDEO_URL" },
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": { "url": "YOUR_AUDIO_URL" },
"role": "reference_audio"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## Callback-Benachrichtigungen
Die Übergabe von `callback_url` aktiviert automatisch den asynchronen Modus: Die Erstellungs-Schnittstelle gibt sofort `task_id` und `trace_id` zurück und sendet nach Abschluss der Aufgabe das Endergebnis per POST an diese Adresse; die Struktur entspricht der Antwort der Aufgabenabfrage.
Die endgültigen Statuswerte im Callback sind `succeeded`, `failed` oder `cancelled`. Auch bei Verwendung eines Callbacks wird empfohlen, `task_id` zu speichern, um aktiv abfragen oder verpasste Benachrichtigungen ausgleichen zu können.
## Häufige Fehler
| HTTP-Statuscode | Bedeutung | Verarbeitungsempfehlung |
| - | - | - |
| `400` | Parameterfehler oder ungültige Materialkombination | Prüfen Sie Pflichtfelder, `role`, Anzahl und Format der Materialien |
| `401` | Token fehlt oder ist ungültig | Prüfen Sie `Authorization: Bearer ...` |
| `402` | Guthaben oder Kontingent unzureichend | Allgemeines Guthaben in der Konsole aufladen |
| `422` | Inhalts-Sicherheitsprüfung nicht bestanden | Prompt oder Materialien anpassen und erneut einreichen |
| `429` | Anfrage zu häufig | Nach exponentiellem Backoff erneut versuchen; für Aufgabenabfragen wird ein Intervall von etwa 10 Sekunden empfohlen |
| `500` | Dienst vorübergehend nicht verfügbar | Anfragedaten aufbewahren und später erneut versuchen |
`task.status: succeeded` in der synchronen Antwort bedeutet, dass das Video generiert wurde; eine asynchrone Bestätigung bedeutet nur, dass die Aufgabe in die Warteschlange aufgenommen wurde. Es wird nur abgerechnet, wenn die Aufgabe letztlich erfolgreich ist; die Aufgabenabfrage selbst ist kostenlos und führt nicht zu wiederholten Abbuchungen.
### H3 Max
`MiniMax-H3-Max` unterstützt 480P oder 768P sowie ganzzahlige Dauern von 5–15 Sekunden. Audioeingaben werden nicht zusätzlich berechnet, die ersten 2 Bilder sind kostenlos, darüber hinausgehende Bilder werden einzeln berechnet; Referenzvideos werden nach der tatsächlichen Eingabedauer berechnet. Dieses Modell unterstützt kein 2K.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.