Skip to main content
W tym artykule przedstawimy sposób integracji z SeeDance Videos Generation API, które pozwala na 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, aby uzyskać swój token API, który należy zachować na przyszłość. 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.
📘 Pełna dokumentacja: SeeDance Videos Generation API →

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 odniesienia multimodalne do postaci i audio-wideo): doubao-seedance-2-0-260128 (standard), 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, czyste odniesienia audio, więcej materiałów, edycję wideo i wydłużanie.
  • content: tablica wprowadzonych treści, type może być text (słowa kluczowe), image_url (zdjęcie referencyjne), audio_url (audio referencyjne), video_url (wideo referencyjne). Obraz można określić za pomocą role: first_frame (pierwsza klatka) / last_frame (ostatnia klatka) / reference_image (odniesienie do postaci / podmiotu).
  • resolution: rozdzielczość wyjściowa, do wyboru 480p / 720p / 1080p / 4k. 2.5 obsługuje 480p, 720p, 1080p; 2.0 Fast/Mini obsługuje 480p, 720p; 2.0 Standard obsługuje maksymalnie 4k.
  • ratio: proporcje, do wyboru 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: długość wideo (sekundy, liczba całkowita). Seria 1.0 2–12; 1.5 Pro 4–12; seria 2.0 4–15; 2.5 to 4–30. 1.5/2.x obsługuje -1 (automatyczna długość).
  • seed: losowe ziarno, liczba całkowita, -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, obsługiwane przez Seedance 1.5 Pro i serie 2.x.
  • return_last_frame: czy w wynikach zwrócić URL ostatniej klatki wideo.
  • 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 narzędzie web_search do wyszukiwania w sieci, można ograniczyć liczbę wyników, liczbę słów kluczowych i źródła wyszukiwania.
  • priority: 2.5 opcjonalny priorytet zadania, liczba całkowita 0–9, domyślnie 0.
  • safety_identifier: stabilny, anonimowy identyfikator użytkownika końcowego o maksymalnej długości 64 znaków; proszę używać haszy lub wewnętrznych anonimowych ID, nie wprowadzać imienia, adresu e-mail ani numeru telefonu.
  • 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 wyniki zostaną przesłane 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 obrazku:

Kliknij przycisk „Spróbuj”, aby przeprowadzić test, jak pokazano na powyższym obrazku, otrzymujemy następujący wynik:
Zwrócone wyniki zawierają 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 w tym momencie.
    • video_url, link do wideo generowanego 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 na podstawie adresu URL wideo w data uzyskamy wygenerowane wideo SeeDance. Dodatkowo, jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco:

Opis parametrów inline

W content[].text na końcu podpowiedzi można przekazać parametry generacji w formie --parameter value (stary sposób, słaba walidacja, w przypadku błędnego wypełnienia automatycznie używane są wartości domyślne). Pełna lista parametrów wygląda następująco:
Zalecana praktyka: Bezpośrednio w ciele żądania użyj odpowiednich pól najwyższego poziomu (np. resolution, ratio itp.), aby uzyskać tryb silnej walidacji, w przypadku błędnego wypełnienia parametrów zwróci wyraźny komunikat o błędzie, co ułatwia diagnozowanie problemów.

Generowanie wideo z dźwiękiem

Seedance 1.5 Pro i seria 2.x wspierają generowanie wideo z dźwiękiem za pomocą parametru generate_audio:
Seria 1.0 nie wspiera tego parametru.

Seedance 2.5 Generowanie, edytowanie i wydłużanie w trybie multimodalnym

doubao-seedance-2-5-260628 wspiera 480p / 720p / 1080p, 4–30 sekund lub automatyczny czas trwania, a także zwiększa limit materiałów do 30 obrazów referencyjnych, 10 klipów wideo referencyjnych, 10 klipów audio referencyjnych (łącznie maksymalnie 50). 2.5 wspiera również przesyłanie tylko audio referencyjnego, bez konieczności jednoczesnego dostarczania obrazów lub wideo. Zwykłe generowanie multimodalne można pominąć omni_reference_task_type, ustawić na auto lub jawnie ustawić na reference. Edytowanie wideo i wydłużanie musi zawierać reference_video:
  • reference: Należy przesłać przynajmniej jeden reference_image, reference_video lub reference_audio; 2.5 wspiera tylko przesyłanie audio referencyjnego.
  • edit: Należy użyć ratio: adaptive i duration: -1; czas trwania wyjścia rozliczany jest na podstawie rzeczywistego wyniku.
  • extend: Należy użyć ratio: adaptive; duration może wynosić 4–30 lub -1.
  • auto: Model automatycznie wybiera generowanie, edytowanie lub wydłużanie na podstawie podpowiedzi i materiałów.
  • Gdy typ zadania nie pasuje do materiałów lub podpowiedzi, zadanie zakończy się niepowodzeniem i zwróci błąd parametrów, który można zlokalizować; proszę dostosować zgodnie z powyższymi ograniczeniami i ponownie przesłać.

Generowanie wideo z pierwszą klatką

