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

# Przewodnik integracji API zapytań o zadania MiniMax H3

> Minimax API guide - Ace Data Cloud

Ten artykuł przedstawia integrację i użycie API zapytań o zadania MiniMax H3. Ten interfejs służy do sprawdzania, zbiorczego wyświetlania lub usuwania zadań asynchronicznych utworzonych przez [API generowania wideo MiniMax H3](https://platform.acedata.cloud/documents/minimax-videos-integration).

## Proces składania wniosku

Aby używać API zapytań o zadania MiniMax H3, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go do użycia.

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

Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi cię do rejestracji i logowania; po zakończeniu automatycznie powrócisz na bieżącą stronę.

**Jeden API Token może wywoływać wszystkie usługi platformy, bez konieczności składania osobnego wniosku dla każdej usługi.** Przy pierwszym wniosku otrzymasz bezpłatny limit, aby korzystać bezpłatnie; gdy limit jest niewystarczający, możesz doładować wspólne saldo w [konsoli](https://platform.acedata.cloud/console/coin).

> 📘 Pełna dokumentacja: [API zapytań o zadania MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

Podczas sprawdzania zadania należy użyć tego samego Tokena, którym utworzono to zadanie. Zaleca się zapisanie Tokena jako zmiennej środowiskowej, nie zapisywanie go w kodzie źródłowym ani nieprzesyłanie go do repozytorium wersji:

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

## Przegląd interfejsu

* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/tasks`
* **Metoda uwierzytelniania**：w HTTP Header należy przekazać `authorization: Bearer {token}`
* **Nagłówki żądania**：
  * `accept: application/json`
  * `content-type: application/json`
* **Sprawdzanie pojedynczego zadania**：`action=retrieve`, przekaż `id`
* **Zbiorcze sprawdzanie zadań**：`action=retrieve_batch`, można filtrować według ID zadania, zakresu czasu i warunków paginacji
* **Usuwanie zadania**：`action=delete`, przekaż `id`
* **Informacje o rozliczeniu**：sprawdzanie zadań jest bezpłatne i nie spowoduje ponownego naliczenia opłat

Po utworzeniu wideo należy zapisać `task_id`. Zaleca się sprawdzanie mniej więcej co 10 sekund, aż zadanie osiągnie stan końcowy.

## Parametry żądania

| Parametr | Typ | Wymagany warunkowo | Dotycząca akcja | Opis |
| - | - | - | - | - |
| `action` | string | Nie | Wszystkie | `retrieve`, `retrieve_batch` lub `delete`; domyślnie `retrieve` |
| `id` | string | Wymagany warunkowo | `retrieve`, `delete` | ID pojedynczego zadania |
| `ids` | string\[] | Nie | `retrieve_batch` | Zwraca tylko określone ID zadań; po pominięciu wyświetla zadania według innych warunków |
| `limit` | integer | Nie | `retrieve_batch` | Maksymalna liczba zadań zwracanych tym razem |
| `offset` | integer | Nie | `retrieve_batch` | Liczba zadań pomijanych na liście wyników, używana do paginacji |
| `created_at_min` | number | Nie | `retrieve_batch` | Dolna granica czasu utworzenia, znacznik czasu Unix, w sekundach |
| `created_at_max` | number | Nie | `retrieve_batch` | Górna granica czasu utworzenia, znacznik czasu Unix, w sekundach |

Zastosowania trzech akcji są następujące:

| `action` | Zastosowanie | Wymagane parametry | Struktura odpowiedzi |
| - | - | - | - |
| `retrieve` | Sprawdza stan i wynik jednego zadania | `id` | `{ "task": {...} }` |
| `retrieve_batch` | Zbiorczo sprawdza według ID zadania, czasu i warunków paginacji | Opcjonalne `ids`, zakres czasu, `offset`, `limit` | `{ "items": [...], "total": number }` |
| `delete` | Anuluje lub usuwa rekord zadania zgodnie z bieżącym stanem zadania | `id` | `{ "id": "...", "deleted": true }` |

## Sprawdzanie pojedynczego zadania

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

Poniżej znajduje się odpowiedź rzeczywistego pomyślnie wykonanego zadania:

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

[Otwórz rzeczywisty wynik wideo tego zadania](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

## Status zadania

| `status` | Znaczenie | Obsługa klienta |
| - | - | - |
| `queued` | Zostało umieszczone w kolejce, oczekuje na wykonanie | Kontynuuj odpytywanie |
| `running` | Jest generowane | Kontynuuj odpytywanie |
| `succeeded` | Generowanie zakończone pomyślnie | Odczytaj `task.content.url`, zatrzymaj odpytywanie |
| `failed` | Generowanie nie powiodło się | Odczytaj `task.error`, zatrzymaj odpytywanie |
| `cancelled` | Zadanie zostało anulowane | Zatrzymaj odpytywanie |

`succeeded`, `failed` i `cancelled` są stanami końcowymi. Nie kontynuuj odpytywania po osiągnięciu stanu końcowego.

## Pola odpowiedzi task

| Pole | Typ | Opis |
| - | - | - |
| `id` | string | ID zadania |
| `model` | string | Model używany przez zadanie, obecnie `MiniMax-H3` |
| `status` | string | Bieżący status zadania |
| `error.code` | string | Kod błędu niepowodzenia, zwracany tylko przy niepowodzeniu |
| `error.message` | string | Przyczyna niepowodzenia, zwracana tylko przy niepowodzeniu |
| `created_at` | integer | Czas utworzenia, znacznik czasu Unix, w sekundach |
| `updated_at` | integer | Czas ostatniej aktualizacji statusu, znacznik czasu Unix, w sekundach |
| `content.url` | string | Adres wideo po powodzeniu |
| `resolution` | string | Rozdzielczość wyjściowa, `768P` lub `2K` |
| `duration` | integer | Długość wyjściowego wideo, w sekundach |
| `usage.total_seconds` | integer | Łączna ilość rozliczeniowa, równa sumie sekund wejściowego wideo i sekund wyjściowych |
| `usage.input_seconds` | integer | Ilość rozliczeniowa generowana przez wejściowe wideo referencyjne |
| `usage.output_seconds` | integer | Ilość rozliczeniowa generowana przez wyjściowe wideo |
| `usage.input_image_count` | integer | Liczba obrazów wejściowych w statystykach rozliczeniowych |
| `ratio` | string | Rzeczywisty wyjściowy współczynnik szerokości do wysokości; przy użyciu `adaptive` należy kierować się wynikiem tutaj |
| `task_type` | string | Dla zadania generowania wideo jest to `generation` |
| `modality` | string | Dla zadania wideo jest to `video` |

## Kompletny przykład odpytywania w Pythonie

Poniższy kod odczytuje Token ze zmiennych środowiskowych, tworzy zadanie, a następnie co 10 sekund wykonuje zapytanie:

```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": "Nad ranem nad morzem biała żaglówka płynie po spokojnej tafli wody, kamera powoli przesuwa się w poziomie",
            }
        ],
        "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"])
```

W środowisku produkcyjnym należy ustawić całkowity limit czasu dla odpytywania oraz stosować wykładnicze wycofywanie dla `429` i tymczasowych `5xx`. Przekroczenie limitu czasu sieciowego nie oznacza niepowodzenia generowania — można kontynuować zapytania, używając tego samego `task_id`.

## Zapytania zbiorcze

Określ wiele identyfikatorów zadań:

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

Wyświetl zadania stronicowane według zakresu czasu:

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

`items` w odpowiedzi zbiorczej używa tych samych pól task co zapytanie pojedynczego zadania, a `total` to całkowita liczba zadań spełniających kryteria filtrowania:

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

Okno zapytań o zadania obejmuje ostatnie 7 dni. `task_id` przekraczające to okno mogą zwracać nieprawidłowe zadania; system biznesowy powinien zapisywać ID podczas tworzenia zadań oraz niezwłocznie trwale zapisywać wynikowy URL po sukcesie.

## Anulowanie lub usuwanie zadań

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

Działanie zależy od bieżącego statusu zadania:

| Bieżący status | Zachowanie |
| - | - |
| `queued` | Anuluje zadanie, które jeszcze się nie rozpoczęło |
| `succeeded` | Usuwa rekord zadania |
| `failed` | Usuwa rekord zadania |
| `running` | Usuwanie lub anulowanie niedozwolone, zwraca błąd |
| `cancelled` | Ponowne działanie niedozwolone, zwraca błąd |

Przykład pomyślnego usunięcia:

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

Usunięcie rekordu zadania nie cofnie naliczonej opłaty za ukończone zadanie ani nie gwarantuje jednoczesnego usunięcia zapisanych kopii wideo.

## Odpowiedzi o błędach i rozwiązywanie problemów

Zadania zakończone niepowodzeniem nadal zwracają obiekt task z HTTP 200, a przyczyna jest podana w `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"
  }
}
```

Gdy sam interfejs zwraca `400`, należy sprawdzić `action` oraz parametry warunków; `401` oznacza nieprawidłowy Token, `429` oznacza zbyt częste zapytania, a `500` oznacza tymczasową niedostępność usługi. Zadania, których generowanie się nie powiodło, nie są płatne; dla zadań zakończonych sukcesem użycie jest naliczane zgodnie z końcowym rekordem `usage`.


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