> ## 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. # SeeDance Videos Generation API Integracja Opis > ByteDance Seedance Video Generation API guide - Ace Data Cloud Ten dokument przedstawi sposób integracji z SeeDance Videos Generation API, który umożliwia generowanie oficjalnych filmów SeeDance poprzez wprowadzenie niestandardowych parametrów. ## Proces aplikacji Aby korzystać z SeeDance Videos Generation API, 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/5hmkdg.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.** Przy pierwszym wniosku otrzymasz darmowy limit, aby móc skorzystać z usługi; gdy limit się wyczerpie, możesz doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [SeeDance Videos Generation API →](https://platform.acedata.cloud/documents/seedance-videos) ## Podstawowe użycie Najpierw zapoznaj się z podstawowym sposobem użycia, polegającym na wprowadzeniu słów kluczowych `content.text`, typu `content.type=text` oraz modelu `model`, aby uzyskać przetworzony wynik, szczegóły są następujące:

Możemy zobaczyć, że ustawiliśmy nagłówki żądania, w tym: * `accept`: jakiego formatu odpowiedzi oczekujesz, tutaj wpisujemy `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. Dodatkowo ustawiono ciało żądania, w tym: * `model`: model generujący wideo. * **Seria Seedance 1.x**: `doubao-seedance-1-0-pro-250528`, `doubao-seedance-1-0-pro-fast-251015`, `doubao-seedance-1-5-pro-251215`, `doubao-seedance-1-0-lite-t2v-250428`, `doubao-seedance-1-0-lite-i2v-250428`. * **Seria Seedance 2.0** (obsługuje multimodalne wejścia, takie jak odniesienia do twarzy / postaci): `doubao-seedance-2-0-260128` (standard), `doubao-seedance-2-0-fast-260128` (szybki), `doubao-seedance-2-0-mini-260615` (lekki). Szczegóły w sekcji „Odniesienia do twarzy i postaci (Seedance 2.0)”. * `content`: tablica wprowadzonych treści, `type` może być `text` (słowa kluczowe), `image_url` (zdjęcie referencyjne), `audio_url` (audio referencyjne, 2.0), `video_url` (wideo referencyjne, 2.0). Obraz można określić za pomocą `role`: `first_frame` (pierwsza klatka) / `last_frame` (ostatnia klatka) / `reference_image` (odniesienie do twarzy / postaci / obiektu). * `resolution`: rozdzielczość wyjściowa, do wyboru `480p` / `720p` / `1080p` (model standardowy 2.0 obsługuje również `4k`; w modelach `fast` / `mini` 2.0 maksymalnie `720p`). * `ratio`: proporcje, do wyboru `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`. * `duration`: długość wideo (sekundy), zakres 1.x 2–12, 2.0 2–15. * `seed`: losowe ziarno, liczba całkowita, od -1 do 4294967295. * `camerafixed`: czy kamera jest stała, `true` / `false`. * `watermark`: czy dodać znak wodny, `true` / `false`. * `generate_audio`: czy generować wideo dźwiękowe, `true` / `false`, **tylko `doubao-seedance-1-5-pro-251215` obsługuje**. * `return_last_frame`: czy w wynikach zwrócić URL ostatniej klatki wideo. * `execution_expires_after`: czas wygaśnięcia zadania (sekundy), zakres 3600–259200. * `callback_url`: adres asynchronicznego wywołania zwrotnego, po ustawieniu API natychmiast zwraca `task_id`, a po zakończeniu zadania wynik zostanie przesłany na ten adres. * `async`: opcjonalne, ustawione na `true`, interfejs natychmiast zwraca `task_id`, nie ma potrzeby podawania `callback_url`, a następnie można uzyskać wyniki, korzystając z odpowiedniego interfejsu zapytań o zadania. Po dokonaniu wyboru, można zauważyć, że po prawej stronie wygenerowano odpowiedni kod, jak pokazano na rysunku:

Kliknij przycisk „Try”, aby przeprowadzić test, jak pokazano na powyższym obrazku, otrzymujemy następujący wynik: ```json theme={null} { "success": true, "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8", "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752", "data": { "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f", "status": "succeeded", "model": "doubao-seedance-2-0-fast-260128", "duration": 5, "resolution": "720p", "ratio": "16:9", "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4" } } ``` Zwrócony wynik zawiera wiele pól, które są opisane poniżej: * `success`, status zadania generowania wideo w tym momencie. * `task_id`, ID zadania generowania wideo w tym momencie. * `trace_id`, ID śledzenia generowania wideo w tym momencie. * `data`, lista wyników zadania generowania wideo w tym momencie. * `task_id`, ID zadania generowania wideo po stronie serwera. * `video_url`, link do wideo wygenerowanego w tym momencie. * `status`, status zadania generowania wideo w tym momencie. * `model`, model użyty do generowania wideo. Możemy zobaczyć, że otrzymaliśmy satysfakcjonujące informacje o wideo, wystarczy, że uzyskamy wygenerowane wideo SeeDance na podstawie adresu URL wideo w `data`. Dodatkowo, jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/seedance/videos' \ -H 'authorization: Bearer ${bearer_token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "content": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}], "model": "doubao-seedance-2-0-fast-260128", "resolution": "720p", "ratio": "16:9", "duration": 5 }' ``` ## Opis parametrów inline Na końcu słów kluczowych `content[].text` można przekazać parametry generacji w formie `--parameter value` (stara metoda, słaba walidacja, w przypadku błędnego wypełnienia automatycznie używane są wartości domyślne). Pełna lista parametrów jest następująca: | Parametry inline | Odpowiednie pole | Opis | Zakres wartości | | ---------------- | ----------------- | ---------------------------- | ------------------------------------------------------------- | | `--rs` | `resolution` | Rozdzielczość wyjściowa | `480p` / `720p` / `1080p` | | `--rt` | `ratio` | Proporcje | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` | | `--dur` | `duration` | Czas trwania wideo (sekundy) | 2–12 | | `--frames` | `frames` | Liczba klatek wideo | Liczby całkowite spełniające 25+4n w zakresie \[29, 289] | | `--fps` | `framespersecond` | Liczba klatek na sekundę | Tylko `24` | | `--seed` | `seed` | Ziarno losowe | -1 do 4294967295 | | `--cf` | `camerafixed` | Czy kamera jest stała | `true` / `false` | | `--wm` | `watermark` | Czy dodać znak wodny | `true` / `false` | > **Zalecana praktyka**: Bezpośrednio w ciele żądania użyj odpowiednich pól najwyższego poziomu (np. `resolution`, `ratio` itp.), aby uzyskać tryb silnej walidacji, błędne wypełnienie parametrów spowoduje zwrócenie wyraźnych komunikatów o błędach, co ułatwia diagnozowanie problemów. ## Generowanie wideo z dźwiękiem `doubao-seedance-1-5-pro-251215` obsługuje generowanie wideo z dźwiękiem za pomocą parametru `generate_audio`: ```json theme={null} { "model": "doubao-seedance-1-5-pro-251215", "content": [ { "type": "text", "text": "Dziewczyna trzyma lisa, wiatr rozwiewa jej włosy, słychać dźwięk wiatru" } ], "generate_audio": true, "ratio": "16:9", "duration": 5 } ``` Inne modele nie obsługują tego parametru, po jego przekazaniu zostanie zignorowany. ## Generowanie wideo z pierwszej klatki Aby wygenerować wideo z obrazu, najpierw parametr `content` musi zawierać element o `type` równym `image_url`, a pole `image_url` musi być w formacie obiektu: `{"url": "https://..."}` lub w formacie Base64 `{"url": "data:image/png;base64,..."}`. > **Uwaga**: `image_url` nie obsługuje bezpośredniego przekazywania w formacie string (np. `"image_url": "https://..."`), musi być użyty format obiektu `"image_url": {"url": "https://..."}`, w przeciwnym razie zwróci błąd 400. Odpowiedni kod: ```python theme={null} import requests url = "https://api.acedata.cloud/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "content": [ { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png" } }, { "type": "text", "text": "Dziewczyna trzyma lisa w ramionach. Otwiera oczy i patrzy czule w kamerę, podczas gdy lis z czułością ją obejmuje. Gdy kamera powoli się oddala, jej włosy są delikatnie rozwiewane przez wiatr. --ratio adaptive --dur 5" } ], "model": "doubao-seedance-1-0-pro-250528" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Klikając uruchom, można natychmiast uzyskać wynik, jak poniżej: ``` { "success": true, "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39", "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4", "data": { "task_id": "cgt-20251222072003-x2259", "status": "succeeded", "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` Można zobaczyć, że efekt generacji jest podobny do opisanego powyżej. ## Generowanie wideo z pierwszej i ostatniej klatki Aby wygenerować wideo z pierwszej i ostatniej klatki, najpierw parametr `content` musi zawierać typ `image_url`, a także należy ustawić `role` na `first_frame` i `last_frame`, aby określić następujące treści: * role: określa pierwszą lub ostatnią klatkę. * image\_url * url link do obrazu Równocześnie `content` musi również zawierać typ `text` jako prompt. Odpowiedni kod: ```python theme={null} import requests url = "https://api.acedata.cloud/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "doubao-seedance-1-0-pro-250528", "content": [ { "type": "text", "text": "Ujęcie 360 stopni" }, { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg" }, "role": "last_frame" } ] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Klikając uruchom, można natychmiast uzyskać wynik, jak poniżej: ``` { "success": true, "task_id": "f7096c6c-9430-4392-8201-d259632d7afd", "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a", "data": { "task_id": "cgt-20251222073134-54qcw", "status": "succeeded", "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` Można zobaczyć, że efekt generacji jest podobny do opisanego powyżej. ## Referencje do twarzy i postaci (Seedance 2.0) **Seria Seedance 2.0** (`doubao-seedance-2-0-260128`, `doubao-seedance-2-0-fast-260128`, `doubao-seedance-2-0-mini-260615`) obsługuje przekazywanie materiałów referencyjnych „**prawdziwych ludzi / postaci**”: dodaj element o `type` równym `image_url` i `role` równym `reference_image` do `content`, aby użyć zdjęcia osoby jako odniesienia, model zachowa **cechy wyglądu tej osoby** w generowanym wideo, umieszczając tę samą osobę w **nowej scenerii, akcji lub ujęciu**. > 📌 Zdjęcia prawdziwych ludzi będą automatycznie rejestrowane przez platformę jako materiały bazowe, a następnie używane do generacji, cały proces jest całkowicie przezroczysty dla wywołującego: **format żądania i odpowiedzi pozostaje niezmieniony**, nie są wymagane żadne dodatkowe parametry, tylko przy pierwszej generacji zajmie to kilka dodatkowych sekund na przetwarzanie materiałów. Wskazówki do użycia: * Tylko modele z serii **Seedance 2.0** wspierają `reference_image`; modele 1.x proszę używać `first_frame` / `last_frame` (pierwsza i ostatnia klatka wideo). * `reference_image` **nie może** być używane razem z `first_frame` / `last_frame`, można wybrać tylko jedno. * Maksymalna liczba odniesień multimodalnych: `image_url` maksymalnie **9** zdjęć; 2.0 wspiera również `audio_url` (rola `reference_audio`, maksymalnie 3) oraz `video_url` (rola `reference_video`, maksymalnie 3). * Zaleca się używanie **zdjęć pojedynczych osób, frontalnych, wyraźnych, bez przeszkód**; im wyraźniejsza twarz, tym wyższa podobieństwo. ### Przykład 1: Zbliżenie na osobę zachowującą wygląd Przekaż zdjęcie twarzy, aby ta osoba uśmiechała się i machała do kamery. Odpowiedni kod: ```python theme={null} import requests url = "https://api.acedata.cloud/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "doubao-seedance-2-0-fast-260128", "content": [ { "type": "text", "text": "Kobieta patrzy w kamerę, daje ciepły naturalny uśmiech i macha ręką, miękkie oświetlenie studyjne, delikatne zbliżenie kamery." }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg" } } ], "resolution": "480p", "ratio": "9:16", "duration": 5 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Wynik jest następujący, w wygenerowanym wideo postać jest zgodna z referencyjnym zdjęciem: ```json theme={null} { "success": true, "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a", "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4", "data": { "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de", "status": "succeeded", "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4", "model": "doubao-seedance-2-0-fast-260128", "resolution": "480p", "ratio": "9:16", "duration": 5 } } ``` ### Przykład 2: Umieszczenie tej samej osoby w nowej scenerii Moc `reference_image` polega na tym, że: zachowuje się tylko **tożsamość postaci**, podczas gdy sceneria, ubranie i ruchy są całkowicie określone przez podane słowa. Poniżej używamy tego samego zdjęcia twarzy, aby ta osoba w beżowym płaszczu spacerowała po jesiennym parku: ```json theme={null} { "model": "doubao-seedance-2-0-fast-260128", "content": [ { "type": "text", "text": "Ta sama kobieta w beżowym płaszczu spaceruje po słonecznym jesiennym parku, złote liście spadają wokół niej, uśmiecha się delikatnie do kamery, filmowy ujęcie z ruchomą kamerą." }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg" } } ], "resolution": "720p", "ratio": "9:16", "duration": 5 } ``` Wynik jest następujący, wygląd postaci został zachowany, a sceneria zmieniła się na jesienny park: ```json theme={null} { "success": true, "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157", "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614", "data": { "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd", "status": "succeeded", "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4", "model": "doubao-seedance-2-0-fast-260128", "resolution": "720p", "ratio": "9:16", "duration": 5 } } ``` > 💡 Jeśli chcesz, aby postać dokładnie odwzorowała kompozycję zdjęcia (a nie „ta sama osoba w innym miejscu”), możesz użyć `first_frame` (pierwsza klatka wideo), aby wideo zaczynało się od tego zdjęcia. ## Asynchroniczne powiadomienia Ponieważ czas generowania wideo przez API SeeDance jest dość długi (około 1-2 minut), można użyć pola `callback_url`, aby skorzystać z trybu asynchronicznego, unikając długiego zajmowania połączenia HTTP. Cały proces: klient inicjuje żądanie, określając `callback_url`, API natychmiast zwraca odpowiedź zawierającą `task_id`; po zakończeniu zadania platforma wysyła wyniki w formacie POST JSON do `callback_url`, a wyniki również zawierają `task_id`, aby umożliwić powiązanie. ```json theme={null} { "task_id": "f7096c6c-9430-4392-8201-d259632d7afd" } ``` Gdy zadanie zostanie zakończone, zawartość wysyłana do `callback_url` wygląda następująco: ```json theme={null} { "success": true, "task_id": "f7096c6c-9430-4392-8201-d259632d7afd", "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a", "data": { "task_id": "cgt-20251222073134-54qcw", "status": "succeeded", "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` Pole `task_id` w wynikach jest zgodne z tym, które zostało zwrócone podczas żądania, dzięki czemu można powiązać zadania. ## Obsługa błędów Podczas wywoływania API, jeśli wystąpią błędy, API zwróci odpowiedni kod błędu i informacje. Na przykład: * `400 token_mismatched`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. * `400 api_not_implemented`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. * `401 invalid_token`: Niedozwolone, nieprawidłowy lub brakujący token autoryzacyjny. * `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": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Wnioski Dzięki temu dokumentowi zrozumieliście, jak używać API SeeDance Videos Generation do generowania wideo za pomocą podanych słów, zdjęć referencyjnych oraz odniesień do twarzy / postaci w Seedance 2.0. Mamy nadzieję, że ten dokument pomoże Wam lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, prosimy o kontakt z naszym zespołem wsparcia technicznego.