> ## 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 interrogazione attività MiniMax H3 > Minimax API guide - Ace Data Cloud Questo documento presenta l'integrazione e l'utilizzo dell'API di interrogazione attività MiniMax H3. Questa interfaccia viene utilizzata per interrogare, elencare in batch o eliminare le attività asincrone create dall'[API di generazione video MiniMax H3](https://platform.acedata.cloud/documents/minimax-videos-integration). ## Procedura di richiesta Per utilizzare l'API di interrogazione attività MiniMax H3, vai prima alla [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare come backup. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e accedere; al termine tornerai automaticamente alla pagina corrente. **Un solo API Token può chiamare tutti i servizi della piattaforma, senza necessità di richiederne uno separatamente per ogni servizio.** La prima richiesta include una quota gratuita, che consente di provarlo gratuitamente; quando la quota è insufficiente, puoi ricaricare il saldo universale dalla [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [API di interrogazione attività MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-tasks-integration) Durante l'interrogazione di un'attività, deve essere utilizzato lo stesso Token che ha creato l'attività. Si consiglia di salvare il Token come variabile d'ambiente e di non 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/tasks` * **Metodo di autenticazione**：includere `authorization: Bearer {token}` nell'HTTP Header * **Header della richiesta**： * `accept: application/json` * `content-type: application/json` * **Interrogazione di una singola attività**：`action=retrieve`, passare `id` * **Interrogazione batch delle attività**：`action=retrieve_batch`, può filtrare per ID attività, intervallo temporale e condizioni di paginazione * **Eliminazione attività**：`action=delete`, passare `id` * **Informazioni sulla fatturazione**：l'interrogazione delle attività è gratuita e non genera addebiti duplicati Dopo aver creato un video, è necessario salvare `task_id`. Si consiglia di eseguire un'interrogazione circa ogni 10 secondi, fino a quando l'attività non entra in uno stato terminale. ## Parametri della richiesta | Parametro | Tipo | Obbligatorio | Azioni applicabili | Descrizione | | - | - | - | - | - | | `action` | string | No | Tutte | `retrieve`, `retrieve_batch` o `delete`; predefinito `retrieve` | | `id` | string | Obbligatorio condizionale | `retrieve`, `delete` | ID di una singola attività | | `ids` | string\[] | No | `retrieve_batch` | Restituisce solo gli ID attività specificati; se omesso, elenca le attività secondo altre condizioni | | `limit` | integer | No | `retrieve_batch` | Numero massimo di attività restituite in questa richiesta | | `offset` | integer | No | `retrieve_batch` | Numero di attività da saltare nell'elenco dei risultati, utilizzato per la paginazione | | `created_at_min` | number | No | `retrieve_batch` | Limite inferiore del tempo di creazione, timestamp Unix, in secondi | | `created_at_max` | number | No | `retrieve_batch` | Limite superiore del tempo di creazione, timestamp Unix, in secondi | Gli utilizzi delle tre azioni sono i seguenti: | `action` | Utilizzo | Parametri necessari | Struttura della risposta | | - | - | - | - | | `retrieve` | Interroga lo stato e il risultato di un'attività | `id` | `{ "task": {...} }` | | `retrieve_batch` | Interrogazione batch per ID attività, tempo e condizioni di paginazione | `ids` facoltativo, intervallo temporale, `offset`, `limit` | `{ "items": [...], "total": number }` | | `delete` | Annulla o elimina il record dell'attività in base allo stato corrente dell'attività | `id` | `{ "id": "...", "deleted": true }` | ## Interrogazione di una singola attività ```bash theme={null} curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "action": "retrieve", "id": "f5977217-ed2c-40da-adbe-93d08235618f" }' ``` Di seguito è riportata la risposta di un'attività reale completata con successo: ```json theme={null} { "task": { "id": "f5977217-ed2c-40da-adbe-93d08235618f", "model": "MiniMax-H3", "status": "succeeded", "created_at": 1786184658, "updated_at": 1786184758, "content": { "url": "https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4" }, "resolution": "768P", "duration": 4, "usage": { "total_seconds": 4, "input_seconds": 0, "output_seconds": 4, "input_image_count": 0 }, "ratio": "16:9", "task_type": "generation", "modality": "video" } } ``` [Apri il risultato video reale di questa attività](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4) ## Stato dell'attività | `status` | Significato | Gestione del client | | - | - | - | | `queued` | È entrata in coda, in attesa di esecuzione | Continua il polling | | `running` | Generazione in corso | Continua il polling | | `succeeded` | Generazione riuscita | Leggi `task.content.url`, interrompi il polling | | `failed` | Generazione non riuscita | Leggi `task.error`, interrompi il polling | | `cancelled` | Attività annullata | Interrompi il polling | `succeeded`, `failed` e `cancelled` sono tutti stati terminali. Non continuare il polling dopo l'ingresso in uno stato terminale. ## Campi della risposta task | Campo | Tipo | Descrizione | | - | - | - | | `id` | string | ID attività | | `model` | string | Modello utilizzato dall'attività, attualmente `MiniMax-H3` | | `status` | string | Stato attuale dell'attività | | `error.code` | string | Codice di errore del fallimento, restituito solo in caso di fallimento | | `error.message` | string | Motivo del fallimento, restituito solo in caso di fallimento | | `created_at` | integer | Ora di creazione, timestamp Unix, in secondi | | `updated_at` | integer | Ora dell'ultimo aggiornamento dello stato, timestamp Unix, in secondi | | `content.url` | string | Indirizzo del video dopo il completamento con successo | | `resolution` | string | Risoluzione di output, `768P` o `2K` | | `duration` | integer | Durata del video di output, in secondi | | `usage.total_seconds` | integer | Quantità totale fatturata, pari alla somma dei secondi del video di input e dei secondi di output | | `usage.input_seconds` | integer | Quantità fatturata generata dall'input del video di riferimento | | `usage.output_seconds` | integer | Quantità fatturata generata dal video di output | | `usage.input_image_count` | integer | Numero di immagini di input nelle statistiche di fatturazione | | `ratio` | string | Rapporto larghezza-altezza effettivo dell'output; quando si utilizza `adaptive`, fare riferimento al risultato qui indicato | | `task_type` | string | Per le attività di generazione video è `generation` | | `modality` | string | Per le attività video è `video` | ## Esempio completo di polling Python Il codice seguente legge il Token dalla variabile d'ambiente e, dopo aver creato un'attività, esegue una query ogni 10 secondi: ```python theme={null} import os import time import requests BASE_URL = "https://api.acedata.cloud" HEADERS = { "Authorization": f"Bearer {os.environ['ACEDATACLOUD_API_KEY']}", "Content-Type": "application/json", } create_response = requests.post( f"{BASE_URL}/minimax/videos", headers=HEADERS, json={ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "清晨的海边，一艘白色帆船驶过平静海面，镜头缓慢横移", } ], "resolution": "768P", "duration": 4, "ratio": "16:9", }, timeout=30, ) create_response.raise_for_status() task_id = create_response.json()["task_id"] while True: time.sleep(10) query_response = requests.post( f"{BASE_URL}/minimax/tasks", headers=HEADERS, json={"action": "retrieve", "id": task_id}, timeout=30, ) query_response.raise_for_status() task = query_response.json()["task"] print(f"task={task_id} status={task['status']}") if task["status"] == "succeeded": print(f"video_url={task['content']['url']}") break if task["status"] in ("failed", "cancelled"): raise RuntimeError(task.get("error") or task["status"]) ``` In ambiente di produzione, è necessario impostare un timeout totale per il polling e utilizzare il backoff esponenziale per `429` e i `5xx` temporanei. Un timeout di rete non equivale a un errore di generazione; è possibile continuare a eseguire query usando lo stesso `task_id`. ## Query in batch Specificare più ID attività: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "action": "retrieve_batch", "ids": ["TASK_ID_1", "TASK_ID_2"], "offset": 0, "limit": 20 }' ``` Elencare le attività per pagine in base all'intervallo temporale: ```json theme={null} { "action": "retrieve_batch", "created_at_min": 1786000000, "created_at_max": 1786200000, "offset": 0, "limit": 20 } ``` Gli `items` nella risposta batch utilizzano gli stessi campi task della query di una singola attività, e `total` è il numero totale di attività corrispondenti ai criteri di filtro: ```json theme={null} { "items": [ { "id": "TASK_ID_1", "model": "MiniMax-H3", "status": "running", "resolution": "2K", "duration": 5, "ratio": "adaptive", "task_type": "generation", "modality": "video" } ], "total": 1 } ``` La finestra di query delle attività copre gli ultimi 7 giorni. I `task_id` oltre questa finestra potrebbero restituire attività non valide; il sistema aziendale deve salvare l'ID al momento della creazione dell'attività e rendere persistente tempestivamente l'URL del risultato dopo il successo. ## Annullare o eliminare un'attività ```bash theme={null} curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "action": "delete", "id": "YOUR_TASK_ID" }' ``` L'azione dipende dallo stato corrente dell'attività: | Stato corrente | Comportamento | | - | - | | `queued` | Annulla l'attività non ancora avviata | | `succeeded` | Elimina il record dell'attività | | `failed` | Elimina il record dell'attività | | `running` | Non è consentito eliminare o annullare, restituisce un errore | | `cancelled` | Non è consentito ripetere l'operazione, restituisce un errore | Esempio di eliminazione riuscita: ```json theme={null} { "id": "YOUR_TASK_ID", "deleted": true } ``` L'eliminazione del record dell'attività non annulla la fatturazione già completata e non può garantire che anche le copie video già salvate vengano eliminate. ## Risposte di errore e diagnostica Le attività non riuscite restituiscono comunque un oggetto task con HTTP 200 e forniscono il motivo in `task.error`: ```json theme={null} { "task": { "id": "YOUR_TASK_ID", "model": "MiniMax-H3", "status": "failed", "error": { "code": "1026", "message": "video description contains sensitive content" }, "task_type": "generation", "modality": "video" } } ``` Quando l'interfaccia stessa restituisce `400`, è necessario controllare `action` e i parametri delle condizioni; `401` indica che il Token non è valido, `429` indica che le query sono troppo frequenti e `500` indica che il servizio è temporaneamente non disponibile. Le attività con generazione non riuscita non vengono fatturate; per le attività riuscite, l'utilizzo viene registrato in base al `usage` finale. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.