> ## 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.
# Guide för integration av MiniMax H3 API för videogenerering
> Minimax API guide - Ace Data Cloud
Detta dokument beskriver integration och användning av MiniMax H3 API för videogenerering. Detta gränssnitt stöder text-till-video, kontroll med första och sista bildruta samt multimodal referensbaserad videogenerering, och använder en enhetlig V2-multimodal `content`-struktur för att skapa uppgifter.
## Ansökningsprocess
För att använda MiniMax H3 API för videogenerering, hämta först din API-token från [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) och spara den för senare användning.
Om du ännu inte har loggat in eller registrerat dig, omdirigeras du automatiskt till inloggningssidan där du uppmanas att registrera dig och logga in. När detta är klart återvänder du automatiskt till den aktuella sidan.
**En API-token kan anropa alla plattformens tjänster, utan att du behöver ansöka separat för varje tjänst.** Vid första ansökan får du en gratis kvot för att kunna prova kostnadsfritt; när kvoten inte räcker till kan du fylla på det gemensamma saldot i [konsolen](https://platform.acedata.cloud/console/coin).
> 📘 Fullständig dokumentation: [MiniMax H3 API för videogenerering →](https://platform.acedata.cloud/documents/minimax-videos-integration)
Det rekommenderas att spara token som en miljövariabel och inte skriva in den i källkoden eller skicka den till versionshanteringssystemet:
```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```
## Översikt över gränssnittet
* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/videos`
* **Autentiseringsmetod**：Ange `authorization: Bearer {token}` i HTTP Header
* **Request Headers**：
* `accept: application/json`
* `content-type: application/json`
* **Modell (model)**：`MiniMax-H3`
* **Indatastruktur**：Text, bilder, video och ljud skickas enhetligt via `content`
* **Utmatningsläge**：Väntar synkront som standard tills genereringen är klar och returnerar hela `task`; med `async: true` eller `callback_url` returneras `task_id` och `trace_id` omedelbart
* **Resultatfråga**：Hämta status och färdig video via [MiniMax H3 API för uppgiftsfråga](https://platform.acedata.cloud/documents/minimax-tasks-integration)
* **Asynkron callback**：Valfritt, ta emot slutligt uppgiftsresultat via `callback_url`
Du behöver inte skicka `action` för att välja genereringsläge; gränssnittet avgör automatiskt användningen baserat på materialtyperna och `role` i `content`.
## Vilka scenarier passar det för
| Scenario | Indatakombination | Vanliga användningsområden |
| - | - | - |
| Text-till-video | Text | Annonsidéer, storyboard-förhandsvisning, kortvideor, stämningsbilder |
| Bild-till-video med första bildruta | Text + bild för första bildrutan | Få produktbilder, affischer, porträttfoton eller illustrationer att röra sig naturligt |
| Video med sista bildruta / första och sista bildruta | Text + sista bildruta, eller text + första bildruta + sista bildruta | Styra början och slutet, övergångar, förändringar över tid och före- och efterjämförelser |
| Multimodal referensbaserad videogenerering | Text + referensbild / video / ljud | Behålla konsekvens för karaktärer och produkter, återskapa rörelser, kamerarörelser, röstklang eller klippningsrytm |
## Anropsflöde
När `async` inte skickas som standard väntar `/minimax/videos` tills genereringen är klar och returnerar direkt hela `task`. Om anslutningen behöver frigöras omedelbart, skicka `async: true` eller `callback_url`:
1. Spara `task_id` och `trace_id` i det omedelbara svaret.
2. Om ingen callback har konfigurerats, anropa `/minimax/tasks` ungefär var 10:e sekund för att fråga.
3. När `task.status` blir `succeeded`, hämta videon från `task.content.url`.
4. När statusen är `failed` eller `cancelled`, sluta polla och läs `task.error`.
## Begärandeparametrar på toppnivå
| Parameter | Typ | Obligatorisk | Standardvärde | Beskrivning |
| - | - | - | - | - |
| `model` | string | Ja | - | Fast värde: `MiniMax-H3` |
| `content` | object\[] | Ja | - | Multimodal innehållsarray, måste innehålla ett icke-tomt `text`-objekt |
| `resolution` | string | Ja | - | `768P` eller `2K` |
| `duration` | integer | Ja | - | Genereringslängd, heltal på 4–15 sekunder |
| `ratio` | string | Villkorligt obligatorisk | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `async` | boolean | Nej | `false` | När `true` returneras uppgiftsidentifieraren omedelbart; hämta resultatet via uppgiftsgränssnittet |
| `callback_url` | string | Nej | - | Offentlig callback-URL för att ta emot det slutliga uppgiftsresultatet; aktiverar asynkront läge automatiskt när den anges |
Reglerna för `ratio` beror på arbetsflödet:
* **Text-till-video**：Obligatoriskt och får inte vara `adaptive`.
* **Video med första bildruta, sista bildruta eller första och sista bildruta**：Bildformatet bestäms av indatabilden; det rekommenderas att utelämna det eller skicka `adaptive`.
* **Multimodal referensbaserad videogenerering**：Kan utelämnas, med standardvärdet `adaptive`; du kan även uttryckligen ange ett fast förhållande.
Gränssnittet accepterar inte gamla eller kompatibilitetsfält, såsom `prompt`, `image_urls`, `audio_urls`, `messages` och `first_frame_image`. När du får ett parameterfel för denna typ av parametrar, ta bort de gamla fälten och migrera till `content`; ändra till exempel `"prompt": "一只猫挥手"` till `"content": [{"type": "text", "text": "一只猫挥手"}]`。Skicka inte både det nya och gamla formatet samtidigt.
## Parametrar för innehållsobjekt i content
Varje innehållsobjekt måste ha `type`, medan övriga fält bestäms av typen:
| `type` | Datafält | `role` | Beskrivning |
| - | - | - | - |
| `text` | `text` | Skickas inte | Varje begäran måste innehålla ett icke-tomt textobjekt, med högst 7 000 tecken |
| `image_url` | `image_url.url` | `first_frame` | Bild för första bildrutan; om det endast finns en bild och `role` utelämnas behandlas den också som första bildruta |
| `image_url` | `image_url.url` | `last_frame` | Bild för sista bildrutan; kan användas separat eller kombineras med `first_frame` för att styra start- och slutpunkt |
| `image_url` | `image_url.url` | `reference_image` | Referens för motiv, karaktär, produkt, kläder, scen eller stil |
| `video_url` | `video_url.url` | `reference_video` | Referens för rörelser, kamerarörelser, framträdande eller klippstruktur |
| `audio_url` | `audio_url.url` | `reference_audio` | Referens för röstklang, dialog, musik eller rytm |
Medieadresser stöder tre format:
* HTTPS-URL:er som är offentligt tillgängliga, rekommenderas för stora filer.
* `mm_file://{file_id}`, som refererar till filer som redan har laddats upp eller befintliga resultat.
* Base64 data URI för motsvarande medietyp. Base64 ökar storleken med ungefär en tredjedel; säkerställ att hela begärandetexten inte överstiger 64 MB.
## Materialspecifikationer och kvantitetsbegränsningar
| Material | Format | Begränsning per enskild fil | Dimensioner / längd | Antalsbegränsning |
| - | - | - | - | - |
| Bild | JPG, JPEG, PNG, WEBP, HEIC, HEIF | Högst 30 MB | Bredd och höjd är båda 256–5760 px; bildförhållande 0,4–2,5 | Högst 1 första bildruta, högst 1 sista bildruta, högst 9 referensbilder |
| Video | MP4, MOV; H.264/AVC eller H.265/HEVC; ljudspår AAC eller MP3 | Högst 50 MB | Varje klipp 2–15 sekunder, totalt högst 15 sekunder; bredd och höjd är båda 256–5760 px; bildförhållande 0,4–2,5; 23,976–60 fps | Högst 3 referensvideor |
| Ljud | WAV, MP3 | Högst 15 MB | Varje klipp 2–15 sekunder, totalt högst 15 sekunder | Högst 3 referensljudklipp |
Bilder, videor och ljud i multimodala referensscenarier får sammanlagt omfatta högst 12 filer. Scenarier med första och sista bildruta och scenarier med referensmaterial utesluter varandra: när `reference_image`, `reference_video` eller `reference_audio` används, kan `first_frame` eller `last_frame` inte längre användas, och vice versa.
## Presentation av produktionsklassade funktioner
Nedan följer inte konceptbilder eller platshållarmaterial, utan verkliga referensingångar och faktiska videoutgångar från MiniMax H3:s officiella exempel på produktionsklassade funktioner. De tre exempelgrupperna omfattar varumärkeskortfilmer, berättelser med verkliga personer och mode-e-handel, och lämpar sig för att utvärdera modellens viktigaste förmågor inom kommersiell produktion.
| Förmåga | Viktiga observationer |
| - | - |
| Konsekvens för personer och ansikten | Om ansiktsdrag, frisyr, makeup och personens karaktär förblir stabila efter växling mellan flera tagningar |
| Ansiktsuttryck | Blick, mikrouttryck, emotionell spänning och naturliga huvudrörelser i närbilder |
| Bevarande av produktstruktur | Kontur, material, bärrelation och spegelreflektioner för produkter som glasögon och handväskor |
| Genomförande av varumärkesvisualisering | Om scenatmosfär, filmkorn, färger, logotyp och klipprytm är enhetliga |
| Filmisk berättelse | Om förändringar i bildstorlek, personregi, kamerarörelser, rytm och ljud kan bilda ett komplett avsnitt |
Med ”ansiktsförmåga” avses konsekvens i personers utseende, ansiktsdetaljer och kontroll av skådespel i videogenerering, inte ansiktsigenkänning, ansiktsjämförelse eller ansiktsbytesgränssnitt.
### Kortfilm för exklusivt varumärke: enhetlighet mellan person, produkt och varumärkestillgångar
**Produktionsmål:** 16:9-film för ett exklusivt modemärke. Skapa en kylig atmosfär med en ökenväg och en veteranbil, behåll huvudrollsinnehavarinnans utseende och den svarta handväskans struktur, och integrera varumärkets logotyp naturligt i slutet. Detta exempel testar främst konsekvens för personer mellan tagningar, produktbevarande, filmisk känsla och förmågan att avsluta med varumärket.
| Referens för atmosfär och scen | Personreferens |
| - | - |
| 
| 
|
| Referens för handväskprodukt | Referens för varumärkeslogotyp |
| - | - |
| 
| 
|
[Öppna eller ladda ner varumärkeskortfilmen direkt](https://cdn.acedata.cloud/uploads/6845b11d-1a58-4478-afd8-29e7e117772a)
Motsvarande organisationssätt för `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"
}
```
### Vertikalt kortdrama med verkliga personer: ansiktskonsekvens och känslomässigt skådespel
**Produktionsmål:** 15 sekunder, 9:16 mörk romantisk kortdramatrailer. Lås karaktärernas utseende genom referensbilder av den kvinnliga och manliga huvudrollen, och styr miljön med en referensbild av det gamla slottet; använd mellanbilder och ansiktsnärbilder för att visa ögonkontaktens konfrontation, rädsla, återhållsamhet och känslan av fara. Detta exempel är lämpligt för att observera stabiliteten i verklighetstrogna ansiktsdrag, mikroansiktsuttryck, blickrelationer och sammanhängande skådespel.
| Referens för kvinnlig och manlig huvudroll | Referens för slottsmiljö |
| - | - |
| 
| 
|
[Öppna eller ladda ner det verklighetstrogna kortdramat direkt](https://cdn.acedata.cloud/uploads/0f3e9bf2-5073-46f4-9a2d-7d8d912391cf)
Prompten bör tydligt ange karaktärernas relation, känslor och bildutsnitt, snarare än att bara beskriva ”en man och en kvinna som samtalar”:
```text theme={null}
15 sekunder, 9:16 verklighetstrogen mörk romantisk kortdramatrailer. Den kvinnliga huvudrollen råkar komma in i ett förbjudet gammalt slott och väcker en sovande vampyraristokrat;
han närmar sig farligt men återhållsamt, hon är rädd men ger inte efter. Behåll de två karaktärernas ansiktsdrag, frisyrer och kläder konsekventa,
använd mellanbilder och ansiktsnärbilder för att visa blickarnas konfrontation och känslomässig spänning, mörk filmisk belysning, kompakt tempo.
```
### Modeannons för glasögon: behåll ansiktsdetaljer och produktstruktur
**Produktionsmål:** 9:16 exklusiv modeannons för glasögon. Helkroppsbilden av personen ansvarar för kroppsform och gångstil, ansiktsreferensbilden ansvarar för ansiktsdrag och makeup, produktbilden ansvarar för omslutande kurvor, linsreflektioner, skalmar och kattögonkonturer. Detta exempel testar samtidigt ansiktsnärbilder, konsekvens mellan flera personer, bärrelationer och produktens geometriska struktur.
| Referens för modell och styling | Referens för ansiktsdetaljer | Referens för glasögonprodukt |
| - | - | - |
| 
| 
| 
|
[Öppna eller ladda ner modeannonsen för glasögon direkt](https://cdn.acedata.cloud/uploads/55715089-b6bd-4ef6-a3c2-e762a672f751)
I produktannonser bör prompten tydligt separera ansvaret för personreferensen och produktreferensen: personmaterialet styr ansikte, makeup, kroppsform och utstrålning; produktmaterialet styr kontur, material, reflektioner och bärposition. Detta är mer stabilt än att generellt skriva ”generera en glasögonannons”.
## Text-till-video
När det bara finns ett textobjekt är det text-till-video. Det passar för att direkt generera bilder från idéer, manus eller bildbeskrivningar. Prompten kan organiseras i ordningen ”motiv + handling + miljö + kamera + ljus + ljud”.
```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 sekunder filmisk parfymannons: På svarta klippor vid kusten i gryningen omges en genomskinlig parfymflaska av tunn dimma och havsvågor. Makrobild visar vattendroppar på flaskan och glasets ljusbrytning, kameran lyfter långsamt från produktnärbilden till det vidsträckta havet; silverblå färgtoner, verklighetstroget naturligt ljus, exklusivt återhållsamt, avslutas med en stillbild av produkten."
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}'
```
Standardläget för synkronisering returnerar hela uppgiften när genereringen är klar:
```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"
}
}
```
Om `"async": true` läggs till i begäran returnerar gränssnittet omedelbart:
```json theme={null}
{
"task_id": "f5977217-ed2c-40da-adbe-93d08235618f",
"trace_id": "trace_7f8c2b1a"
}
```
## Bild-till-video med första bildrutan
Markera bilden som `first_frame`, så börjar modellen generera från denna bild. Det passar för att få affischer, produktbilder, karaktärsdesignbilder och fotografiska verk att naturligt börja röra sig.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "Personen andas naturligt och tittar ut genom fönstret, klädernas fållar rör sig i den lätta vinden, kameran går långsamt framåt"
},
{
"type": "image_url",
"image_url": {
"url": "https://cdn.acedata.cloud/b1c82e4937.png"
},
"role": "first_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## Slutbildruta samt video med första och sista bildruta
Att endast tillhandahålla `last_frame` gör att modellen naturligt kan generera fram till den angivna bilden; att samtidigt tillhandahålla `first_frame` och `last_frame` gör det möjligt att tydligt kontrollera start- och slutpunkt. Lämpligt för övergångar, formförändringar, tillväxtprocesser eller jämförelser av produkter före och efter.
```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"
}
```
Storleken och bildförhållandet för den första och sista bildrutan bör vara så lika som möjligt, och skillnaderna i motivets position, komposition och ljussättning bör inte vara för stora, så blir det lättare att få en naturlig övergång.
## Multimodal referens för video-generering
Referensmaterial kan användas i kombination: referensbilder styr karaktärers eller produkters utseende, referensvideor styr rörelser och kameraföring, och referensljud styr dialogröst, musik eller klipprytm. I prompten bör det tydligt anges vad varje typ av material ska styra, för att undvika att bara ladda upp material utan att ange sambandet.
```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"
}
```
## Återanropsnotifiering
Att skicka in `callback_url` aktiverar automatiskt asynkront läge: skapandegränssnittet returnerar omedelbart `task_id` och `trace_id`, och skickar det slutliga resultatet via POST till den adressen när uppgiften är klar. Strukturen är densamma som för svaret vid uppgiftsfråga.
Slutstatusen i återanropet är `succeeded`, `failed` eller `cancelled`. Även vid användning av återanrop rekommenderas det att spara `task_id`, för att kunna göra aktiva förfrågningar eller kompensera för missade notifieringar.
## Vanliga fel
| HTTP-statuskod | Betydelse | Rekommenderad åtgärd |
| - | - | - |
| `400` | Parameterfel eller ogiltig materialkombination | Kontrollera obligatoriska fält, `role`, antal material och format |
| `401` | Token saknas eller är ogiltig | Kontrollera `Authorization: Bearer ...` |
| `402` | Otillräckligt saldo eller otillräcklig kvot | Fyll på det gemensamma saldot i konsolen |
| `422` | Innehållssäkerhetskontrollen godkändes inte | Justera prompten eller materialet och skicka in igen |
| `429` | För många begäranden | Försök igen med exponentiell backoff; rekommenderat intervall för uppgiftspollning är cirka 10 sekunder |
| `500` | Tjänsten är tillfälligt otillgänglig | Spara begärandeinformationen och försök igen senare |
`task.status: succeeded` i det synkrona svaret innebär att videon har genererats; asynkron bekräftelse innebär endast att uppgiften har lagts i kön. Debitering sker endast när uppgiften slutligen lyckas; att fråga efter uppgifter är kostnadsfritt och leder inte till upprepad debitering.
### H3 Max
`MiniMax-H3-Max` stöder 480P eller 768P samt heltalslängder på 5–15 sekunder. Ljudinmatning debiteras inte extra, de första 2 bilderna är kostnadsfria och överskjutande bilder debiteras per bild; referensvideor debiteras utifrån faktisk inmatningslängd. Denna modell stöder inte 2K.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.