Guide d'intégration de l'API de requête de tâches MiniMax H3

Cet article présente l’intégration et l’utilisation de l’API de requête de tâches MiniMax H3. Cette interface est utilisée pour interroger, lister par lots ou supprimer les tâches asynchrones créées par l’API de génération vidéo MiniMax H3.

Processus de demande

Pour utiliser l’API de requête de tâches MiniMax H3, commencez par obtenir votre API Token dans la console Ace Data Cloud, à conserver en réserve.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion qui vous invitera à vous inscrire et à vous connecter ; une fois cela fait, vous reviendrez automatiquement à la page actuelle. Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service. La première demande offre un quota gratuit permettant une utilisation d’essai gratuite ; lorsque le quota est insuffisant, vous pouvez recharger le solde commun dans la console.

📘 Documentation complète : API de requête de tâches MiniMax H3 →

Lors de la requête d’une tâche, vous devez utiliser le même Token que celui ayant créé cette tâche. Il est recommandé de sauvegarder le Token comme variable d’environnement, sans l’écrire dans le code source ni le soumettre au dépôt de versions :

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

Vue d’ensemble de l’interface

Base URL：https://api.acedata.cloud
Endpoint：POST /minimax/tasks
Méthode d’authentification：inclure authorization: Bearer {token} dans le HTTP Header
En-têtes de requête：
- accept: application/json
- content-type: application/json
Requête d’une tâche unique：action=retrieve, transmettre id
Requête de tâches par lots：action=retrieve_batch, filtrage possible par ID de tâche, plage temporelle et conditions de pagination
Suppression d’une tâche：action=delete, transmettre id
Informations de facturation：la requête de tâches est gratuite et n’entraîne aucune facturation répétée

Après avoir créé une vidéo, vous devez sauvegarder le task_id. Il est recommandé d’effectuer une requête environ toutes les 10 secondes, jusqu’à ce que la tâche entre dans un état terminal.

Paramètres de requête

Paramètre	Type	Obligatoire sous condition	Actions applicables	Description
`action`	string	Non	Toutes	`retrieve`, `retrieve_batch` ou `delete` ; valeur par défaut : `retrieve`
`id`	string	Obligatoire sous condition	`retrieve`, `delete`	ID d’une tâche unique
`ids`	string[]	Non	`retrieve_batch`	Retourne uniquement les ID de tâche spécifiés ; si omis, liste les tâches selon les autres conditions
`limit`	integer	Non	`retrieve_batch`	Nombre maximal de tâches retournées cette fois-ci
`offset`	integer	Non	`retrieve_batch`	Nombre de tâches à ignorer dans la liste des résultats, utilisé pour la pagination
`created_at_min`	number	Non	`retrieve_batch`	Limite inférieure de l’heure de création, horodatage Unix, en secondes
`created_at_max`	number	Non	`retrieve_batch`	Limite supérieure de l’heure de création, horodatage Unix, en secondes

Les utilisations des trois actions sont les suivantes :

`action`	Utilisation	Paramètres nécessaires	Structure de réponse
`retrieve`	Interroger le statut et le résultat d’une tâche	`id`	`{ "task": {...} }`
`retrieve_batch`	Interroger des tâches par lots selon l’ID, le temps et les conditions de pagination	`ids`, plage temporelle, `offset`, `limit` facultatifs	`{ "items": [...], "total": number }`
`delete`	Annuler ou supprimer l’enregistrement d’une tâche selon son statut actuel	`id`	`{ "id": "...", "deleted": true }`

Requête d’une tâche unique

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"
  }'

Voici la réponse d’une véritable tâche réussie :

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

Ouvrir le résultat vidéo réel de cette tâche

Statuts des tâches

`status`	Signification	Traitement côté client
`queued`	Entrée dans la file d’attente, en attente d’exécution	Continuer le polling
`running`	Génération en cours	Continuer le polling
`succeeded`	Génération réussie	Lire `task.content.url`, arrêter le polling
`failed`	Échec de la génération	Lire `task.error`, arrêter le polling
`cancelled`	Tâche annulée	Arrêter le polling

succeeded, failed et cancelled sont tous des états terminaux. Ne continuez pas le polling après l’entrée dans un état terminal.

Champs de réponse task

