Instrukcja integracji API zapytań o zadania Maestro

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 (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, aby uzyskać swój API Token i zachować go do późniejszego użycia.

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.

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

Zapytanie o pojedyncze zadanie

Informacje o tym, jak tworzyć zadania wideo, znajdziesz w dokumentacji API generowania wideo Maestro. 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:

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:

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

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

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:

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

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

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Instrukcja integracji API zapytań o zadania Maestro

Proces aplikowania

Zapytanie o pojedyncze zadanie

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

Przykład kodu

Przykład odpowiedzi

Zapytanie o listę historii

Przykład kodu

Przykład odpowiedzi

Zalecenia dotyczące odpytywania

Obsługa błędów

Przykład odpowiedzi błędu

Podsumowanie

Powiązane interfejsy

​Proces aplikowania

​Zapytanie o pojedyncze zadanie

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

​Przykład kodu

​Przykład odpowiedzi

​Zapytanie o listę historii

​Przykład kodu

​Przykład odpowiedzi

​Zalecenia dotyczące odpytywania

​Obsługa błędów

​Przykład odpowiedzi błędu

​Podsumowanie

​Powiązane interfejsy

Proces aplikowania

Zapytanie o pojedyncze zadanie

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

Przykład kodu

Przykład odpowiedzi

Zapytanie o listę historii

Przykład kodu

Przykład odpowiedzi

Zalecenia dotyczące odpytywania

Obsługa błędów

Przykład odpowiedzi błędu

Podsumowanie

Powiązane interfejsy