Integrationsguide för MiniMax H3 API för uppgiftsfrågor

Den här artikeln introducerar integration och användning av MiniMax H3 API för uppgiftsfrågor. Detta gränssnitt används för att fråga, lista i batch eller ta bort asynkrona uppgifter som skapats av MiniMax H3 API för videogenerering.

Ansökningsprocess

För att använda MiniMax H3 API för uppgiftsfrågor, gå först till Ace Data Cloud-konsolen för att hämta din API-token och spara den för senare användning.

Om du ännu inte har loggat in eller registrerat dig omdirigeras du automatiskt till inloggningssidan för att registrera och logga in, och återvänder automatiskt till den aktuella sidan när det är klart. En API-token kan användas för att anropa alla plattformens tjänster, utan att behöva ansöka separat för varje tjänst. Vid första ansökan får du en kostnadsfri kvot för att prova tjänsten gratis; när kvoten är otillräcklig kan du fylla på det gemensamma saldot i konsolen.

📘 Fullständig dokumentation: MiniMax H3 API för uppgiftsfrågor →

Vid frågor om uppgifter ska samma token användas som skapade uppgiften. Vi rekommenderar att du sparar token som en miljövariabel och inte skriver in den i källkoden eller skickar den till versionsarkivet:

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

API-översikt

Base URL：https://api.acedata.cloud
Endpoint：POST /minimax/tasks
Autentiseringsmetod：Skicka authorization: Bearer {token} i HTTP Header
Begärandehuvuden：
- accept: application/json
- content-type: application/json
Fråga en enskild uppgift：action=retrieve, skicka in id
Fråga uppgifter i batch：action=retrieve_batch, kan filtrera efter uppgifts-ID, tidsintervall och pagineringsvillkor
Ta bort uppgift：action=delete, skicka in id
Faktureringsinformation：Uppgiftsfrågor är kostnadsfria och medför ingen upprepad fakturering

Efter att ha skapat en video måste du spara task_id. Vi rekommenderar att fråga ungefär var tionde sekund tills uppgiften når ett slutligt tillstånd.

Begärandeparametrar

Parameter	Typ	Obligatorisk	Tillämplig åtgärd	Beskrivning
`action`	string	Nej	Alla	`retrieve`, `retrieve_batch` eller `delete`; standardvärdet är `retrieve`
`id`	string	Villkorligt obligatorisk	`retrieve`, `delete`	ID för en enskild uppgift
`ids`	string[]	Nej	`retrieve_batch`	Returnerar endast angivna uppgifts-ID:n; om det utelämnas listas uppgifter enligt andra villkor
`limit`	integer	Nej	`retrieve_batch`	Maximalt antal uppgifter som returneras denna gång
`offset`	integer	Nej	`retrieve_batch`	Antal uppgifter som hoppas över i resultatlistan, används för paginering
`created_at_min`	number	Nej	`retrieve_batch`	Nedre gräns för skapandetid, Unix-tidsstämpel i sekunder
`created_at_max`	number	Nej	`retrieve_batch`	Övre gräns för skapandetid, Unix-tidsstämpel i sekunder

De tre åtgärdernas användningsområden är följande:

`action`	Användning	Nödvändiga parametrar	Svarsstruktur
`retrieve`	Fråga en uppgifts status och resultat	`id`	`{ "task": {...} }`
`retrieve_batch`	Fråga uppgifter i batch efter uppgifts-ID, tid och pagineringsvillkor	Valfria `ids`, tidsintervall, `offset`, `limit`	`{ "items": [...], "total": number }`
`delete`	Avbryt eller ta bort uppgiftsposten baserat på uppgiftens aktuella status	`id`	`{ "id": "...", "deleted": true }`

Fråga en enskild uppgift

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

Nedan följer svaret från en verklig lyckad uppgift:

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

Öppna det verkliga videoresultatet för denna uppgift

Uppgiftsstatus

`status`	Betydelse	Klienthantering
`queued`	Har lagts i kön och väntar på körning	Fortsätt polla
`running`	Genereras	Fortsätt polla
`succeeded`	Genereringen lyckades	Läs `task.content.url`, sluta polla
`failed`	Genereringen misslyckades	Läs `task.error`, sluta polla
`cancelled`	Uppgiften har avbrutits	Sluta polla

succeeded, failed och cancelled är alla slutliga tillstånd. Fortsätt inte polla efter att ett slutligt tillstånd har nåtts.

task-svarsfält

