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

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

> Minimax API guide - Ace Data Cloud

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

## Ansökningsprocess

För att använda MiniMax H3 API för uppgiftsfrågor, gå först till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API-token och spara den för senare användning.

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

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

> 📘 Fullständig dokumentation: [MiniMax H3 API för uppgiftsfrågor →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

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:

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

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

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

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

[Öppna det verkliga videoresultatet för denna uppgift](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

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

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

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:

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

Lista uppgifter sidvis efter tidsintervall:

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

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

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

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

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

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

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

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


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