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

# Leitfaden zur Integration der MiniMax H3 Task-Abfrage-API

> Minimax API guide - Ace Data Cloud

Dieser Artikel stellt die Integration und Verwendung der MiniMax H3 Task-Abfrage-API vor. Diese Schnittstelle wird verwendet, um asynchrone Aufgaben abzufragen, stapelweise aufzulisten oder zu löschen, die von der [MiniMax H3 Videoerzeugungs-API](https://platform.acedata.cloud/documents/minimax-videos-integration) erstellt wurden.

## Antragsprozess

Um die MiniMax H3 Task-Abfrage-API zu verwenden, rufen Sie zunächst in der [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) Ihren API-Token ab und bewahren Sie ihn zur späteren Verwendung auf.

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

Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück.

**Ein API-Token kann alle Dienste der Plattform aufrufen; es ist nicht erforderlich, jeden Dienst separat zu beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben, mit dem Sie den Dienst kostenlos testen können; bei unzureichendem Guthaben können Sie das allgemeine Guthaben in der [Konsole](https://platform.acedata.cloud/console/coin) aufladen.

> 📘 Vollständige Dokumentation: [MiniMax H3 Task-Abfrage-API →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

Beim Abfragen einer Aufgabe sollte derselbe Token verwendet werden, mit dem diese Aufgabe erstellt wurde. Es wird empfohlen, den Token als Umgebungsvariable zu speichern und ihn nicht in den Quellcode zu schreiben oder in ein Repository zu übertragen:

```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```

## Schnittstellenübersicht

* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/tasks`
* **Authentifizierungsmethode**：`authorization: Bearer {token}` im HTTP-Header
* **Request-Header**：
  * `accept: application/json`
  * `content-type: application/json`
* **Einzelne Aufgabe abfragen**：`action=retrieve`, `id` übergeben
* **Aufgaben stapelweise abfragen**：`action=retrieve_batch`, kann nach Aufgaben-ID, Zeitraum und Paginierungsbedingungen filtern
* **Aufgabe löschen**：`action=delete`, `id` übergeben
* **Abrechnungshinweis**：Die Aufgabenabfrage ist kostenlos und verursacht keine wiederholte Abrechnung

Nach der Videoerstellung muss die `task_id` gespeichert werden. Es wird empfohlen, etwa alle 10 Sekunden abzufragen, bis die Aufgabe einen Endzustand erreicht.

## Request-Parameter

| Parameter | Typ | Erforderlich | Gültige Aktion | Beschreibung |
| - | - | - | - | - |
| `action` | string | Nein | Alle | `retrieve`, `retrieve_batch` oder `delete`; Standard ist `retrieve` |
| `id` | string | Bedingt erforderlich | `retrieve`, `delete` | Einzelne Aufgaben-ID |
| `ids` | string\[] | Nein | `retrieve_batch` | Gibt nur die angegebenen Aufgaben-IDs zurück; wenn ausgelassen, werden Aufgaben nach anderen Bedingungen aufgelistet |
| `limit` | integer | Nein | `retrieve_batch` | Maximale Anzahl der in diesem Aufruf zurückgegebenen Aufgaben |
| `offset` | integer | Nein | `retrieve_batch` | Anzahl der aus der Ergebnisliste übersprungenen Aufgaben, für die Paginierung |
| `created_at_min` | number | Nein | `retrieve_batch` | Untergrenze der Erstellungszeit, Unix-Zeitstempel in Sekunden |
| `created_at_max` | number | Nein | `retrieve_batch` | Obergrenze der Erstellungszeit, Unix-Zeitstempel in Sekunden |

Die Verwendungszwecke der drei Aktionen sind wie folgt:

| `action` | Zweck | Erforderliche Parameter | Antwortstruktur |
| - | - | - | - |
| `retrieve` | Status und Ergebnis einer Aufgabe abfragen | `id` | `{ "task": {...} }` |
| `retrieve_batch` | Stapelweise Abfrage nach Aufgaben-ID, Zeit und Paginierungsbedingungen | Optionale `ids`, Zeitraum, `offset`, `limit` | `{ "items": [...], "total": number }` |
| `delete` | Aufgabenaufzeichnung entsprechend dem aktuellen Aufgabenstatus abbrechen oder löschen | `id` | `{ "id": "...", "deleted": true }` |

## Einzelne Aufgabe abfragen

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

Nachfolgend sehen Sie die Antwort einer tatsächlich erfolgreich abgeschlossenen Aufgabe:

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

[Das tatsächliche Videoergebnis dieser Aufgabe öffnen](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

## Aufgabenstatus

| `status` | Bedeutung | Verarbeitung durch den Client |
| - | - | - |
| `queued` | In die Warteschlange eingereiht, wartet auf Ausführung | Weiter abfragen |
| `running` | Wird gerade generiert | Weiter abfragen |
| `succeeded` | Erfolgreich generiert | `task.content.url` lesen, Abfrage beenden |
| `failed` | Generierung fehlgeschlagen | `task.error` lesen, Abfrage beenden |
| `cancelled` | Aufgabe wurde abgebrochen | Abfrage beenden |

`succeeded`, `failed` und `cancelled` sind alles Endzustände. Fragen Sie nicht weiter ab, nachdem ein Endzustand erreicht wurde.

## task-Antwortfelder

| Feld | Typ | Beschreibung |
| - | - | - |
| `id` | string | Aufgaben-ID |
| `model` | string | Von der Aufgabe verwendetes Modell, derzeit `MiniMax-H3` |
| `status` | string | Aktueller Aufgabenstatus |
| `error.code` | string | Fehlercode bei Fehlschlag, wird nur bei Fehlschlag zurückgegeben |
| `error.message` | string | Fehlerursache, wird nur bei Fehlschlag zurückgegeben |
| `created_at` | integer | Erstellungszeit, Unix-Zeitstempel in Sekunden |
| `updated_at` | integer | Zeitpunkt der letzten Statusaktualisierung, Unix-Zeitstempel in Sekunden |
| `content.url` | string | Video-URL nach erfolgreicher Erstellung |
| `resolution` | string | Ausgabeauflösung, `768P` oder `2K` |
| `duration` | integer | Dauer des Ausgabevideos in Sekunden |
| `usage.total_seconds` | integer | Gesamte abrechenbare Menge, entspricht der Summe aus Eingabevideo-Sekunden und Ausgabe-Sekunden |
| `usage.input_seconds` | integer | Abrechenbare Menge, die durch die Referenzvideo-Eingabe entsteht |
| `usage.output_seconds` | integer | Abrechenbare Menge, die durch das Ausgabevideo entsteht |
| `usage.input_image_count` | integer | Anzahl der Eingabebilder in der Abrechnungsstatistik |
| `ratio` | string | Tatsächliches Ausgabe-Seitenverhältnis; bei Verwendung von `adaptive` ist dieses Ergebnis maßgeblich |
| `task_type` | string | Für Videoerstellungsaufgaben `generation` |
| `modality` | string | Für Videoaufgaben `video` |

## Vollständiges Python-Polling-Beispiel

Der folgende Code liest das Token aus der Umgebungsvariable, erstellt eine Aufgabe und fragt dann alle 10 Sekunden einmal ab:

```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 der Produktionsumgebung sollte für das Polling ein Gesamttimeout festgelegt und für `429` sowie temporäre `5xx` ein exponentielles Backoff verwendet werden. Netzwerk-Timeouts sind nicht gleichbedeutend mit einem fehlgeschlagenen Generierungsvorgang; Sie können mit derselben `task_id` weiter abfragen.

## Stapelabfrage

Mehrere Aufgaben-IDs angeben:

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

Aufgaben nach Zeitbereich paginiert auflisten:

```json theme={null}
{
  "action": "retrieve_batch",
  "created_at_min": 1786000000,
  "created_at_max": 1786200000,
  "offset": 0,
  "limit": 20
}
```

Die `items` in der Stapelantwort verwenden dieselben task-Felder wie die Einzelaufgabenabfrage, und `total` ist die Gesamtzahl der Aufgaben, die den Filterbedingungen entsprechen:

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

Das Abfragefenster für Aufgaben beträgt die letzten 7 Tage. `task_id` außerhalb dieses Fensters können möglicherweise ungültige Aufgaben zurückgeben; Geschäftssysteme sollten die ID beim Erstellen einer Aufgabe speichern und die Ergebnis-URL nach Erfolg zeitnah dauerhaft speichern.

## Aufgabe abbrechen oder löschen

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

Die Aktion hängt vom aktuellen Status der Aufgabe ab:

| Aktueller Status | Verhalten |
| - | - |
| `queued` | Bricht eine noch nicht gestartete Aufgabe ab |
| `succeeded` | Löscht den Aufgabeneintrag |
| `failed` | Löscht den Aufgabeneintrag |
| `running` | Löschen oder Abbrechen nicht erlaubt, gibt einen Fehler zurück |
| `cancelled` | Wiederholte Aktion nicht erlaubt, gibt einen Fehler zurück |

Beispiel für erfolgreiches Löschen:

```json theme={null}
{
  "id": "YOUR_TASK_ID",
  "deleted": true
}
```

Das Löschen eines Aufgabeneintrags widerruft keine bereits abgeschlossene Abrechnung und kann nicht garantieren, dass gleichzeitig gespeicherte Videokopien gelöscht werden.

## Fehlerantworten und Fehlerbehebung

Fehlgeschlagene Aufgaben geben weiterhin ein task-Objekt mit HTTP 200 zurück und nennen den Grund 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"
  }
}
```

Wenn die Schnittstelle selbst `400` zurückgibt, sollten `action` und die Bedingungsparameter überprüft werden; `401` bedeutet, dass das Token ungültig ist, `429` bedeutet, dass die Abfrage zu häufig erfolgt, und `500` bedeutet, dass der Dienst vorübergehend nicht verfügbar ist. Aufgaben mit fehlgeschlagener Generierung werden nicht abgerechnet; erfolgreiche Aufgaben erfassen die Nutzung gemäß der endgültigen `usage`.


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