Przejdź do głównej treści
Maestro to natywny dla Agentów interfejs produkcji wideo: używasz jednego naturalnego językowego prompt, aby opisać wideo, które chcesz stworzyć (opcjonalnie dołączając obrazy / wideo / audio referencyjne za pomocą file_urls), a bezgłowy „reżyser AI” automatycznie wykona wybór tematu, napisze scenariusz, wygeneruje obraz, lektora, muzykę, kompozycję i renderowanie, ostatecznie tworząc gotowy film z napisami i przesyłając go do CDN. Ten artykuł szczegółowo przedstawia instrukcję integracji API generowania wideo Maestro, pomagając szybko zintegrować i w pełni wykorzystać możliwości tego API. To interfejs zadań asynchronicznych: po przesłaniu natychmiast zwracany jest task_id, a następnie wyniki są pobierane przez odpytywanie za pomocą API zapytania o zadania Maestro (POST /maestro/tasks) (odpytywanie jest bezpłatne i nie jest naliczane). Aby kontynuować iterację na istniejącym wideo, możesz użyć action: remix / edit / extend wraz z ref_task_id.

Proces składania wniosku

Aby korzystać z API generowania wideo Maestro, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go na później. Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się, a po zakończeniu automatycznie powró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 darmowy limit, umożliwiający bezpłatne wypróbowanie; gdy limit jest niewystarczający, możesz doładować wspólne saldo w konsoli.
📘 Pełna dokumentacja: API generowania wideo Maestro →

Podstawowe użycie

POST https://api.acedata.cloud/maestro/videos W najbardziej podstawowym użyciu wystarczy przekazać opis prompt w języku naturalnym. Reżyser AI automatycznie zdecyduje o scenariuszu, obrazie, lektorze i montażu. Najpierw omówimy wymagane nagłówki i treść żądania. Request Headers obejmują:
  • accept: format odpowiedzi, którą chcesz otrzymać; wpisz tutaj application/json, czyli format JSON.
  • authorization: klucz do wywołania API; po uzyskaniu można go wybrać bezpośrednio z listy rozwijanej.
  • content-type: format treści żądania; wpisz tutaj application/json.
Request Body obejmuje głównie:
  • prompt: opisz w języku naturalnym film, który chcesz stworzyć (temat, co ma zostać pokazane, styl, odbiorcy).
  • langs: tablica języków gotowego filmu; jednorazowo przekaż tylko jeden, np. ["zh-cn"]; domyślnie ["zh-cn"].
  • aspect: proporcje obrazu: 9:16 (domyślnie) / 16:9 / 1:1.
  • duration: docelowy czas trwania (w sekundach); domyślnie 30.
Wszystkie pola treści żądania przedstawiono w poniższej tabeli: Poniżej przedstawiono konkretny przykład. Załóżmy, że chcemy wygenerować 20-sekundowy, pionowy film popularnonaukowy w języku chińskim. Odpowiedni kod CURL wygląda następująco:
Odpowiedni kod w Pythonie wygląda następująco:
Po kliknięciu przycisku uruchamiania można zauważyć, że wynik zostanie zwrócony natychmiast, jak poniżej:
Opis pól wyniku odpowiedzi jest następujący:
  • success: czy to zadanie zostało pomyślnie przesłane.
  • task_id: identyfikator tego zadania generowania wideo; użyj go później do odpytywania wyników za pomocą API zapytań o zadania Maestro.
  • trace_id: identyfikator śledzenia tego żądania; w przypadku problemów można przekazać go pomocy technicznej w celu ich zdiagnozowania.
Ze względu na długi czas generowania wideo interfejs API natychmiast zwraca task_id i nie czeka na zakończenie renderowania wideo. Następnie należy użyć task_id do odpytywania o wynik; szczegóły znajdziesz w sekcji „Pobieranie wyników”.

Określanie typu i stylu wideo (scenario / style)

Jeśli scenario nie zostanie przekazane, AI określi je automatycznie (równoznaczne z auto); jeśli chcesz przypisać wideo do określonego typu, przekaż je jawnie. Na przykład, aby stworzyć pionowy krótki dramat, można określić następujące wartości:
  • scenario: typ wideo, tutaj ustawiony na drama (krótki dramat z postaciami + dialogami).
  • style: styl wizualny, tutaj ustawiony na cinematic (kinowa jakość).