Jeśli chcesz wygenerować wideo z pierwszą klatką, najpierw parametr content musi zawierać element o type równym image_url, a pole image_url musi być w formacie obiektowym: {"url": "https://..."} lub w formacie Base64 {"url": "data:image/png;base64,..."}.
Uwaga: image_url nie wspiera bezpośredniego przesyłania w formacie string (np. "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"), musi być użyty format obiektowy "image_url": {"url": "https://..."}, w przeciwnym razie zwróci błąd 400.
Odpowiedni kod:
Klikając uruchom, można zauważyć, że natychmiast otrzymuje się wynik, jak poniżej:
Można zauważyć, że wygenerowany efekt to wideo stworzone na podstawie obrazu, a wynik jest podobny do powyższego.

Generowanie wideo z pierwszą i ostatnią klatką

Jeśli chcesz wygenerować wideo z pierwszą i ostatnią klatką, 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 podpowiedź.
Odpowiedni kod:
Kliknij uruchom, a natychmiast otrzymasz wynik, jak poniżej:
Można zauważyć, że wygenerowany efekt to wideo z postacią, a wynik jest podobny do powyższego.

Postacie i multimodalne odniesienia audio-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, tematu, ruchów, ujęć, dźwięku i rytmu.
Proszę przesyłać tylko własne lub autoryzowane materiały z prawdziwymi osobami i postaciami. Różne modele mają różne sposoby wsparcia dla materiałów z prawdziwymi osobami; format żądania pozostaje niezmienny, jeśli materiały nie spełniają wymagań, zwróci wyraźny błąd.
Wskazówki dotyczące użycia:
  • Tylko modele z serii Seedance 2.0 obsługują reference_image; modele 1.x należy używać first_frame / last_frame (pierwsza i ostatnia klatka wideo).
  • Pierwsza klatka wideo, pierwsza i ostatnia klatka wideo oraz pełne odniesienia 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 pełnym odniesieniu, oznacz zdjęcie jako reference_image i w opisie napisz “zdjęcie 1 jako pierwsza klatka” lub “zdjęcie 2 jako ostatnia klatka”; jeśli potrzebujesz ściśle zablokować pierwszą i ostatnią klatkę, użyj tylko first_frame / last_frame.
  • Limit liczby odniesień multimodalnych: maksymalnie 9 zdjęć image_url; 2.0 obsługuje również audio_url (rola reference_audio, maksymalnie 3) oraz video_url (rola reference_video, maksymalnie 3).
  • Wymagania dotyczące materiałów audio (audio_url): format wav / mp3; długość pojedynczego utworu 2~15 sekund, maksymalnie 3 utwory i łączna długość nie przekracza 15 sekund; pojedynczy utwór nie przekracza 15 MB. Przekroczenie zakresu długości spowoduje niepowodzenie w etapie przetwarzania materiałów.
  • Wymagania dotyczące materiałów wideo (video_url): format mp4 / mov; długość pojedynczego utworu 2~15 sekund, maksymalnie 3 utwory i łączna długość nie przekracza 15 sekund.
  • Zaleca się używanie zdjęć pojedynczych, frontalnych, wyraźnych, bez przeszkód; im wyraźniejsza twarz, tym wyższa podobieństwo.

Przykład 1: Zbliżenie zachowujące wygląd postaci

Przekaż zdjęcie twarzy, aby ta postać uśmiechała się i machała do kamery. Odpowiedni kod:
Wynik zwrotny wygląda następująco, w wygenerowanym wideo postać zachowuje zgodność z referencyjnym zdjęciem:

Przykład 2: Umieszczenie tej samej osoby w nowej scenerii

Potęga reference_image polega na tym, że: zachowuje tylko tożsamość postaci, podczas gdy sceneria, ubranie i ruchy są całkowicie określone przez opis. Poniżej używamy tego samego zdjęcia twarzy, aby postać w beżowym płaszczu spacerowała po jesiennym parku:
Wynik zwrotny wygląda następująco, wygląd postaci został zachowany, a sceneria zmieniła się na jesienny park:
💡 Jeśli chcesz, aby postać dokładnie odwzorowała kompozycję ze zdjęcia (a nie „zmieniła scenę na tę samą osobę”), możesz użyć first_frame (pierwsza klatka wideo), aby wideo zaczęło się poruszać od tego zdjęcia.

Asynchroniczny callback

Ponieważ czas generacji 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ługotrwałego 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.
Gdy zadanie zostanie zakończone, zawartość wysyłana do callback_url przez platformę jest następująca:
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łąd, 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: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczono limit szybkości.
  • 500 api_error: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

Przykład odpowiedzi błędu

Wnioski

Dzięki temu dokumentowi zrozumiałeś, jak korzystać z API Seedance Videos Generation do generowania wideo z tekstu, pierwszej i ostatniej klatki oraz generowania multimodalnych odniesień, a także jak edytować lub wydłużać wideo za pomocą Seedance 2.5. Mamy nadzieję, że ten dokument pomoże Ci w integracji API; w razie pytań skontaktuj się z pomocą techniczną.