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

# Maestro API do generowania wideo - instrukcja integracji

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro to **natywne dla agenta** API do produkcji wideo: opisujesz pożądane wideo za pomocą naturalnego języka `prompt` (opcjonalnie dołączając `file_urls` z referencyjnymi obrazami / wideo / dźwiękiem), a bezgłowy „reżyser AI” automatycznie zajmie się wyborem tematu, pisaniem scenariusza, generowaniem obrazów, lektorem, muzyką, kompozycją i renderowaniem, ostatecznie produkując gotowy film z napisami i przesyłając go do CDN.

W tym dokumencie szczegółowo opisano integrację API do generowania wideo Maestro, aby pomóc Ci szybko zintegrować i w pełni wykorzystać możliwości tego API.

Jest to **interfejs zadań asynchronicznych**: po przesłaniu natychmiast zwraca `task_id`, a następnie można za pomocą [API zapytań o zadania Maestro](/pl/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) cyklicznie uzyskiwać wyniki (cykliczne zapytania są bezpłatne). Aby kontynuować iterację na istniejącym wideo, można użyć `action: remix` / `edit` / `extend` w połączeniu z `ref_task_id`.

## Proces aplikacji

Aby korzystać z API do generowania wideo Maestro, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość.

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

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę.

**Jeden token API wystarczy do wywołania wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Pierwsze zgłoszenie daje darmowy limit, aby móc skorzystać z bezpłatnego doświadczenia; w przypadku niewystarczającego limitu można doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin).

