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

# Instrukcja integracji API zapytań o zadania Maestro

> Maestro AI Video Studio API guide - Ace Data Cloud

Główną funkcją API zapytań o zadania Maestro jest sprawdzanie statusu wykonania i końcowego wyniku zadania na podstawie identyfikatora zadania zwróconego przez [API generowania wideo Maestro](/pl/guides/maestro/maestro_videos) (`POST /maestro/videos`).

Ten dokument szczegółowo przedstawia instrukcję integracji API zapytań o zadania Maestro. Ponieważ generowanie wideo jest zadaniem asynchronicznym, po przesłaniu należy użyć tego interfejsu do odpytywania w celu uzyskania postępu i gotowego filmu, **odpytywanie jest bezpłatne i nie zużywa punktów.**

`POST https://api.acedata.cloud/maestro/tasks`

## Proces aplikowania

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

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

Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, nastąpi automatyczne przekierowanie na stronę logowania z zaproszeniem do rejestracji i logowania, a po ukończeniu automatycznie wrócisz na bieżącą stronę.

**Jeden API Token umożliwia wywoływanie wszystkich usług platformy, nie ma potrzeby osobnego aplikowania dla każdej usługi.** Przy pierwszej aplikacji otrzymasz bezpłatny limit, aby korzystać z bezpłatnego okresu próbnego; gdy limit jest niewystarczający, możesz doładować uniwersalne saldo w [konsoli](https://platform.acedata.cloud/console/coin).

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

## Zapytanie o pojedyncze zadanie

Informacje o tym, jak tworzyć zadania wideo, znajdziesz w dokumentacji [API generowania wideo Maestro](/pl/guides/maestro/maestro_videos). Jako przykład użyjemy zwróconego przez nie identyfikatora zadania: `f57e99c4f60f4373a15517742ce2357d`, aby zademonstrować, jak sprawdzić jego status i wynik.

### Ustawianie nagłówków żądania i treści żądania

**Request Headers** obejmują:

* `accept`: określa odbieranie wyników odpowiedzi w formacie JSON, tutaj należy wpisać `application/json`.
* `authorization`: klucz do wywołania API, po aplikacji można go bezpośrednio wybrać z listy rozwijanej.
* `content-type`: format treści żądania, tutaj należy wpisać `application/json`.

**Request Body** obejmuje:

| Pole | Typ | Wymagane przy | Opis |
| - | - | - | - |
| `id` | string | Wymagane przy zapytaniu o pojedyncze zadanie | `task_id` zwrócone przez `POST /maestro/videos` |
| `action` | string | Nie | `retrieve` (domyślnie, zapytanie o pojedyncze zadanie); przy zapytaniu o listę historii zawsze `retrieve_batch` |

### Przykład kodu

Odpowiedni kod CURL jest następujący:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'
```

Odpowiedni kod Python jest następujący:

```python theme={null}
import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

### Przykład odpowiedzi

Po pomyślnym przesłaniu żądania API zwróci status i wynik tego zadania wideo. Przykład odpowiedzi po ukończeniu zadania jest następujący (każdy język odpowiada jednemu `variant`):

```json theme={null}
{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}
```

Opis pól zwróconego wyniku jest następujący:

* `id`: ID tego zadania wideo, używane do unikalnej identyfikacji tego zadania generowania wideo.
* `status`: status zadania, wartości to `pending → planning → producing → succeeded` (lub `failed`). O tym, czy zadanie zostało ukończone, decyduje ten najwyższego poziomu `status`.
* `elapsed`: czas trwania zadania (sekundy).
* `progress`: obiekt postępu najwyższego poziomu, `percent` (0–100) po pomyślnym zakończeniu zadania zostanie awaryjnie ustawiony na 100; `stage` i `message` odzwierciedlają ostatnie zdarzenie postępu reżysera AI (dlatego po sukcesie `stage` może nadal być ostatnim etapem wykonania, takim jak `producing`), można go bezpośrednio użyć do wyświetlania paska postępu.
* `request`: treść żądania podczas uruchamiania zadania.
* `response`: informacje zwrócone przez zadanie.
  * `success`: czy zadanie zakończyło się powodzeniem.
  * `data.variants`: każdy język odpowiada jednemu obiektowi gotowego filmu, zawierającemu `lang`, `aspect`, `title`, `output_url` (adres pobierania gotowego filmu) itd.
  * `data.project`: produkt całego projektu, zawierający `tarball_url` (pakiet projektu) i `outputs` (łącza do wszystkich gotowych filmów).
  * `data.progress`: tablica zdarzeń postępu dodawanych według etapów (dziennik append-only), może być używana do wyświetlania szczegółowego postępu w czasie rzeczywistym.
* `created_at`: czas utworzenia zadania, znacznik czasu Unix (sekundy).
* `started_at`: czas rozpoczęcia wykonania zadania, znacznik czasu Unix (sekundy). Wartość `null`, gdy zadanie jeszcze się nie rozpoczęło.
* `finished_at`: czas ukończenia zadania, znacznik czasu Unix (sekundy). Wartość `null`, gdy zadanie nie zostało ukończone.

## Zapytanie o listę historii

Przekaż `action: retrieve_batch`, aby uzyskać ostatnie zadania aktualnie zalogowanego wykonawcy (w odwrotnej kolejności według czasu utworzenia); może to być używane na stronie listy „Moje filmy”. Lista historii jest izolowana według tożsamości logowania.

**Request Body** obejmuje:

| Pole | Typ | Wymagane | Opis |
| - | - | - | - |
| `action` | string | Tak | Stała wartość `retrieve_batch` |
| `limit` | int | Nie | Liczba zwracanych rekordów, domyślnie 20; prawidłowy zakres to 1–100 |
| `created_at_max` | int | Nie | Zwraca tylko zadania utworzone ściśle przed tym znacznikiem czasu Unix (bez wartości granicznej, do stronicowania) |
| `created_at_min` | int | Nie | Zwraca tylko zadania utworzone ściśle po tym znaczniku czasu Unix (bez wartości granicznej) |

### Przykład kodu

Odpowiedni kod CURL jest następujący:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'
```

### Przykład odpowiedzi

Po pomyślnym wysłaniu żądania API zwróci listę historycznych zadań bieżącego użytkownika:

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}
```

Opis pól zwracanego wyniku jest następujący:

* `count`: Łączna liczba zadań widocznych dla aktualnie zalogowanego wykonawcy, niezależnie od warunków czasowych ani `limit`.
* `items`: Tablica zadań przefiltrowanych według warunków czasowych i `limit`, uporządkowana malejąco według czasu utworzenia; format każdego elementu jest zgodny z wynikiem zwracanym przez „Zapytanie o pojedyncze zadanie”.

## Zalecenia dotyczące odpytywania

Ze względu na długi czas produkcji wideo `status` przejdzie przez `pending → planning → producing → succeeded` (lub `failed`). Zaleca się odpytywanie co 5–10 sekund, aż `status` zmieni się na `succeeded` lub `failed`. Do wyświetlania paska postępu w czasie rzeczywistym można wykorzystać najwyższego poziomu `progress.percent`. **Odpytywanie tego interfejsu jest bezpłatne i nie zużywa punktów.**

## Obsługa błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład:

* `401 invalid_token`: Unauthorized, invalid or missing authorization token.
* `404 not_found`: Task not found, the given task\_id does not exist.
* `429 too_many_requests`: Too many requests, you have exceeded the rate limit.
* `500 api_error`: Internal server error, something went wrong on the server.

### Przykład odpowiedzi błędu

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Podsumowanie

Dzięki temu dokumentowi dowiedzieli się Państwo, jak używać API zapytań o zadania Maestro do sprawdzania statusu i wyników pojedynczego zadania, a także do pobierania listy historycznych zadań bieżącego użytkownika. Mamy nadzieję, że ten dokument pomoże Państwu lepiej zintegrować i używać tego API. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego.

## Powiązane interfejsy

* [Instrukcja integracji API generowania wideo Maestro](/pl/guides/maestro/maestro_videos): Automatyczne tworzenie gotowego filmu z napisami za pomocą jednolinijkowego promptu w języku naturalnym; po wysłaniu zwracane jest `task_id`, a następnie do odpytywania wyników używany jest ten interfejs.


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