Przejdź do głównej treści
W tym artykule zostanie przedstawiona instrukcja integracji API SeeDance Videos Generation, które umożliwia generowanie oficjalnych filmów SeeDance poprzez wprowadzenie niestandardowych parametrów.

Proces aplikacji

Aby korzystać z API SeeDance Videos Generation, 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(-a) ani zarejestrowany(-a), zostaniesz automatycznie przekierowany(-a) na stronę logowania, która zaprosi Cię do rejestracji i logowania; po zakończeniu automatycznie powrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez potrzeby składania osobnego wniosku dla każdej usługi. Przy pierwszym wniosku otrzymasz darmowy limit, który pozwoli na bezpłatne testowanie; gdy limit będzie niewystarczający, możesz doładować uniwersalne saldo w konsoli.
📘 Pełna dokumentacja: SeeDance Videos Generation API →

Podstawowe użycie

Najpierw zapoznajmy się z podstawowym sposobem użycia: wystarczy wprowadzić prompt content.text, typ content.type=text oraz model model, aby uzyskać przetworzony wynik; szczegółowa zawartość jest następująca:

Można zauważyć, że ustawiliśmy tutaj Request Headers, w tym:
  • accept: format odpowiedzi, który chcesz otrzymać; tutaj należy wpisać application/json, czyli format JSON.
  • authorization: klucz do wywoływania API, po złożeniu wniosku można go bezpośrednio wybrać z listy rozwijanej.
Dodatkowo ustawiliśmy Request Body, w tym:
  • model: model do generowania filmów.
    • 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 wielomodalne odniesienia do postaci oraz audio-wideo): doubao-seedance-2-0-260128 (standardowy), doubao-seedance-2-0-fast-260128 (szybki), doubao-seedance-2-0-mini-260615 (lekki).
    • Seedance 2.5: doubao-seedance-2-5-260628, obsługuje maksymalnie 30 sekund, odniesienia wyłącznie audio, więcej materiałów, edycję i rozszerzanie filmów.
  • content: tablica treści wejściowej, type może być text (prompt), image_url (obraz referencyjny), audio_url (audio referencyjne), video_url (wideo referencyjne). Do obrazów można przypisać zastosowanie poprzez role: first_frame (pierwsza klatka) / last_frame (ostatnia klatka) / reference_image (odniesienie do postaci / obiektu).
  • resolution: rozdzielczość wyjściowa, do wyboru 480p / 720p / 1080p / 4k. Wersja 2.5 obsługuje 480p, 720p, 1080p; 2.0 Fast/Mini obsługuje 480p, 720p; 2.0 Standard obsługuje maksymalnie 4k.
  • ratio: proporcje obrazu, do wyboru 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: czas trwania filmu (sekundy, liczba całkowita). Seria 1.0: 2–12; 1.5 Pro: 4–12; seria 2.0: 4–15; 2.5: 4–30. Wersje 1.5/2.x obsługują -1 (automatyczny czas trwania).
  • seed: losowe ziarno, liczba całkowita od -1 do 4294967295.
  • camerafixed: czy kamera ma być nieruchoma, true / false.
  • watermark: czy dodać znak wodny, true / false.
  • generate_audio: czy generować film z dźwiękiem, true / false, obsługiwane przez Seedance 1.5 Pro oraz serię 2.x.
  • return_last_frame: czy zwrócić w wynikach adres URL obrazu ostatniej klatki filmu.
  • omni_reference_task_type: tylko 2.5; auto / reference / edit / extend.
  • output_format: tylko 2.5; mp4 / mov, domyślnie mp4.
  • tools: tylko 2.5; obecnie obsługiwane jest narzędzie wyszukiwania internetowego web_search, które może ograniczać liczbę wyników, liczbę słów kluczowych i źródła wyszukiwania.
  • priority: opcjonalny priorytet zadania dla 2.5, liczba całkowita 0–9, domyślnie 0.
  • safety_identifier: stabilny anonimowy identyfikator użytkownika końcowego o długości maksymalnie 64 znaków; użyj hasha lub wewnętrznego anonimowego ID, nie przekazuj imienia i nazwiska, adresu e-mail ani numeru telefonu.
  • execution_expires_after: limit czasu zadania (sekundy), zakres 3600–259200.
  • callback_url: adres asynchronicznego wywołania zwrotnego; po ustawieniu API natychmiast zwraca task_id, a po ukończeniu zadania wynik zostanie wysłany metodą POST na ten adres.
  • async: opcjonalne; po ustawieniu na true interfejs natychmiast zwraca task_id, bez konieczności podawania callback_url, a następnie wynik można uzyskać poprzez odpytywanie odpowiedniego interfejsu zapytań o zadania.
Po dokonaniu wyboru można zauważyć, że po prawej stronie został również wygenerowany odpowiedni kod, jak pokazano na ilustracji:

