Przejdź do głównej treści
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 opisuje 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 aplikacji

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 użycia później. Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności składania osobnego wniosku dla każdej usługi. Przy pierwszym wniosku otrzymasz bezpłatny limit, aby móc korzystać z usługi za darmo; gdy limit będzie 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 utworzyć zadanie wideo, znajdziesz w dokumentacji API generowania wideo Maestro. Jako przykład użyjemy identyfikatora zadania zwróconego przez ten interfejs: f57e99c4f60f4373a15517742ce2357d, aby pokazać, jak sprawdzić jego status i wynik.

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

Request Headers obejmują:
  • accept: określa odbieranie odpowiedzi w formacie JSON, tutaj należy wpisać application/json.
  • authorization: klucz do wywołania API, po złożeniu wniosku można go bezpośrednio wybrać z listy rozwijanej.
  • content-type: format treści żądania, tutaj należy wpisać application/json.
Request Body obejmuje:

Przykład kodu

Odpowiedni kod CURL jest następujący:
Odpowiedni kod Python jest następujący:

Przykład odpowiedzi

Po pomyślnym wysłaniu żądania API zwróci status i wynik tego zadania wideo. Przykład odpowiedzi po ukończeniu zadania jest następujący (tablica variants zawiera jeden gotowy film):
Opis pól wyniku odpowiedzi jest następujący:
  • id: ID tego zadania wideo, używane do jednoznacznej identyfikacji bieżącego zadania generowania wideo.
  • status: Status zadania; możliwe wartości to pending → planning → producing → succeeded (lub failed). O tym, czy zadanie zostało ukończone, decyduje to pole status na najwyższym poziomie.
  • elapsed: Czas trwania zadania (w sekundach).
  • progress: Obiekt postępu na najwyższym poziomie. percent (0–100) po pomyślnym ukończeniu zadania wynosi 100; stage i message odzwierciedlają najnowsze zdarzenie postępu reżysera AI (dlatego po powodzeniu stage może nadal wskazywać ostatni etap wykonania, np. producing) i mogą być używane bezpośrednio do wyświetlania paska postępu.
  • request: Treść żądania w momencie uruchamiania zadania.
  • response: Informacje zwrócone przez zadanie.
    • success: Informacja, czy zadanie zakończyło się pomyślnie.
    • data.variants: Zawiera obiekt gotowego filmu w wybranym języku, w tym lang, aspect, title, output_url (adres pobierania gotowego filmu) itd.
    • data.project: Artefakty całego projektu, w tym tarball_url (pakiet projektu) i outputs (link do gotowego filmu).
    • data.progress: Tablica zdarzeń postępu dodawanych według etapów (dziennik tylko do dopisywania), która może służyć do wyświetlania szczegółowego postępu w czasie rzeczywistym.
  • created_at: Czas utworzenia zadania, znacznik czasu Unix (sekundy).
  • started_at: Czas rozpoczęcia wykonywania zadania, znacznik czasu Unix (sekundy). Wartość wynosi null, jeśli zadanie nie zostało jeszcze rozpoczęte.
  • finished_at: czas ukończenia zadania, znacznik czasu Unix (w sekundach). 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 kolejności malejącej według czasu utworzenia); może to służyć do strony listy „Moje filmy”. Lista historii jest izolowana według tożsamości logowania. Request Body obejmuje:

Przykład kodu

Odpowiedni kod CURL jest następujący:

Przykład odpowiedzi

Po pomyślnym wysłaniu żądania API zwróci listę historycznych zadań bieżącego użytkownika:
Opis pól wyniku zwracanego jest następujący:
  • count: Łączna liczba zadań widocznych dla aktualnie zalogowanego wykonawcy, niezależna 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

Ponieważ produkcja wideo trwa stosunkowo długo, status będzie przechodzić przez pending → planning → producing → succeeded (lub failed). Zaleca się odpytywanie co 5–10 sekund, aż status zmieni się na succeeded lub failed. Można użyć najwyższego poziomu progress.percent do wyświetlania paska postępu w czasie rzeczywistym. 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: Brak autoryzacji, nieprawidłowy lub brakujący token autoryzacyjny.
  • 404 not_found: Nie znaleziono zadania, podane task_id nie istnieje.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczono limit częstotliwości.
  • 500 api_error: Wewnętrzny błąd serwera, coś poszło nie tak na serwerze.

Przykład odpowiedzi błędu

Podsumowanie

Dzięki temu dokumentowi wiesz już, 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 Ci lepiej zintegrować i używać tego API. W razie jakichkolwiek pytań skontaktuj się z naszym zespołem wsparcia technicznego.

Powiązane interfejsy