Champ	Type	Description
`id`	string	ID de la tâche
`model`	string	Modèle utilisé par la tâche, actuellement `MiniMax-H3`
`status`	string	Statut actuel de la tâche
`error.code`	string	Code d’erreur d’échec, retourné uniquement en cas d’échec
`error.message`	string	Raison de l’échec, retournée uniquement en cas d’échec
`created_at`	integer	Heure de création, horodatage Unix, en secondes
`updated_at`	integer	Heure de la dernière mise à jour du statut, horodatage Unix, en secondes
`content.url`	string	Adresse de la vidéo après réussite
`resolution`	string	Résolution de sortie, `768P` ou `2K`
`duration`	integer	Durée de la vidéo de sortie, en secondes
`usage.total_seconds`	integer	Volume total facturé, égal à la somme des secondes de vidéo d’entrée et de sortie
`usage.input_seconds`	integer	Volume facturé généré par l’entrée de vidéo de référence
`usage.output_seconds`	integer	Volume facturé généré par la vidéo de sortie
`usage.input_image_count`	integer	Nombre d’images d’entrée dans les statistiques de facturation
`ratio`	string	Ratio largeur-hauteur réel de sortie ; lors de l’utilisation de `adaptive`, le résultat ici prévaut
`task_type`	string	Les tâches de génération vidéo utilisent `generation`
`modality`	string	Les tâches vidéo utilisent `video`

Exemple complet de polling Python

Le code suivant lit le Token depuis les variables d’environnement, crée une tâche puis effectue une requête toutes les 10 secondes :

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"])

L’environnement de production doit définir un délai d’expiration total pour le polling et utiliser un backoff exponentiel pour les 429 et les 5xx temporaires. Un délai d’expiration réseau ne signifie pas que la génération a échoué ; vous pouvez continuer à interroger avec le même task_id.

Requête par lots

Spécifiez plusieurs ID de tâches :

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
  }'

Listez les tâches par pagination selon une plage temporelle :

{
  "action": "retrieve_batch",
  "created_at_min": 1786000000,
  "created_at_max": 1786200000,
  "offset": 0,
  "limit": 20
}

Les items dans la réponse par lots utilisent les mêmes champs task que la requête d’une tâche unique, et total correspond au nombre total de tâches correspondant aux critères de filtrage :

{
  "items": [
    {
      "id": "TASK_ID_1",
      "model": "MiniMax-H3",
      "status": "running",
      "resolution": "2K",
      "duration": 5,
      "ratio": "adaptive",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}

La fenêtre de requête des tâches couvre les 7 derniers jours. Les task_id au-delà de cette fenêtre peuvent renvoyer une tâche non valide ; le système métier doit enregistrer l’ID lors de la création de la tâche et persister rapidement l’URL du résultat après le succès.

Annuler ou supprimer une tâche

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’action dépend de l’état actuel de la tâche :

État actuel	Comportement
`queued`	Annule une tâche qui n’a pas encore commencé
`succeeded`	Supprime l’enregistrement de la tâche
`failed`	Supprime l’enregistrement de la tâche
`running`	La suppression ou l’annulation n’est pas autorisée, renvoie une erreur
`cancelled`	Les opérations répétées ne sont pas autorisées, renvoie une erreur

Exemple de suppression réussie :

{
  "id": "YOUR_TASK_ID",
  "deleted": true
}

La suppression d’un enregistrement de tâche n’annule pas la facturation déjà effectuée et ne garantit pas que les copies de vidéo déjà sauvegardées soient supprimées en même temps.

Réponses d’échec et dépannage

Les tâches ayant échoué renvoient toujours un objet task avec HTTP 200, et la raison est fournie dans 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"
  }
}

Lorsque l’interface elle-même renvoie 400, vérifiez action et les paramètres de condition ; 401 indique que le Token est invalide, 429 indique que les requêtes sont trop fréquentes, et 500 indique que le service est temporairement indisponible. Les tâches dont la génération échoue ne sont pas facturées ; les tâches réussies enregistrent l’utilisation selon le usage final.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Guide d'intégration de l'API de requête de tâches MiniMax H3

Processus de demande

Vue d’ensemble de l’interface

Paramètres de requête

Requête d’une tâche unique

Statuts des tâches

Champs de réponse task

Exemple complet de polling Python

Requête par lots

Annuler ou supprimer une tâche

Réponses d’échec et dépannage

​Processus de demande

​Vue d’ensemble de l’interface

​Paramètres de requête

​Requête d’une tâche unique

​Statuts des tâches

​Champs de réponse task

​Exemple complet de polling Python

​Requête par lots

​Annuler ou supprimer une tâche

​Réponses d’échec et dépannage

Processus de demande

Vue d’ensemble de l’interface

Paramètres de requête

Requête d’une tâche unique

Statuts des tâches

Champs de réponse task

Exemple complet de polling Python

Requête par lots

Annuler ou supprimer une tâche

Réponses d’échec et dépannage