Kliknij przycisk „Try”, aby przeprowadzić test; jak pokazano na powyższej ilustracji, otrzymaliśmy tutaj następujący wynik:
Zwrócony wynik zawiera wiele pól, opisanych poniżej:
  • success, stan zadania generowania filmu w tym momencie.
  • task_id, ID zadania generowania filmu w tym momencie.
  • trace_id, ID śledzenia generowania filmu w tym momencie.
  • data, lista wyników zadania generowania filmu w tym momencie.
    • task_id, ID po stronie serwera zadania generowania filmu w tym momencie.
    • video_url, link do filmu zadania generowania filmu w tym momencie.
    • status, stan zadania generowania filmu w tym momencie.
      • model, model użyty do wygenerowania filmu.
Można zauważyć, że otrzymaliśmy satysfakcjonujące informacje o filmie; wystarczy pobrać wygenerowany film SeeDance na podstawie adresu linku do filmu w data w wyniku. Ponadto, jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować; na przykład kod CURL jest następujący:

Opis parametrów inline

Na końcu promptu content[].text można przekazać parametry generowania, dodając je w formacie --parameter value (stary sposób, słaba walidacja, w przypadku błędnych wartości automatycznie używane są wartości domyślne). Pełna lista parametrów jest następująca:
Zalecana praktyka: bezpośrednio używaj odpowiednich pól najwyższego poziomu w Request Body (takich jak resolution, ratio itd.). Jest to tryb ścisłej walidacji — w przypadku błędnych parametrów zostanie zwrócony jednoznaczny komunikat o błędzie, co ułatwia diagnozowanie problemów.

Generowanie filmów z dźwiękiem

Seedance 1.5 Pro oraz serie 2.x obsługują generowanie filmów z dźwiękiem za pomocą parametru generate_audio:
Seria 1.0 nie obsługuje tego parametru.

Pełnomodalne generowanie, edycja i rozszerzanie Seedance 2.5

doubao-seedance-2-5-260628 obsługuje 480p / 720p / 1080p, 4–30 sekund lub automatyczny czas trwania, a limit materiałów został zwiększony do 30 obrazów referencyjnych, 10 referencyjnych filmów i 10 referencyjnych nagrań audio (łącznie maksymalnie 50). Wersja 2.5 obsługuje również przekazywanie wyłącznie referencyjnego audio, bez wymogu jednoczesnego dostarczania obrazów lub filmów. W przypadku zwykłego pełnomodalnego generowania można pominąć omni_reference_task_type, ustawić je na auto lub jawnie ustawić na reference. Edycja i rozszerzanie filmów muszą przekazywać reference_video:
  • reference: przekaż co najmniej jeden reference_image, reference_video lub reference_audio; wersja 2.5 obsługuje przekazywanie wyłącznie referencyjnego audio.
  • edit: należy użyć ratio: adaptive i duration: -1; czas trwania wyjścia jest rozliczany na podstawie rzeczywistego wyniku.
  • extend: należy użyć ratio: adaptive; duration może wynosić 4–30 lub -1.
  • auto: model automatycznie wybiera generowanie, edycję lub rozszerzanie na podstawie promptu i materiałów.
  • Jeśli typ zadania nie odpowiada materiałom lub promptowi, zadanie zakończy się niepowodzeniem i zwróci możliwy do zidentyfikowania błąd parametru; dostosuj ustawienia zgodnie z powyższymi ograniczeniami i prześlij ponownie.

Pierwsza klatka obrazu do filmu

Jeśli chcesz wykonać zadanie obrazu do filmu, parametr content musi najpierw zawierać element z type ustawionym na image_url, a pole image_url musi mieć format obiektu: {"url": "https://..."} lub format Base64 {"url": "data:image/png;base64,..."}.
Uwaga: image_url nie obsługuje bezpośredniego przekazywania w formacie ciągu znaków (np. "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"). Należy użyć formatu obiektu "image_url": {"url": "https://..."}, w przeciwnym razie zostanie zwrócony błąd 400.
Odpowiedni kod:
Po kliknięciu uruchomienia można zauważyć, że wynik zostanie uzyskany natychmiast, jak poniżej:
Można zobaczyć, że wygenerowany efekt to tworzenie filmu na podstawie obrazu, a wynik jest podobny do opisanego powyżej.

Pierwsza i ostatnia klatka obrazu do filmu

Jeśli chcesz utworzyć pierwszą i ostatnią klatkę obrazu do filmu, parametr content musi najpierw przekazać typ image_url, a następnie odpowiednio ustawić role na first_frame i last_frame, aby określić następującą zawartość:
  • role: określa pierwszą lub ostatnią klatkę.
  • image_url
    • link url obrazu Jednocześnie content musi również zawierać typ text jako prompt.
Odpowiedni kod:
Kliknij uruchom, można zauważyć, że natychmiast zostanie uzyskany wynik, jak poniżej:
Można zauważyć, że wygenerowany efekt to film wideo z postacią, a wynik jest podobny do opisanego powyżej.