Przykładowy kod CURL do wypełnienia jest następujący:
Typowe sposoby łączenia:
  • Krótki film z narracją: scenario: "narrated".
  • Automatyczne napisy: scenario: "captions", należy przekazać źródłowe wideo przez file_urls.
  • Cyfrowy awatar / wypowiedź do kamery: scenario: "avatar", należy przekazać jedno zdjęcie portretowe przez file_urls.
  • Krótki dramat: scenario: "drama" (postacie + dialogi).
  • style to ustawienie wstępne stylu wizualnego (np. modern / neon / luxury), nie zmienia typu, a jedynie wpływa na odbiór wizualny.
  • voice służy do określenia barwy głosu narratora (np. warm-female / deep-male), jest niezależne od języka i uniwersalne między językami.
Wynik zwracany jest tak samo jak w „Podstawowym użyciu”, również natychmiast zwracany jest task_id.

Język gotowego wideo

Jedno zadanie dostarcza tylko jedno gotowe wideo w jednym języku. langs może zawierać tylko jeden kod języka, na przykład ["zh-cn"] lub ["en"]; przekazanie wielu języków zwróci 400. Jeśli potrzebujesz wideo w różnych językach, utwórz osobne zadania. Wybór języka nie zmienia ceny za sekundę.

Iterowanie na istniejącym wideo (remix / edit / extend)

Przekaż action oraz ref_task_id poprzedniego zadania, aby wprowadzić przyrostowe zmiany na podstawie oryginalnego projektu (np. „zmień tytuł sceny 2”, „zmień dubbing”, „ogólnie przyciemnij”). Małe zmiany są szybkie, duże zmiany powodują ponowne wykonanie:
  • remix: ponowna interpretacja na podstawie struktury oryginalnego wideo (zachowuje temat, dostosowuje formę).
  • edit: precyzyjna edycja określonego fragmentu (np. zmiana tytułu, dubbingu, korekcja kolorów).
  • extend: rozszerzenie treści na podstawie oryginalnego wideo.
Wynik również natychmiast zwraca nowy task_id; użyj go do odpytywania, aby uzyskać gotowe wideo po iteracji.

Pobieranie wyników

Ze względu na długi czas produkcji wideo ten interfejs natychmiast zwraca task_id po przesłaniu; należy użyć go do odpytywania wyników przez API zapytań o zadania Maestro:
Po zakończeniu zadania zwrócona zostanie informacja o jednym gotowym wideo (znajdująca się w tablicy variants). status przechodzi przez pending → planning → producing → succeeded (lub failed), odpytywanie jest bezpłatne i nie zużywa punktów. Pełny format odpowiedzi oraz zapytania o listę historii znajdziesz w instrukcji integracji API zapytań o zadania Maestro.

Rozliczenia

Po pomyślnym wykonaniu zadania opłata jest naliczana według rzeczywistego czasu trwania dostarczonego gotowego wideo; za niepowodzenie nie jest pobierana opłata. Czas rozliczeniowy jest liczony w pełnych sekundach i nie przekracza żądanego czasu trwania; jeśli nie można odczytać czasu trwania gotowego wideo, używany jest żądany czas trwania. Samo przesłanie zadania nie jest rozliczane osobno, a odpytywanie /maestro/tasks jest bezpłatne.
Wszystkie scenariusze, działania i języki mają tę samą cenę, bez mnożników scenariusza ani dopłat za język. Każde zadanie dostarcza tylko jedno gotowe wideo w jednym języku. Żądany czas trwania obsługuje od 5 do 300 sekund, z jednolitym wyjściem 1080p / 30fps.

Obsługa błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informację. Na przykład:
  • 400 invalid_request: Nieprawidłowe żądanie, prawdopodobnie z powodu braku prompt lub nieprawidłowych parametrów.
  • 401 invalid_token: Brak autoryzacji, nieprawidłowy lub brakujący token autoryzacyjny.
  • 403 forbidden: Dostęp zabroniony, niewystarczające saldo lub uprawnienia.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczono limit szybkoś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 korzystać z API generowania wideo Maestro: wystarczy jedno naturalne językowo prompt, aby automatycznie ukończyć scenariusz, materiały, dubbing, muzykę, montaż, napisy i renderowanie gotowego wideo, a także obsługiwane jest określanie typu wideo, stylu, barwy głosu, języka gotowego wideo oraz iterowanie na istniejących wideo. Mamy nadzieję, że ten dokument pomoże Ci lepiej integrować i używać tego API. W razie jakichkolwiek pytań skontaktuj się z naszym zespołem wsparcia technicznego.

Powiązane interfejsy