Fält	Typ	Beskrivning
`id`	string	Uppgifts-ID
`model`	string	Modellen som används av uppgiften, för närvarande `MiniMax-H3`
`status`	string	Aktuell uppgiftsstatus
`error.code`	string	Felkod vid misslyckande, returneras endast vid misslyckande
`error.message`	string	Orsak till misslyckande, returneras endast vid misslyckande
`created_at`	integer	Skapandetid, Unix-tidsstämpel i sekunder
`updated_at`	integer	Tidpunkt för senaste statusuppdatering, Unix-tidsstämpel i sekunder
`content.url`	string	Videoadress efter lyckad generering
`resolution`	string	Utdatakvalitet, `768P` eller `2K`
`duration`	integer	Längd på utdata-videon, i sekunder
`usage.total_seconds`	integer	Total fakturerad mängd, lika med summan av indata-videosekunder och utdata-sekunder
`usage.input_seconds`	integer	Fakturerad mängd som genereras av referensvideoindata
`usage.output_seconds`	integer	Fakturerad mängd som genereras av utdata-video
`usage.input_image_count`	integer	Antal indatabilder i faktureringsstatistiken
`ratio`	string	Faktiskt utdata-bredd/höjd-förhållande; när `adaptive` används gäller resultatet här
`task_type`	string	Videogenereringsuppgifter är `generation`
`modality`	string	Videouppgifter är `video`

Fullständigt exempel på Python-pollning

Följande kod läser Token från miljövariabeln, skapar en uppgift och frågar sedan en gång var 10:e sekund:

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

I produktionsmiljö bör en total timeout ställas in för pollning, och exponentiell backoff användas för 429 och tillfälliga 5xx. Nätverkstimeout är inte detsamma som att genereringen misslyckats; du kan fortsätta fråga med samma task_id.

Batchfråga

Ange flera uppgifts-ID:n:

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

Lista uppgifter sidvis efter tidsintervall:

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

items i batchsvaret använder samma task-fält som enskild uppgiftsfråga, och total är det totala antalet uppgifter som matchar filtreringsvillkoren:

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

Fönstret för uppgiftsfrågor är de senaste 7 dagarna. task_id som överskrider detta fönster kan returnera en ogiltig uppgift; verksamhetssystemet bör spara ID:t när uppgiften skapas och i god tid beständigt lagra resultat-URL:en efter lyckat resultat.

Avbryt eller ta bort uppgift

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

Åtgärden beror på uppgiftens aktuella status:

Aktuell status	Beteende
`queued`	Avbryt uppgift som ännu inte har startat
`succeeded`	Ta bort uppgiftspost
`failed`	Ta bort uppgiftspost
`running`	Borttagning eller avbrott tillåts inte, returnerar fel
`cancelled`	Upprepad åtgärd tillåts inte, returnerar fel

Exempel på lyckad borttagning:

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

Att ta bort en uppgiftspost återkallar inte redan genomförd debitering och kan inte garantera att sparade videokopior tas bort samtidigt.

Felrespons och felsökning

Misslyckade uppgifter returnerar fortfarande task-objektet med HTTP 200, och orsaken anges i 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"
  }
}

När själva gränssnittet returnerar 400 bör action och villkorsparametrarna kontrolleras, 401 betyder att Token är ogiltig, 429 betyder att frågorna är för frekventa, och 500 betyder att tjänsten tillfälligt inte är tillgänglig. Uppgifter där genereringen misslyckas debiteras inte; lyckade uppgifter registrerar användning enligt slutlig usage.

Getting Started

AI Samtal

AI Bild

AI Video

AI Ljud

Web & Data

CAPTCHA

Identitet

Coding

Fler guider

Integrationsguide för MiniMax H3 API för uppgiftsfrågor

Ansökningsprocess

API-översikt

Begärandeparametrar

Fråga en enskild uppgift

Uppgiftsstatus

task-svarsfält

Fullständigt exempel på Python-pollning

Batchfråga

Avbryt eller ta bort uppgift

Felrespons och felsökning

​Ansökningsprocess

​API-översikt

​Begärandeparametrar

​Fråga en enskild uppgift

​Uppgiftsstatus

​task-svarsfält

​Fullständigt exempel på Python-pollning

​Batchfråga

​Avbryt eller ta bort uppgift

​Felrespons och felsökning

Ansökningsprocess

API-översikt

Begärandeparametrar

Fråga en enskild uppgift

Uppgiftsstatus

task-svarsfält

Fullständigt exempel på Python-pollning

Batchfråga

Avbryt eller ta bort uppgift

Felrespons och felsökning