Referencje multimodalne postaci oraz audio i wideo (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 reference_image, reference_audio oraz reference_video. Można używać własnych lub autoryzowanych materiałów, aby zachować spójność postaci, obiektów, ruchów, pracy kamery, dźwięku i rytmu.
Przesyłaj wyłącznie własne lub autoryzowane materiały z prawdziwymi osobami i postaciami. Różne modele w odmienny sposób obsługują materiały z prawdziwymi osobami; format żądania pozostaje bez zmian, a jeśli materiały nie spełniają wymagań, zostanie zwrócony jednoznaczny błąd.
Kluczowe informacje dotyczące użycia:
  • Tylko modele serii Seedance 2.0 obsługują reference_image; w przypadku modeli 1.x użyj first_frame / last_frame (pierwszej i ostatniej klatki obrazu do filmu).
  • Pierwsza klatka obrazu do filmu, pierwsza i ostatnia klatka obrazu do filmu oraz referencja pełnomodalna to trzy wzajemnie wykluczające się scenariusze: first_frame / last_frame nie mogą być używane razem z reference_image / reference_video / reference_audio.
  • Jeśli chcesz określić pierwszą i ostatnią klatkę w referencji pełnomodalnej, oznacz obrazy jako reference_image i w promptcie napisz „obraz 1 jako pierwsza klatka” lub „obraz 2 jako ostatnia klatka”; jeśli wymagane jest ścisłe zablokowanie pierwszej i ostatniej klatki, używaj wyłącznie first_frame / last_frame.
  • Górny limit liczby referencji multimodalnych: maksymalnie 9 image_url; wersja 2.0 obsługuje również audio_url (role to reference_audio, maksymalnie 3 pozycje) oraz video_url (role to reference_video, maksymalnie 3 pozycje).
  • Wymagania dotyczące materiałów referencyjnych audio (audio_url): format wav / mp3; czas trwania pojedynczego pliku 2–15 sekund, maksymalnie 3 pliki, a łączny czas trwania nie przekracza 15 sekund; pojedynczy plik nie może przekraczać 15 MB. Przekroczenie zakresu czasu trwania spowoduje niepowodzenie na etapie przetwarzania materiału.
  • Wymagania dotyczące materiałów referencyjnych wideo (video_url): format mp4 / mov; czas trwania pojedynczego pliku 2–15 sekund, maksymalnie 3 pliki, a łączny czas trwania nie przekracza 15 sekund.
  • Dla obrazów referencyjnych zaleca się zdjęcia jednej osoby, twarzą na wprost, wyraźne, bez zasłonięć; im wyraźniejsza twarz, tym większe podobieństwo.

Przykład pierwszy: zbliżenie zachowujące wygląd osoby

Przekaż zdjęcie twarzy, aby ta osoba uśmiechała się i machała do kamery. Odpowiedni kod:
Wynik zwracany jest jak poniżej, osoba w wygenerowanym filmie pozostaje zgodna ze zdjęciem referencyjnym:

Przykład drugi: umieszczenie tej samej osoby w zupełnie nowej scenie

Siła reference_image polega na tym, że zachowuje tylko tożsamość osoby, podczas gdy scena, ubiór i ruch są całkowicie określane przez prompt. Poniżej, przy użyciu tego samego zdjęcia twarzy, osoba nosi beżowy płaszcz i spaceruje po jesiennym parku:
Wynik zwracany jest jak poniżej, wygląd osoby zostaje zachowany, a scena została przełączona na jesienny park:
💡 Jeśli chcesz, aby postać dokładnie odtworzyła kompozycję ze zdjęcia (a nie „ta sama osoba w innej scenerii”), możesz zamiast tego użyć first_frame (pierwsza klatka wideo generowanego z obrazu), aby wideo zaczynało ruch od tego zdjęcia.

Asynchroniczne wywołanie zwrotne

Ponieważ czas generowania przez SeeDance Videos Generation API jest długi (około 1–2 minuty), można użyć trybu asynchronicznego za pośrednictwem pola callback_url, aby uniknąć długotrwałego zajmowania połączenia HTTP. Ogólny proces: klient podczas inicjowania żądania określa callback_url, API natychmiast zwraca odpowiedź zawierającą task_id; po zakończeniu zadania platforma wysyła wynik generowania w formie POST JSON do callback_url, a wynik również zawiera task_id w celu powiązania.
Po zakończeniu zadania platforma wysyła następującą treść do callback_url:
Pole task_id w wyniku jest zgodne z tym zwróconym podczas żądania, a za pomocą tego pola można realizować powiązanie zadań.

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 token_mismatched:Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 400 api_not_implemented:Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 401 invalid_token:Brak autoryzacji, nieprawidłowy lub brakujący token autoryzacyjny.
  • 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 dowiedziałeś się już, jak używać Seedance Videos Generation API do generowania wideo z tekstu, generowania z pierwszej i ostatniej klatki oraz generowania z odniesieniami multimodalnymi, a także jak używać Seedance 2.5 do edycji lub wydłużania wideo. Mamy nadzieję, że ten dokument pomoże Ci ukończyć integrację API; w razie pytań skontaktuj się ze wsparciem technicznym.