
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
| Element | Wartość |
|---|---|
| Endpoint wysyłania | POST https://api.poyo.ai/api/generate/submit |
| Endpoint statusu | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Nagłówek uwierzytelniania | Authorization: Bearer $POYO_API_KEY |
| ID modelu | seedance-2.5-flash (slug strony seedance-2-5-flash nie jest ID modelu) |
| Pola wymagane | prompt, duration |
| Czas trwania | Pełne sekundy, 4–30 |
| Rozdzielczość | 480p lub 720p, domyślnie 720p |
| Proporcje obrazu | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, domyślnie auto |
| Audio | generate_audio, domyślnie true |
| Dostarczenie wyniku | Zadanie 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-Signaturejakobase64(HMAC-SHA256(task_id + "." + timestamp, key)), gdzietimestamppochodzi zX-Webhook-Timestamp, a klucz zGET /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.
| Tryb | Wybierany, gdy | Proporcje obrazu |
|---|---|---|
| Reference-to-video | Którekolwiek z reference_image_urls, reference_video_urls, reference_audio_urls jest niepuste | Dowolna obsługiwana wartość |
| Image-to-video (pierwsza/ostatnia klatka) | image_urls jest niepuste | auto lub pomiń; wyjście dopasowuje się do pierwszej klatki |
| Text-to-video | Brak mediów | Dowolna 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.
| Pole | Reguła |
|---|---|
prompt | Wymagane, niepusty ciąg znaków |
duration | Wymagana liczba całkowita, 4–30 |
resolution | Tylko 480p lub 720p; 1080p wymaga seedance-2.5 |
aspect_ratio | Jedna z siedmiu wartości; przy image_urls użyj auto lub pomiń |
image_urls | 1–2 URL (pierwsza, potem ostatnia klatka); JPEG, PNG lub WebP, do 30 MB każdy; nie łączy się z polami referencji |
reference_image_urls | Do 10; JPEG, PNG lub WebP, do 30 MB każdy |
reference_video_urls | Do 5; MP4 lub MOV, 2–30 s i do 200 MB każdy; łączna długość najwyżej 30 s |
reference_audio_urls | Do 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ów | Publiczne 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:
| Kod | Typ | Co zrobić |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Popraw żądanie lub media; nie ponawiaj bez zmian |
401 | authentication_error | Sprawdź nagłówek Bearer i czy klucz nadal istnieje |
402 | insufficient_credits_error | Doładuj konto, a potem wyślij ponownie |
429 | Limit częstotliwości | Odczekaj (1 s, 2 s, 4 s...) przed kolejnym odpytaniem lub wysłaniem |
500, 502, 503 | Serwer lub dostawca upstream | Ponów zapytanie o status z backoffem; sprawdź status przed ponownym wysłaniem |
Zadanie failed | Ustawione error_message | Zaloguj 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żej | Rozliczane sekundy | Kredyty | USD |
|---|---|---|---|
| Test cURL, 5 s 480p | 5 | 92.5 | $0.4625 |
| Text-to-video, 30 s 720p | 30 | 1,230 | $6.15 |
| Pierwsza/ostatnia klatka, 5 s 720p | 5 | 205 | $1.025 |
| Obrazy referencyjne + audio, 6 s 480p | 6 | 111 | $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.