> ## 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. # Przewodnik integracji API generowania wideo MiniMax H3 > Minimax API guide - Ace Data Cloud Ten dokument przedstawia integrację i użycie API generowania wideo MiniMax H3. Interfejs obsługuje generowanie wideo z tekstu, kontrolę pierwszej i ostatniej klatki oraz generowanie wideo z referencjami multimodalnymi, używając jednolitej struktury multimodalnej V2 `content` do tworzenia zadań. ## Proces uzyskania dostępu Aby używać API generowania wideo MiniMax H3, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token, i zachowaj go do późniejszego użycia. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, nastąpi automatyczne przekierowanie na stronę logowania z zaproszeniem do rejestracji i logowania, a po ukończeniu automatycznie wrócisz na bieżącą stronę. **Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności osobnego składania wniosku dla każdej usługi.** Pierwsze uzyskanie dostępu obejmuje bezpłatny limit, umożliwiający darmowe testowanie; gdy limit będzie niewystarczający, możesz doładować wspólne saldo w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [API generowania wideo MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-videos-integration) Zaleca się zapisanie Tokena jako zmiennej środowiskowej, bez umieszczania go w kodzie źródłowym ani przesyłania do repozytorium wersji: ```bash theme={null} export ACEDATACLOUD_API_KEY="YOUR_API_KEY" ``` ## Przegląd interfejsu * **Base URL**：`https://api.acedata.cloud` * **Endpoint**：`POST /minimax/videos` * **Metoda uwierzytelniania**：w HTTP Header należy przekazać `authorization: Bearer {token}` * **Nagłówki żądania**： * `accept: application/json` * `content-type: application/json` * **Model（model）**：`MiniMax-H3` * **Struktura wejściowa**：tekst, obrazy, wideo i audio są przekazywane jednolicie przez `content` * **Tryb wyjściowy**：domyślnie synchronicznie oczekuje na ukończenie generowania i zwraca pełny `task`; po przekazaniu `async: true` lub `callback_url` natychmiast zwraca `task_id` oraz `trace_id` * **Zapytanie o wynik**：status i gotowy materiał można uzyskać przez [API zapytań o zadania MiniMax H3](https://platform.acedata.cloud/documents/minimax-tasks-integration) * **Asynchroniczne callbacki**：opcjonalne, odbieranie końcowego wyniku zadania przez `callback_url` Nie musisz przekazywać `action`, aby wybrać tryb generowania; interfejs automatycznie określi zastosowanie na podstawie typu materiałów i `role` w `content`. ## Do jakich scenariuszy się nadaje | Scenariusz | Kombinacja wejściowa | Typowe zastosowania | | - | - | - | | Generowanie wideo z tekstu | Tekst | Kreacje reklamowe, prewizualizacja storyboardów, krótkie wideo, ujęcia nastrojowe | | Generowanie wideo z obrazu pierwszej klatki | Tekst + obraz pierwszej klatki | Naturalne ożywianie zdjęć produktów, plakatów, zdjęć postaci lub ilustracji | | Wideo z ostatnią klatką / pierwszą i ostatnią klatką | Tekst + ostatnia klatka lub tekst + pierwsza klatka + ostatnia klatka | Kontrola początku i końca, przejść, zmian rozwojowych oraz porównań przed i po | | Generowanie wideo z referencjami multimodalnymi | Tekst + referencyjne obrazy / wideo / audio | Zachowanie spójności postaci i produktów, odtwarzanie ruchów, pracy kamery, barwy głosu lub rytmu montażu | ## Proces wywołania Gdy domyślnie nie zostanie przekazane `async`, `/minimax/videos` będzie oczekiwać na ukończenie generowania i bezpośrednio zwróci pełny `task`. Aby natychmiast zwolnić połączenie, przekaż `async: true` lub `callback_url`: 1. Zapisz `task_id` i `trace_id` z natychmiastowej odpowiedzi. 2. Gdy callback nie jest skonfigurowany, wywołuj `/minimax/tasks` mniej więcej co 10 sekund. 3. Gdy `task.status` zmieni się na `succeeded`, pobierz wideo z `task.content.url`. 4. Gdy status wynosi `failed` lub `cancelled`, zatrzymaj odpytywanie i odczytaj `task.error`. ## Parametry żądania najwyższego poziomu | Parametr | Typ | Wymagany | Wartość domyślna | Opis | | - | - | - | - | - | | `model` | string | Tak | - | Na stałe `MiniMax-H3` | | `content` | object\[] | Tak | - | Tablica treści multimodalnych, musi zawierać jedną niepustą pozycję `text` | | `resolution` | string | Tak | - | `768P` lub `2K` | | `duration` | integer | Tak | - | Czas trwania generowania, liczba całkowita 4–15 sekund | | `ratio` | string | Warunkowo wymagany | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` | | `async` | boolean | Nie | `false` | Przy `true` natychmiast zwraca identyfikator zadania, a wynik uzyskuje się przez interfejs zadań | | `callback_url` | string | Nie | - | Publiczny URL callbacku odbierający końcowy wynik zadania; po podaniu automatycznie włącza tryb asynchroniczny | Reguły `ratio` zależą od workflow: * **Generowanie wideo z tekstu**：wymagane i nie może mieć wartości `adaptive`. * **Wideo z pierwszą klatką, ostatnią klatką lub pierwszą i ostatnią klatką**：format kadru jest określany przez obrazy wejściowe; zaleca się pominięcie parametru lub przekazanie `adaptive`. * **Generowanie wideo z referencjami multimodalnymi**：można pominąć, domyślnie `adaptive`; można również jawnie określić stałe proporcje. Interfejs nie akceptuje starszych ani kompatybilnych pól, takich jak `prompt`, `image_urls`, `audio_urls`, `messages` i `first_frame_image`. W przypadku otrzymania błędu dotyczącego takich parametrów usuń stare pola i przejdź na `content`; na przykład zmień `"prompt": "Kot macha łapą"` na `"content": [{"type": "text", "text": "Kot macha łapą"}]`. Nie wysyłaj jednocześnie obu formatów, nowego i starego. ## Parametry elementów treści content Każdy element treści musi mieć `type`, a pozostałe pola są określane przez typ: | `type` | Pole danych | `role` | Opis | | - | - | - | - | | `text` | `text` | Nie przekazywać | Każde żądanie musi zawierać jedną niepustą pozycję tekstową, maksymalnie 7000 znaków | | `image_url` | `image_url.url` | `first_frame` | Obraz pierwszej klatki; gdy jest tylko jeden obraz i pominięto `role`, również jest traktowany jako pierwsza klatka | | `image_url` | `image_url.url` | `last_frame` | Obraz ostatniej klatki; może być używany samodzielnie lub razem z `first_frame` do kontrolowania początku i końca | | `image_url` | `image_url.url` | `reference_image` | Referencyjny obiekt, postać, produkt, ubiór, scena lub styl | | `video_url` | `video_url.url` | `reference_video` | Referencyjny ruch, praca kamery, występ lub struktura montażu | | `audio_url` | `audio_url.url` | `reference_audio` | Referencyjna barwa głosu, dialog, muzyka lub rytm | Adresy mediów obsługują trzy formy: * Publicznie dostępny HTTPS URL, zalecany dla dużych plików. * `mm_file://{file_id}`, odwołanie do przesłanego już lub istniejącego pliku wynikowego. * Base64 data URI odpowiedniego typu mediów. Base64 zwiększa rozmiar o około jedną trzecią; upewnij się, że całe ciało żądania nie przekracza 64 MB. ## Specyfikacje materiałów i limity ilościowe | Materiał | Format | Limit pojedynczego pliku | Wymiary / czas trwania | Limit liczby | | - | - | - | - | - | | Obraz | JPG、JPEG、PNG、WEBP、HEIC、HEIF | Nie więcej niż 30 MB | Szerokość i wysokość po 256–5760 px; proporcje 0,4–2,5 | Maks. 1 pierwsza klatka, maks. 1 ostatnia klatka, maks. 9 obrazów referencyjnych | | Wideo | MP4、MOV；H.264/AVC lub H.265/HEVC；ścieżka audio AAC lub MP3 | Nie więcej niż 50 MB | Każdy klip 2–15 s, łącznie nie więcej niż 15 s; szerokość i wysokość po 256–5760 px; proporcje 0,4–2,5; 23,976–60 fps | Maks. 3 referencyjne klipy wideo | | Audio | WAV、MP3 | Nie więcej niż 15 MB | Każdy klip 2–15 s, łącznie nie więcej niż 15 s | Maks. 3 referencyjne klipy audio | Łącznie obrazy, wideo i audio w scenariuszu referencji multimodalnych mogą obejmować maksymalnie 12 plików. Scenariusz pierwszej i ostatniej klatki oraz scenariusz materiałów referencyjnych wzajemnie się wykluczają: po użyciu `reference_image`, `reference_video` lub `reference_audio` nie można już używać `first_frame` ani `last_frame`, i odwrotnie. ## Prezentacja możliwości klasy produkcyjnej Poniżej nie znajdują się grafiki koncepcyjne ani materiały zastępcze, lecz rzeczywiste wejścia referencyjne i faktyczne wyjścia wideo oficjalnych próbek możliwości klasy produkcyjnej MiniMax H3. Trzy zestawy przykładów obejmują odpowiednio filmy brandingowe, narrację z udziałem prawdziwych osób oraz modowy e-commerce i nadają się do oceny najważniejszych możliwości modelu w produkcji komercyjnej. | Możliwość | Kluczowe elementy obserwacji | | - | - | | Spójność postaci i twarzy | Czy rysy twarzy, fryzura, makijaż i charakter postaci pozostają stabilne po zmianie wielu ujęć | | Ekspresja twarzy | Spojrzenie, mikroekspresje, napięcie emocjonalne i naturalne ruchy głowy w zbliżeniach | | Zachowanie struktury produktu | Kontury, materiały, relacja noszenia i odbicia lustrzane produktów takich jak okulary i torebki | | Realizacja identyfikacji wizualnej marki | Czy atmosfera sceny, ziarno filmowe, kolorystyka, logo i rytm montażu są spójne | | Filmowa narracja | Czy zmiany planów, prowadzenie postaci, ruch kamery, rytm i dźwięk mogą utworzyć kompletną sekwencję | „Możliwości twarzy” oznaczają tutaj spójność wyglądu postaci, szczegóły twarzy i kontrolę ekspresji w generowaniu wideo, a nie rozpoznawanie tożsamości, porównywanie twarzy ani interfejs zamiany twarzy. ### Film krótkometrażowy luksusowej marki: spójność postaci, produktu i zasobów marki **Cel produkcyjny:** Film modowy premium w formacie 16:9. Surową atmosferę tworzą pustynna droga i zabytkowy samochód, przy zachowaniu wyglądu głównej bohaterki oraz struktury czarnej torebki, a logo marki zostaje naturalnie włączone do zakończenia. Ten przykład koncentruje się na testowaniu spójności postaci między ujęciami, zachowania produktu, filmowej jakości i możliwości domknięcia przekazu marki. | Referencja atmosfery i sceny | Referencja postaci | | - | - | | Referencja atmosfery filmu brandingowego z pustynną drogą i zabytkowym samochodem | Referencja głównej bohaterki filmu brandingowego | | Referencja produktu — torebki | Referencja logo marki | | - | - | | Referencja produktu — czarnej torebki | Referencja logo marki |