Guida all'integrazione dell'API di interrogazione attività MiniMax H3

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.

Procedura di richiesta

Per utilizzare l’API di interrogazione attività MiniMax H3, vai prima alla console Ace Data Cloud per ottenere il tuo API Token, da conservare come backup.

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.

📘 Documentazione completa: API di interrogazione attività MiniMax H3 →

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:

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à

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:

{
  "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à

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:

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à:

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:

{
  "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:

{
  "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à

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:

{
  "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:

{
  "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.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Guida all'integrazione dell'API di interrogazione attività MiniMax H3

Procedura di richiesta

Panoramica dell’interfaccia

Parametri della richiesta

Interrogazione di una singola attività

Stato dell’attività

Campi della risposta task

Esempio completo di polling Python

Query in batch

Annullare o eliminare un’attività

Risposte di errore e diagnostica

​Procedura di richiesta

​Panoramica dell’interfaccia

​Parametri della richiesta

​Interrogazione di una singola attività

​Stato dell’attività

​Campi della risposta task

​Esempio completo di polling Python

​Query in batch

​Annullare o eliminare un’attività

​Risposte di errore e diagnostica

Procedura di richiesta

Panoramica dell’interfaccia

Parametri della richiesta

Interrogazione di una singola attività

Stato dell’attività

Campi della risposta task

Esempio completo di polling Python

Query in batch

Annullare o eliminare un’attività

Risposte di errore e diagnostica