> 📘 Pełna dokumentacja: [API do generowania wideo Maestro →](https://platform.acedata.cloud/documents/maestro-videos)

## Podstawowe użycie

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

Najprostsze użycie wymaga jedynie przesłania naturalnego języka `prompt`, a reżyser AI automatycznie zdecyduje o scenariuszu, obrazach, lektorze i montażu. Najpierw zapoznajmy się z nagłówkami żądania i ciałem żądania, które należy ustawić.

**Nagłówki żądania** obejmują:

* `accept`: format odpowiedzi, który chcesz otrzymać, tutaj wpisz `application/json`, czyli format JSON.
* `authorization`: klucz do wywołania API, po złożeniu wniosku można go bezpośrednio wybrać z rozwijanej listy.
* `content-type`: format ciała żądania, tutaj wpisz `application/json`.

**Ciało żądania** głównie obejmuje:

* `prompt`: opis w naturalnym języku wideo, które chcesz stworzyć (temat, co ma być pokazane, styl, odbiorcy).
* `langs`: tablica języków wyjściowych, np. `["zh-cn", "en"]`, domyślnie `["zh-cn"]`.
* `aspect`: proporcje obrazu, `9:16` (domyślnie) / `16:9` / `1:1`.
* `duration`: docelowy czas trwania (sekundy), domyślnie 30.

Wszystkie pola ciała żądania przedstawione są w poniższej tabeli:

| Pole | Typ | Wymagane | Opis |
| - | - | - | - |
| `prompt` | string | Tak | Opis w naturalnym języku wideo, które chcesz stworzyć (temat, co ma być pokazane, styl, odbiorcy). Scenariusz, obrazy, lektor i montaż są ustalane przez AI. |
| `action` | string | Nie | `generate` (domyślnie, generowanie nowego wideo) / `remix` / `edit` / `extend` (iteracja na istniejącym wideo, wymaga `ref_task_id`). |
| `ref_task_id` | string | Nie | Wymagane, gdy `action` to remix / edit / extend: historyczne `task_id`, które jest punktem wyjścia. |
| `file_urls` | string\[] | Nie | Referencyjne media (obrazy / wideo / dźwięki URL), na przykład zdjęcia produktów, logo lub fragmenty materiałów, do których mają być dodane napisy. |
| `langs` | string\[] | Nie | Języki wyjściowe, np. `["zh-cn", "en"]`, domyślnie `["zh-cn"]`. Pierwszy to język główny; za każdą dodatkową język, który wykorzystuje te same obrazy, dodaje się tylko lektora + renderowanie, **za każdy dodatkowy +6 punktów**. |
| `aspect` | string | Nie | `9:16` (domyślnie) / `16:9` / `1:1`, jednolite wyjście 1080p/30fps. |
| `duration` | int | Nie | Docelowy czas trwania (sekundy), domyślnie 30, wspiera **5–300 sekund**. Opłaty są naliczane na podstawie rzeczywistego czasu trwania filmu, ale nie przekroczą czasu żądania. |
| `scenario` | string | Nie | Typ wideo: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` wymaga przesłania źródłowego wideo, `avatar` wymaga przesłania portretu. |
| `style` | string | Nie | Ustawienia stylu wizualnego: `auto` (domyślnie) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, akceptuje również tekst swobodny jako miękki podpowiedź. Nie zmienia trasy. |
| `voice` | string | Nie | Głos narratora (niezależny od języka, uniwersalny): `auto` (domyślnie) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`. |

Poniżej przedstawiamy konkretny przykład. Załóżmy, że chcemy wygenerować dwujęzyczne wideo popularnonaukowe w poziomie, trwające 20 sekund, odpowiadający kod CURL wygląda następująco:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'
```

Odpowiedni kod w Pythonie wygląda następująco:

```python theme={null}
import requests

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

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

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

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

Po kliknięciu uruchomienia można zauważyć, że natychmiast otrzymasz wynik, jak poniżej:

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

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

* `success`：Czy zadanie zostało pomyślnie przesłane.
* `task_id`：ID zadania generowania wideo, które można wykorzystać do późniejszego sprawdzania wyników w [API zapytań o zadania Maestro](/pl/guides/maestro/maestro_tasks).
* `trace_id`：ID śledzenia tego żądania, które można przekazać wsparciu technicznemu w przypadku problemów.

Ponieważ produkcja wideo zajmuje dużo czasu, interfejs **natychmiast zwraca `task_id`**, nie czekając na zakończenie renderowania wideo. Następnie należy użyć `task_id` do sprawdzania wyników, szczegóły w sekcji „Pobierz wyniki”.

## Określenie typu i stylu wideo (scenario / style)

Jeśli nie przekażesz `scenario`, AI automatycznie oceni (równa się `auto`); jeśli chcesz przypisać wideo do określonego typu, przekaż to wyraźnie. Na przykład, aby stworzyć **pionowy krótkometrażowy dramat**, można określić następujące treści:

* `scenario`：Typ wideo, tutaj ustawione na `drama` (krótki dramat z postaciami + dialogami).
* `style`：Styl wizualny, tutaj ustawione na `cinematic` (filmowa jakość).

Przykładowy kod CURL do wypełnienia wygląda następująco:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Dwaj współlokatorzy kłócą się o kota, a potem się godzą, trzy akty zwrotów akcji, zakończenie ciepłe",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

Typowe kombinacje:

* Krótkie filmy narracyjne: `scenario: "narrated"`, wspierane przez Lite / Standard / Pro.
* Automatyczne napisy: `scenario: "captions"`, należy użyć `file_urls` do przesłania źródłowego wideo, wspierane przez Lite / Standard / Pro.
* Cyfrowa postać / narracja: `scenario: "avatar"`, należy użyć `file_urls` do przesłania zdjęcia osoby, wspierane przez Standard / Pro.
* Krótki dramat: `scenario: "drama"` (postacie + dialogi), wspierane tylko przez Pro.
* `style` to predefiniowany styl wizualny (np. `modern` / `neon` / `luxury`), nie zmienia typu, tylko wpływa na wrażenia wizualne.
* `voice` służy do określenia tonu narracji (np. `warm-female` / `deep-male`), niezależnie od języka, uniwersalne między językami.

Wynik zwracany jest zgodny z „Podstawowym użyciem”, również natychmiast zwraca `task_id`.

## Wielojęzyczne wyjście

W `langs` można przekazać wiele języków, aby jednocześnie wygenerować wersje wielojęzyczne. Pierwszy język to język główny, a każda dodatkowa wersja językowa **używa tych samych obrazów**, tylko dodatkowo nagrywa głos + renderuje, dlatego **każdy dodatkowy język to tylko +6 punktów**. Przykład:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Przedstawiamy nasz produkt inteligentnej obsługi klienta, podkreślając 3 kluczowe cechy",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

Po zakończeniu zadania każdemu językowi odpowiada jeden `variant` w wynikach (patrz [API zapytań o zadania Maestro](/pl/guides/maestro/maestro_tasks)).

## Iteracja na istniejącym wideo (remix / edit / extend)

Przekazując `action` oraz `ref_task_id` z poprzedniego zadania, można wprowadzić różnicowe zmiany na podstawie oryginalnego projektu (np. „zmień tytuł drugiego aktu”, „zmień narrację”, „ogólnie przyciemnij”). Małe zmiany są szybkie, duże zmiany będą wymagały ponownego wykonania:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "Zmień tytuł otwierający na coś bardziej uderzającego, ogólnie przyciemnij kolorystykę"
}'
```

* `remix`：Na podstawie oryginalnej struktury wideo, nowa interpretacja (zachowując temat, dostosowując wykonanie).
* `edit`：Drobne poprawki w określonym obszarze (np. zmiana tytułu, zmiana narracji, korekcja kolorów).
* `extend`：Rozszerzenie treści na podstawie oryginalnego wideo.

Wynik również natychmiast zwraca nowe `task_id`, które można wykorzystać do sprawdzania wyników po iteracji.

## Pobierz wyniki

Ponieważ produkcja wideo zajmuje dużo czasu, ten interfejs natychmiast zwraca `task_id` po przesłaniu, należy użyć go do [API zapytań o zadania Maestro](/pl/guides/maestro/maestro_tasks) w celu sprawdzenia wyników:

```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"
}'
```

Po zakończeniu zadania zwrócone zostaną informacje o gotowym materiale (każdy język odpowiada jednemu `variant`). `status` przechodzi przez `pending → planning → producing → succeeded` (lub `failed`), **sprawdzanie jest darmowe, nie zużywa punktów**. Pełny format odpowiedzi oraz zapytania o historię można znaleźć w [Dokumentacji API zapytań o zadania Maestro](/pl/guides/maestro/maestro_tasks).

## Rozliczenia

**Opłata za zadanie jest naliczana po zakończeniu, nie pobiera się opłat za nieudane zadania.** Opłata jest uzależniona od rzeczywistego czasu trwania gotowego materiału oraz liczby języków, a czas rozliczeniowy nie przekroczy czasu żądania. Jeśli dany język ostatecznie nie zostanie wygenerowany, nie zostanie naliczona dodatkowa opłata +6 za ten język. Przesyłanie zadań nie jest osobno płatne, a zapytania `/maestro/tasks` są darmowe.

Punkty za pojedynczy gotowy materiał oblicza się według wzoru:

```
punkty = czas trwania materiału w sekundach × 0.60 × mnożnik scenariusza + 6 × max(liczba języków − 1, 0)
```

Maestro nalicza opłatę w wysokości **0.60 punktów/sekundę rzeczywistego materiału**, wspiera 5–300 sekund, maksymalnie 4 języki oraz wyjście 1080p / 30fps; wszystkie akcje i scenariusze są dozwolone.

Mnożnik scenariusza: `drama` 1.35× / `avatar` 1.15× / inne 1×.

| Przykład | Punkty |
| - | -: |
| Lite 30 sekund | 6 |
| Standard 30 sekund | 18 |
| Standard 60 sekund | 36 |
| Standard 120 sekund | 72 |
| Pro 30 sekund | 36 |
| Pro 300 sekund | 360 |
| Każdy dodatkowy język dostarczony | +6 |
| Zapytania `/maestro/tasks` | Darmowe |

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

* `400 invalid_request`：Złe żądanie, prawdopodobnie z powodu brakującego `prompt` lub nieprawidłowych parametrów.
* `401 invalid_token`：Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacji.
* `403 forbidden`：Zabronione, niewystarczający balans lub dostęp.
* `429 too_many_requests`：Zbyt wiele żądań, przekroczono limit.
* `500 api_error`：Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

### Przykład odpowiedzi błędu

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "pobieranie nie powiodło się"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Wnioski

Dzięki temu dokumentowi zrozumiałeś, jak korzystać z API do generowania wideo Maestro: wystarczy jedno naturalne zdanie `prompt`, aby automatycznie zrealizować skrypt, materiały, lektorów, muzykę, montaż, napisy i renderowanie gotowego filmu, a także wspierać określenie typu wideo, stylu, tonu, wielojęzycznego wyjścia oraz iteracji na istniejących filmach. Mamy nadzieję, że ten dokument pomoże Ci lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, prosimy o kontakt z naszym zespołem wsparcia technicznego.

## Powiązane interfejsy

* [Dokumentacja integracji API zapytań o zadania Maestro](/pl/guides/maestro/maestro_tasks): użyj `POST /maestro/videos`, aby zwrócić `task_id` do sprawdzenia statusu i wyników zadania lub pobrania listy historycznych zadań (polling bezpłatny).


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