> ## 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.

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

> Minimax API guide - Ace Data Cloud

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](https://platform.acedata.cloud/documents/minimax-videos-integration).

## 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](https://platform.acedata.cloud/console/applications), à conserver en réserve.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [API de requête de tâches MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

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 :

```bash theme={null}
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

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

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

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

[Ouvrir le résultat vidéo réel de cette tâche](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

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

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

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 :

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

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

```json theme={null}
{
  "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 :

```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 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

```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’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 :

```json theme={null}
{
  "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` :

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

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.