Jak używać Seedance API: klucz, żądanie, odpytywanie i referencje

Aby używać Seedance API, utwórz klucz API, wyślij oficjalną treść zadania wideo ModelArk na jeden punkt końcowy i odpytuj zwrócone zadanie, aż adres URL wideo będzie gotowy. Te same kroki działają dla Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini i Seedance 2.5; zmienia się tylko wartość model i kilka limitów specyficznych dla modelu.

Ten poradnik przeprowadza cię przez każdy krok z działającym kodem, a potem pokazuje, jak dodać referencje, edytować klip w Seedance 2.5 i przekazać zadanie agentowi AI do programowania.

Czego potrzebujesz przed pierwszym żądaniem?

1. Klucza API. Utwórz go na stronie kluczy API i trzymaj na swoim serwerze. Nigdy nie umieszczaj go w kodzie przeglądarki.
2. Kredytów. Doładuj saldo na stronie rozliczeń. Kredyty nigdy nie wygasają, a nieudane zadania nie są rozliczane.
3. ID modelu. Wybierz jedno z tabeli poniżej.

Nie wiesz, który wybrać? Przewodnik Seedance 2.0 vs Fast vs Mini i przewodnik Seedance 2.5 vs 2.0 je porównują.

export SEEDROUTER_API_KEY="your-key"

Jak wysłać żądanie do Seedance?

Wyślij zadanie metodą POST na /v1/contents/generations/tasks. Treść to oficjalne żądanie ModelArk „create a video generation task” (utworzenie zadania generowania wideo):

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

Odpowiedzią jest identyfikator zadania, a nie wideo:

{"id": "task_..."}

Jeśli już wywołujesz ModelArk, zmień tylko bazowy adres URL na https://api.seedrouter.ai/v1 i klucz API. Nieznane pola są odrzucane, zanim cokolwiek zostanie naliczone, podobnie jak ustawienie, którego model nie obsługuje, na przykład 1080p w Fast lub Mini.

Jak odebrać wideo?

Odpytuj zadanie co 10–20 sekund, aż status będzie succeeded, failed lub expired. 5-sekundowy klip 720p zwykle zajmuje dwie do trzech minut. W Pythonie:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/contents/generations/tasks",
    headers=headers,
    json={
        "model": "dreamina-seedance-2-0",
        "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(f"{API}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "succeeded":
        print(task["content"]["video_url"])
        break
    if task["status"] in ("failed", "expired"):
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Zakończone powodzeniem zadanie zawiera wideo w content.video_url, rozliczone tokeny wideo w usage.completion_tokens oraz ustawienia, z którymi faktycznie wyrenderowano klip, w tym seed wybrany przez model. Wideo jest przechowywane w naszym magazynie; jeśli potrzebujesz go na dłużej, pobierz je do własnego.

Przekroczenie limitu czasu podczas odpytywania nie oznacza, że wideo się nie udało. Zachowaj identyfikator zadania i sprawdź je ponownie; wysłanie nowego zadania oznacza zapłatę za drugie wideo. Nie ma adresu URL wywołania zwrotnego (callback), więc wynik odbierasz przez odpytywanie, a wysłanego zadania nie można anulować.

Jak dodać obrazy, wideo i audio?

Dodaj elementy do content, każdy z publicznym adresem URL i polem role:

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

Seedance 2.0 oraz jego wersje Fast i Mini przyjmują do 9 obrazów referencyjnych, 3 filmów i 3 ścieżek audio; Seedance 2.5 do 30, 10 i 10. Multimedia muszą być adresami URL: base64 i przesyłanie plików nie są akceptowane. Model nie obsługuje obrazów ani filmów referencyjnych z prawdziwymi ludzkimi twarzami. Multimedia są sprawdzane na starcie zadania, a plik przekraczający limit kończy zadanie niepowodzeniem przed jakimkolwiek generowaniem, bez opłaty.

Jak edytować lub przedłużyć klip w Seedance 2.5?

Wyślij klip jako reference_video i ustaw omni_reference_task_type:

{
  "model": "dreamina-seedance-2-5",
  "content": [
    {"type": "text", "text": "Change the jacket to red. Keep everything else the same."},
    {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}, "role": "reference_video"}
  ],
  "omni_reference_task_type": "edit"
}

