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.
Przykład kodu
Odpowiedni kod CURL 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 (tablicavariants zawiera jeden gotowy film):
id: ID tego zadania wideo, używane do jednoznacznej identyfikacji bieżącego zadania generowania wideo.status: Status zadania; możliwe wartości topending → planning → producing → succeeded(lubfailed). O tym, czy zadanie zostało ukończone, decyduje to polestatusna 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;stageimessageodzwierciedlają najnowsze zdarzenie postępu reżysera AI (dlatego po powodzeniustagemoż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 tymlang,aspect,title,output_url(adres pobierania gotowego filmu) itd.data.project: Artefakty całego projektu, w tymtarball_url(pakiet projektu) ioutputs(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:count: Łączna liczba zadań widocznych dla aktualnie zalogowanego wykonawcy, niezależna od warunków czasowych anilimit.items: Tablica zadań przefiltrowanych według warunków czasowych ilimit, 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
- Instrukcja integracji API generowania wideo Maestro: Automatycznie tworzy gotowy film z napisami na podstawie jednego polecenia w języku naturalnym, po przesłaniu zwraca
task_id, a następnie używa tego interfejsu do odpytywania o wynik.

