> ## 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. # Guida all'integrazione dell'API di generazione video MiniMax H3 > Minimax API guide - Ace Data Cloud Questo articolo introduce l'integrazione e l'utilizzo dell'API di generazione video MiniMax H3. Questa interfaccia supporta la generazione di video da testo, il controllo del primo e dell'ultimo fotogramma e la generazione di video con riferimenti multimodali, utilizzando una struttura `content` multimodale V2 unificata per creare attività. ## Procedura di richiesta Per utilizzare l'API di generazione video MiniMax H3, accedi innanzitutto alla [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token e conservarlo per l'uso futuro. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per registrarti ed effettuare l'accesso; al termine, tornerai automaticamente alla pagina corrente. **Un solo API Token consente di chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ciascun servizio.** La prima richiesta include crediti gratuiti per provare il servizio senza costi; quando i crediti sono insufficienti, puoi ricaricare il saldo universale nella [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [API di generazione video MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-videos-integration) Si consiglia di salvare il Token come variabile d'ambiente, senza scriverlo nel codice sorgente né inviarlo al repository di versionamento: ```bash theme={null} export ACEDATACLOUD_API_KEY="YOUR_API_KEY" ``` ## Panoramica dell'interfaccia * **Base URL**：`https://api.acedata.cloud` * **Endpoint**：`POST /minimax/videos` * **Metodo di autenticazione**：includere `authorization: Bearer {token}` nell'HTTP Header * **Intestazioni della richiesta**： * `accept: application/json` * `content-type: application/json` * **Modello (model)**：`MiniMax-H3` * **Struttura di input**：testo, immagini, video e audio vengono passati in modo unificato tramite `content` * **Modalità di output**：per impostazione predefinita attende in modo sincrono il completamento della generazione e restituisce il `task` completo; passando `async: true` o `callback_url`, restituisce immediatamente `task_id` e `trace_id` * **Consultazione del risultato**：ottenere lo stato e il video finale tramite l'[API di consultazione delle attività MiniMax H3](https://platform.acedata.cloud/documents/minimax-tasks-integration) * **Callback asincrono**：opzionale, riceve il risultato finale dell'attività tramite `callback_url` Non è necessario passare `action` per selezionare la modalità di generazione; l'interfaccia determina automaticamente l'uso in base al tipo di materiale e al `role` in `content`. ## Scenari adatti | Scenario | Combinazione di input | Utilizzi comuni | | - | - | - | | Generazione video da testo | Testo | Creatività pubblicitaria, previsualizzazione di storyboard, video brevi, inquadrature d'atmosfera | | Generazione video da immagine del primo fotogramma | Testo + immagine del primo fotogramma | Far muovere naturalmente immagini di prodotti, poster, foto di persone o illustrazioni | | Video con ultimo fotogramma / primo e ultimo fotogramma | Testo + ultimo fotogramma, oppure testo + primo fotogramma + ultimo fotogramma | Controllare l'inizio e la fine del video, le transizioni, i cambiamenti di crescita e i confronti prima/dopo | | Generazione video con riferimenti multimodali | Testo + immagini / video / audio di riferimento | Mantenere coerenti personaggi e prodotti, riprodurre azioni, movimenti di camera, timbro vocale o ritmo di montaggio | ## Flusso di chiamata Quando `async` non viene passato per impostazione predefinita, `/minimax/videos` attende il completamento della generazione e restituisce direttamente il `task` completo. Se è necessario liberare immediatamente la connessione, passare `async: true` o `callback_url`: 1. Salvare `task_id` e `trace_id` nella risposta immediata. 2. Se non è configurato un callback, chiamare `/minimax/tasks` circa ogni 10 secondi per effettuare una query. 3. Quando `task.status` diventa `succeeded`, ottenere il video da `task.content.url`. 4. Quando lo stato è `failed` o `cancelled`, interrompere il polling e leggere `task.error`. ## Parametri di richiesta di primo livello | Parametro | Tipo | Obbligatorio | Valore predefinito | Descrizione | | - | - | - | - | - | | `model` | string | Sì | - | Fisso a `MiniMax-H3` | | `content` | object\[] | Sì | - | Array di contenuti multimodali, deve contenere un elemento `text` non vuoto | | `resolution` | string | Sì | - | `768P` o `2K` | | `duration` | integer | Sì | - | Durata generata, numero intero di 4-15 secondi | | `ratio` | string | Obbligatorio condizionale | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` | | `async` | boolean | No | `false` | Quando è `true`, restituisce immediatamente l'identificativo dell'attività e ottiene il risultato tramite l'interfaccia delle attività | | `callback_url` | string | No | - | URL di callback pubblico che riceve il risultato finale dell'attività; dopo averlo fornito, abilita automaticamente la modalità asincrona | Le regole di `ratio` dipendono dal flusso di lavoro: * **Generazione video da testo**：obbligatorio e non può essere `adaptive`. * **Video con primo fotogramma, ultimo fotogramma o primo e ultimo fotogramma**：il formato è determinato dall'immagine di input; si consiglia di ometterlo o passare `adaptive`. * **Generazione video con riferimenti multimodali**：può essere omesso, il valore predefinito è `adaptive`; è inoltre possibile specificare esplicitamente una proporzione fissa. L'interfaccia non accetta campi legacy o di compatibilità, ad esempio `prompt`, `image_urls`, `audio_urls`, `messages` e `first_frame_image`. Quando si riceve un errore relativo a tali parametri, eliminare i campi legacy e migrare a `content`; ad esempio, modificare `"prompt": "一只猫挥手"` in `"content": [{"type": "text", "text": "一只猫挥手"}]`. Non inviare contemporaneamente entrambi i formati, nuovo e vecchio. ## Parametri degli elementi di contenuto content Ogni elemento di contenuto deve avere `type`; gli altri campi dipendono dal tipo: | `type` | Campo dati | `role` | Descrizione | | - | - | - | - | | `text` | `text` | Non passare | Ogni richiesta deve contenere un elemento di testo non vuoto, con un massimo di 7000 caratteri | | `image_url` | `image_url.url` | `first_frame` | Immagine del primo fotogramma; quando è presente una sola immagine e `role` viene omesso, viene anch'essa elaborata come primo fotogramma | | `image_url` | `image_url.url` | `last_frame` | Immagine dell'ultimo fotogramma; può essere utilizzata singolarmente oppure combinata con `first_frame` per controllare inizio e fine | | `image_url` | `image_url.url` | `reference_image` | Soggetto, personaggio, prodotto, abbigliamento, scena o stile di riferimento | | `video_url` | `video_url.url` | `reference_video` | Azione, movimento di camera, interpretazione o struttura di montaggio di riferimento | | `audio_url` | `audio_url.url` | `reference_audio` | Timbro vocale, dialogo, musica o ritmo di riferimento | Gli indirizzi dei media supportano tre formati: * URL HTTPS accessibili pubblicamente, consigliati per file di grandi dimensioni. * `mm_file://{file_id}`, per fare riferimento a file già caricati o a risultati esistenti. * Base64 data URI del tipo di media corrispondente. Base64 aumenta le dimensioni di circa un terzo; assicurarsi che l'intero corpo della richiesta non superi 64 MB. ## Specifiche dei materiali e limiti di quantità | Materiale | Formato | Limite per singolo file | Dimensioni / durata | Limite di quantità | | - | - | - | - | - | | Immagini | JPG、JPEG、PNG、WEBP、HEIC、HEIF | Non superiore a 30 MB | Larghezza e altezza entrambe 256-5760 px; rapporto d'aspetto 0.4-2.5 | Massimo 1 primo fotogramma, massimo 1 ultimo fotogramma, massimo 9 immagini di riferimento | | Video | MP4、MOV；H.264/AVC o H.265/HEVC；traccia audio AAC o MP3 | Non superiore a 50 MB | Ogni clip 2-15 secondi, totale non superiore a 15 secondi; larghezza e altezza entrambe 256-5760 px; rapporto d'aspetto 0.4-2.5；23.976-60 fps | Massimo 3 video di riferimento | | Audio | WAV、MP3 | Non superiore a 15 MB | Ogni clip 2-15 secondi, totale non superiore a 15 secondi | Massimo 3 audio di riferimento | Immagini, video e audio negli scenari di riferimento multimodale possono totalizzare al massimo 12 file. Lo scenario dei fotogrammi iniziale e finale e lo scenario dei materiali di riferimento sono mutuamente esclusivi: una volta utilizzati `reference_image`, `reference_video` o `reference_audio`, non è più possibile utilizzare `first_frame` o `last_frame`, e viceversa. ## Dimostrazione delle capacità di livello produttivo Quanto segue non sono immagini concettuali o materiali segnaposto, bensì input di riferimento reali e output video effettivi dei filmati campione ufficiali delle capacità di livello produttivo di MiniMax H3. I tre gruppi di casi coprono rispettivamente spot di brand, narrazione con attori reali ed e-commerce di moda, e sono adatti a valutare le capacità più cruciali del modello nella produzione commerciale. | Capacità | Punti chiave da osservare | | - | - | | Coerenza dei personaggi e dei volti | Se lineamenti, acconciatura, trucco e temperamento del personaggio restano stabili dopo il cambio di più inquadrature | | Espressione facciale | Sguardo, microespressioni, tensione emotiva e naturale movimento della testa nei primi piani | | Mantenimento della struttura del prodotto | Contorni, materiali, relazione di indossamento e riflessi speculari di prodotti come occhiali e borse | | Esecuzione visiva del brand | Se atmosfera della scena, grana cinematografica, colori, Logo e ritmo di montaggio sono coerenti | | Narrazione cinematografica | Se variazioni dell'inquadratura, messa in scena dei personaggi, movimenti di camera, ritmo e suono possono formare un segmento completo | Qui, per “capacità del volto” si intendono la coerenza dell'aspetto dei personaggi, i dettagli facciali e il controllo della recitazione nella generazione video, non il riconoscimento dell'identità, il confronto dei volti o le interfacce di sostituzione del volto. ### Cortometraggio di brand di lusso: unificazione di personaggi, prodotti e asset del brand **Obiettivo di produzione:** Filmato di brand di alta moda in 16:9. Utilizza una strada nel deserto e un'auto d'epoca per creare un'atmosfera algida, mantenendo l'aspetto della protagonista e la struttura della borsa nera, e integrando naturalmente il Logo del brand nel finale. Questo caso verifica in particolare la coerenza dei personaggi tra le inquadrature, il mantenimento del prodotto, la qualità cinematografica e la capacità di chiusura del brand. | Riferimento per atmosfera e scena | Riferimento per il personaggio | | - | - | | Riferimento per l'atmosfera del filmato di brand con strada nel deserto e auto d'epoca | Riferimento per la protagonista del filmato di brand | | Riferimento per il prodotto borsa | Riferimento per il Logo del brand | | - | - | | Riferimento per il prodotto borsa nera | Riferimento per il Logo del brand |