how-tos

Seedance 2.5 API: przewodnik — wywołanie Seedance 2.5 Flash z cURL i Pythona

Poyo.ai Team
10 min read
Share:

Kurier na rowerze ścigający się z wieżą zegarową o świcie, ilustracja redakcyjna do przewodnika po Seedance 2.5 Flash API

Seedance 2.5 Flash API to szybszy i tańszy poziom Seedance 2.5 API, a w PoYo jest to jeden ID modelu: seedance-2.5-flash. ByteDance wydało go 12 listopada 2026; na stronie modelu Seedance 2.5 Flash znajdziesz playground i aktualne ceny. Ten przewodnik prowadzi od pierwszego żądania cURL do produkcyjnej pętli w Pythonie, korzystając ze schematu z dokumentacji Seedance 2.5 Flash API, sprawdzonego 16 listopada 2026.

Seedance 2.5 Flash API w skrócie

ElementWartość
Endpoint wysyłaniaPOST https://api.poyo.ai/api/generate/submit
Endpoint statusuGET https://api.poyo.ai/api/generate/status/{task_id}
Nagłówek uwierzytelnianiaAuthorization: Bearer $POYO_API_KEY
ID modeluseedance-2.5-flash (slug strony seedance-2-5-flash nie jest ID modelu)
Pola wymaganeprompt, duration
Czas trwaniaPełne sekundy, 4–30
Rozdzielczość480p lub 720p, domyślnie 720p
Proporcje obrazuauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, domyślnie auto
Audiogenerate_audio, domyślnie true
Dostarczenie wynikuZadanie asynchroniczne: odpytuj o status lub ustaw callback_url

Pierwsze żądanie do Seedance 2.5 API w cURL

Wyeksportuj klucz jako POYO_API_KEY i trzymaj go na serwerze, nigdy w kodzie przeglądarki. To 5-sekundowe żądanie text-to-video w 480p, tani pierwszy test za 92,5 kredytu:

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash",
    "input": {
      "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
      "duration": 5,
      "resolution": "480p",
      "aspect_ratio": "16:9"
    }
  }'

Udane wysłanie zwraca code: 200 i obiekt data z task_id, status (zaraz po wysłaniu zawsze not_started) i created_time. To potwierdzenie, a nie wideo. Zapisz task_id, a następnie zapytaj o status:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Statusy przechodzą przez not_started, running, finished i failed. Gdy zadanie ma status finished, URL wideo znajduje się w data.files[].file_url z file_type: "video"; przy failed odczytaj data.error_message. Wygenerowane pliki są dostępne przez 3 dni, więc kopiuj je do własnego magazynu.

Python: wysyłanie i odpytywanie z twardym terminem

Dokumentacja statusu zaleca odpytywanie co 2–5 sekund, wydłużanie odstępu przy 429 i 5xx oraz zawsze ustawianie limitu czasu. Poniższa pętla robi wszystkie trzy rzeczy i nigdy nie wysyła zadania ponownie po przekroczeniu czasu, bo drugie wysłanie to drugie płatne zadanie.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    try:
        body = response.json()
    except ValueError:
        response.raise_for_status()
        raise
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(
            f"PoYo {body.get('code')} {err.get('type')}: "
            f"{err.get('message') or body.get('detail')}"
        )
    return body["data"]


