Leitfaden zur Integration der MiniMax H3 Task-Abfrage-API

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 erstellt wurden.

Antragsprozess

Um die MiniMax H3 Task-Abfrage-API zu verwenden, rufen Sie zunächst in der Ace Data Cloud-Konsole Ihren API-Token ab und bewahren Sie ihn zur späteren Verwendung auf.

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

📘 Vollständige Dokumentation: MiniMax H3 Task-Abfrage-API →

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:

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

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:

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

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:

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:

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:

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

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

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:

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

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

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

Leitfaden zur Integration der MiniMax H3 Task-Abfrage-API

Antragsprozess

Schnittstellenübersicht

Request-Parameter

Einzelne Aufgabe abfragen

Aufgabenstatus

task-Antwortfelder

Vollständiges Python-Polling-Beispiel

Stapelabfrage

Aufgabe abbrechen oder löschen

Fehlerantworten und Fehlerbehebung

​Antragsprozess

​Schnittstellenübersicht

​Request-Parameter

​Einzelne Aufgabe abfragen

​Aufgabenstatus

​task-Antwortfelder

​Vollständiges Python-Polling-Beispiel

​Stapelabfrage

​Aufgabe abbrechen oder löschen

​Fehlerantworten und Fehlerbehebung

Antragsprozess

Schnittstellenübersicht

Request-Parameter

Einzelne Aufgabe abfragen

Aufgabenstatus

task-Antwortfelder

Vollständiges Python-Polling-Beispiel

Stapelabfrage

Aufgabe abbrechen oder löschen

Fehlerantworten und Fehlerbehebung