Użyj edit, aby zmienić zawartość materiału, a extend, aby kontynuować go za ostatnią klatką. Przy edit zostaw duration na domyślnej wartości -1; w obu przypadkach zostaw ratio jako adaptive. Sekundy wejściowe są rozliczane według stawki referencyjnej, jak wyjaśnia przewodnik po cenach.

Jak pozwolić agentowi AI korzystać z Seedance API?

Agent AI do programowania, taki jak Claude Code, Codex czy Cursor, może wywołać API poleceniem powłoki lub krótkim skryptem. SeedRouter nie udostępnia serwera MCP, gotowego skilla ani węzła ComfyUI; ten prompt to cała integracja. Najpierw wyeksportuj klucz, a potem wklej:

Use the SeedRouter API to generate a Seedance video for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, action, camera move, lighting, what the clip is for]
Model: [dreamina-seedance-2-0 | dreamina-seedance-2-0-fast | dreamina-seedance-2-0-mini | dreamina-seedance-2-5]
Resolution: [480p | 720p | 1080p | 4k]    Ratio: [16:9 | 9:16 | 1:1 | adaptive]    Duration: [seconds]
References: [public image, video or audio URLs with their roles, or none]

Send POST https://api.seedrouter.ai/v1/contents/generations/tasks with
{"model": "...",
 "content": [{"type": "text", "text": "..."}],
 "resolution": "...", "ratio": "...", "duration": 5}
Media goes in content as image_url, video_url or audio_url items with a role,
never base64. Do not add fields that are not in the API reference.

Before sending, show me the request body and wait for my approval: each
task is charged. Then poll GET https://api.seedrouter.ai/v1/contents/generations/tasks/{id}
every 15 seconds until status is succeeded, failed or expired. If polling
times out, keep checking the same task; never resubmit. Save
content.video_url into ./videos/ and tell me the file path.

Krok zatwierdzenia jest ważny: agent wydaje twoje saldo, więc nigdy nie powinien wysyłać zadań sam z siebie.

Najczęściej zadawane pytania

Jak uzyskać klucz do Seedance API?

Zaloguj się, otwórz stronę kluczy API i utwórz klucz. Ten sam klucz działa dla każdego modelu Seedance i dla pozostałych modeli w SeedRouter.

Gdzie znajdę dokumentację Seedance API?

Dokumentacja API Seedance 2.0 i Seedance 2.5 wymienia każde pole, limit i błąd, z przykładami w cURL, Pythonie, Node.js i Go, a także plik OpenAPI i wersję Markdown do skopiowania.

Czy mogę generować kilka filmów naraz?

Wysyłaj jedno zadanie na film i odpytuj zadania równolegle. Każde zadanie zwraca jeden film i jest rozliczane osobno. Aby wyświetlić ostatnie zadania, wywołaj GET /v1/contents/generations/tasks z page_num, page_size i filtrami takimi jak filter.status.

Jakie błędy powinienem obsłużyć?

Kod 400 oznacza, że treść naruszyła regułę, na przykład zawiera nieznane pole lub nieobsługiwaną rozdzielczość, i nic nie jest naliczane. Zadanie zakończone jako failed lub expired zawiera kod i komunikat błędu i również nie jest rozliczane. Przewodnik po błędach wymienia każdy kod i podpowiada, kiedy ponowić próbę.

Wyślij pierwsze żądanie

Utwórz klucz, doładuj niewielkie saldo i uruchom powyższy przykład w Pythonie albo wypróbuj to samo żądanie bez kodu w playgroundzie Seedance 2.0. Przy dłuższych klipach i edycji zmień model na dreamina-seedance-2-5 i zajrzyj na stronę Seedance 2.5.