task = checked(session.post(BASE + "/api/generate/submit", json={
    "model": "seedance-2.5-flash",
    "input": {
        "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
        "duration": 5,
        "resolution": "480p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)

deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
    r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
    if r.status_code == 429 or r.status_code >= 500:
        time.sleep(backoff)
        backoff = min(backoff * 2, 60)
        continue
    data = checked(r)
    if data["status"] == "failed":
        raise RuntimeError(data.get("error_message") or "Generation failed")
    if data["status"] == "finished":
        videos = [f["file_url"] for f in data.get("files", [])
                  if f.get("file_type") == "video"]
        print(videos[0], "credits:", data.get("credits_amount"))
        break
    backoff = 5
    time.sleep(5)
else:
    raise TimeoutError("Still running; poll the saved task ID later: " + task_id)

Dla orientacji: w testach PoYo 16 listopada 2026 4-sekundowy klip w 480p był gotowy po około dwóch minutach, a 30-sekundowy klip w 720p w mniej niż trzy minuty, licząc od początku do końca. Czasy zależą od obciążenia, więc 15-minutowy termin to granica bezpieczeństwa, a nie szacunek.

Bez odpytywania: użyj callback_url

Dodaj callback_url na najwyższym poziomie obok model. Gdy zadanie przejdzie w stan finished lub failed, PoYo wyśle POST, którego treścią jest obiekt danych zadania (task_id, status, files, created_time, error_message) bez opakowania code/data. Zgodnie z dokumentacją webhooków wideo:

  • URL musi być publicznym adresem HTTPS, o długości najwyżej 2048 znaków, bez prywatnych adresów IP.
  • Odpowiedz kodem 2xx w ciągu 30 sekund; nieudane dostarczenia są ponawiane do 5 razy z wykładniczym backoffem.
  • Weryfikuj X-Webhook-Signature jako base64(HMAC-SHA256(task_id + "." + timestamp, key)), gdzie timestamp pochodzi z X-Webhook-Timestamp, a klucz z GET /api/api-keys/webhook-secret.
  • Zrób handler idempotentnym. Jeśli wszystkie ponowienia się nie powiodą, wynik nadal jest dostępny w endpoincie statusu.

Trzy tryby wejścia z treściami JSON

API wybiera tryb na podstawie wysłanych mediów. Nie ma pola mode.

TrybWybierany, gdyProporcje obrazu
Reference-to-videoKtórekolwiek z reference_image_urls, reference_video_urls, reference_audio_urls jest niepusteDowolna obsługiwana wartość
Image-to-video (pierwsza/ostatnia klatka)image_urls jest niepusteauto lub pomiń; wyjście dopasowuje się do pierwszej klatki
Text-to-videoBrak mediówDowolna obsługiwana wartość

image_urls i pola referencji wysyła się w osobnych żądaniach. Poniższe treści żądań to przykłady z dokumentacji.

Text-to-video (30 sekund w 720p, z rozpisaną w czasie listą ujęć w prompcie):

{
  "model": "seedance-2.5-flash",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
    "duration": 30,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}

Pierwsza i ostatnia klatka (jeden URL ustala początek, drugi zakończenie):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  }
}

Reference-to-video (odwołuj się do plików według kolejności wgrania jako @Image1, @Video1, @Audio1):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
    "reference_image_urls": [
      "https://example.com/cat.png",
      "https://example.com/scarf.png",
      "https://example.com/bookstore.png"
    ],
    "reference_audio_urls": [
      "https://example.com/rhythm.mp3"
    ],
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}

Reguły walidacji do sprawdzenia przed wysłaniem

Sprawdzanie ich po stronie klienta oszczędza jedno żądanie i daje użytkownikom jaśniejszy komunikat niż ogólny 400.

PoleReguła
promptWymagane, niepusty ciąg znaków
durationWymagana liczba całkowita, 4–30
resolutionTylko 480p lub 720p; 1080p wymaga seedance-2.5
aspect_ratioJedna z siedmiu wartości; przy image_urls użyj auto lub pomiń
image_urls1–2 URL (pierwsza, potem ostatnia klatka); JPEG, PNG lub WebP, do 30 MB każdy; nie łączy się z polami referencji
reference_image_urlsDo 10; JPEG, PNG lub WebP, do 30 MB każdy
reference_video_urlsDo 5; MP4 lub MOV, 2–30 s i do 200 MB każdy; łączna długość najwyżej 30 s
reference_audio_urlsDo 5; MP3 lub WAV, 2–30 s i do 15 MB każdy; łączna długość najwyżej 30 s; wymaga obrazu lub wideo referencyjnego
Wszystkie URL mediówPubliczne HTTP lub HTTPS, do bezpośredniego pobrania (bez stron logowania i wygasających podglądów)

Łączny czas trwania referencji jest sprawdzany przy wysyłaniu zadania. Schemat ustawia też additionalProperties: false dla input, więc nie wysyłaj pól z API innych dostawców, takich jak seed czy negative_prompt.

Błędy, które warto obsłużyć

Zawsze odczytuj pole code w treści odpowiedzi: niektóre błędy walidacji z endpointu wysyłania wracają z HTTP 200 i "code": 400. Lista kodów błędów wymienia następujące:

KodTypCo zrobić
400validation_error, file_format_error, content_moderation_errorPopraw żądanie lub media; nie ponawiaj bez zmian
401authentication_errorSprawdź nagłówek Bearer i czy klucz nadal istnieje
402insufficient_credits_errorDoładuj konto, a potem wyślij ponownie
429Limit częstotliwościOdczekaj (1 s, 2 s, 4 s...) przed kolejnym odpytaniem lub wysłaniem
500, 502, 503Serwer lub dostawca upstreamPonów zapytanie o status z backoffem; sprawdź status przed ponownym wysłaniem
Zadanie failedUstawione error_messageZaloguj ID zadania; nieudane zadania raportują credits_amount: 0

Jak liczony jest pierwszy rachunek

Bez wideo referencyjnych koszt to sekundy wyjścia pomnożone przez stawkę za sekundę: 18,5 kredytu ($0.0925) w 480p i 41 kredytów ($0.205) w 720p, przy 1 kredyt = $0.005. Wygenerowane audio nic nie dodaje.

Żądanie powyżejRozliczane sekundyKredytyUSD
Test cURL, 5 s 480p592.5$0.4625
Text-to-video, 30 s 720p301,230$6.15
Pierwsza/ostatnia klatka, 5 s 720p5205$1.025
Obrazy referencyjne + audio, 6 s 480p6111$0.555

Dodanie dowolnych reference_video_urls przełącza na niższą stawkę z wideo (11,5 kredytu w 480p, 25,5 w 720p), stosowaną do rozliczanych sekund: czasu trwania wyjścia plus długości każdego wideo referencyjnego zaokrąglonej w dół do pełnych sekund. Te przypadki omawia artykuł Cennik Seedance 2.5 API. Opłata za ukończone zadanie pojawia się jako credits_amount w odpowiedzi statusu.

Przejdź na Seedance 2.5 dla 1080p

Pola żądania są te same, więc przeniesienie zadania z Flash na standardowy model Seedance 2.5 to zmiana ID modelu:

{
  "model": "seedance-2.5",
  "input": {
    "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }
}

Dwa szczegóły: dokumentacja seedance-2.5 podaje resolution jako pole wymagane, więc zawsze je wysyłaj, a model standardowy pozwala na do 30 obrazów, 10 wideo i 10 referencji audio. W 1080p kosztuje 114 kredytów ($0.57) za sekundę. O decyzji o routingu przeczytasz w artykule Seedance 2.5 Flash vs Seedance 2.5; porównanie Seedance 2.5 z modelem innego dostawcy znajdziesz w artykule Kling 4.0 vs Seedance 2.5.

Najczęściej zadawane pytania

Jaki jest ID modelu Seedance 2.5 Flash API? seedance-2.5-flash, z kropkami. Wersja z myślnikami seedance-2-5-flash to tylko slug strony modelu.

Czy Seedance 2.5 Flash API obsługuje 1080p? Nie. Przyjmuje 480p i 720p. Dla natywnego 1080p wyślij tę samą treść z "model": "seedance-2.5" i "resolution": "1080p".

Jak wyłączyć audio w Seedance 2.5 API? Ustaw "generate_audio": false, aby otrzymać klip bez dźwięku, albo zostaw audio włączone i usuń poszczególne warstwy w prompcie, np. „no background music”.

Czy mogę użyć pierwszych klatek i obrazów referencyjnych w jednym żądaniu do Seedance 2.5 Flash? Nie. image_urls i pola reference_* muszą być wysyłane w osobnych żądaniach.

Ile trwa zadanie w Seedance 2.5 Flash API? W teście PoYo z 16 listopada 2026 około dwóch minut dla 4 sekund w 480p i mniej niż trzy minuty dla 30 sekund w 720p, licząc od początku do końca. Odpytuj o status lub użyj callbacku, zamiast trzymać otwarte żądanie.

Czy płacę, jeśli zadanie Seedance 2.5 Flash się nie powiedzie? Nie. Nieudane zadania nie są rozliczane, a ich status pokazuje credits_amount: 0.

Share: