Przewodnik integracji API zapytań o zadania MiniMax H3

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.

Proces składania wniosku

Aby używać API zapytań o zadania MiniMax H3, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go do użycia.

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.

📘 Pełna dokumentacja: API zapytań o zadania MiniMax H3 →

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:

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

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:

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

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:

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

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:

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

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

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:

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

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

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Przewodnik integracji API zapytań o zadania MiniMax H3

Proces składania wniosku

Przegląd interfejsu

Parametry żądania

Sprawdzanie pojedynczego zadania

Status zadania

Pola odpowiedzi task

Kompletny przykład odpytywania w Pythonie

Zapytania zbiorcze

Anulowanie lub usuwanie zadań

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

​Proces składania wniosku

​Przegląd interfejsu

​Parametry żądania

​Sprawdzanie pojedynczego zadania

​Status zadania

​Pola odpowiedzi task

​Kompletny przykład odpytywania w Pythonie

​Zapytania zbiorcze

​Anulowanie lub usuwanie zadań

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

Proces składania wniosku

Przegląd interfejsu

Parametry żądania

Sprawdzanie pojedynczego zadania

Status zadania

Pola odpowiedzi task

Kompletny przykład odpytywania w Pythonie

Zapytania zbiorcze

Anulowanie lub usuwanie zadań

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