Samouczek API Seedance 2.5 Flash: zadania asynchroniczne, limity, błędy

AIHubMix8 min czytania
Samouczek API Seedance 2.5 Flash: zadania asynchroniczne, limity, błędy

Użyj doubao-seedance-2-5-flash z POST /ai/v1/videos, sprawdzaj status zadania, a następnie pobierz wynik. Aktualny schemat AIHubMix udostępnia generowanie w rozdzielczości 480p/720p, klipy o długości 4–30 sekund oraz maksymalnie 10 obrazów, 5 filmów i 5 nagrań audio jako materiałów referencyjnych. Starsze klienty korzystające z /v1/videos muszą zmienić zarówno punkt końcowy, jak i identyfikator modelu.

Ten przewodnik został zweryfikowany 16 listopada 2026 r. Zarówno powyższy krótki identyfikator, jak i doubao-seedance-2-5-flash-261115 zwróciły schemat modelu i odrzuciły żądanie 1080p błędem 400 schema_violation. Oddzielna próba wygenerowania klipu 480p o długości 4 sekund zakończyła się błędem 402 insufficient_quota; film nie został wygenerowany. Opisany niżej przepływ pracy jest zgodny z aktualnym schematem i dokumentacją, ale podczas tej weryfikacji nie sprawdzono pełnego procesu generowania, opóźnienia, pliku wyjściowego MOV ani edycji.

Wymagania wstępne i sprawdzanie schematu

Na stronie modelu Seedance 2.5 Flash model jest wymieniony pod krótkim identyfikatorem używanym w tym przewodniku. Przed wysłaniem zadania:

  1. Włącz asynchroniczne zadania multimedialne w konsoli AIHubMix. Udokumentowany błąd dla konta, na którym ta funkcja nie jest włączona, to 403 async_not_enabled.
  2. Upewnij się, że klucz API ma odpowiednie uprawnienia, a na koncie jest wystarczające saldo. Podczas bieżącej weryfikacji zwrócono 402 insufficient_quota z komunikatem Your account has insufficient quota. Add credits and try again.
  3. Ustaw w powłoce zmienną AIHUBMIX_API_KEY. Nie umieszczaj klucza w plikach źródłowych ani w kodzie przeglądarkowym.
  4. Pobierz aktualny schemat; żądanie sprawdzające nie wymaga uwierzytelniania.
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

Schemat z 16 listopada wymienia dla Flash wyłącznie /ai/v1/videos. Akceptuje wartości resolution 480p i 720p (domyślnie 720p), całkowitą wartość duration od 4 do 30 albo -1, aby model sam wybrał czas trwania. Jeśli chcesz przewidywalnie zaplanować budżet, podaj konkretną długość.

Utworzenie zadania, sprawdzanie statusu i pobieranie

API generowania wideo AIHubMix rozdziela tworzenie zadania, sprawdzanie jego statusu i pobieranie wyników. Sukces żądania HTTP podczas tworzenia oznacza, że zadanie zostało przyjęte; jego ukończenie potwierdza dopiero status: "completed". Zapytanie może zwrócić HTTP 200, mimo że samo zadanie ma status status: "failed".

Wyślij zadanie przekształcenia tekstu w wideo

Ten przykład tworzy 10-sekundowy klip produktowy w rozdzielczości 720p i formacie 16:9, z dźwiękiem. Korzysta wyłącznie z tekstu, więc nie wymaga obrazów referencyjnych hostowanych w innym miejscu.

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

Zapisz od razu zwrócone id zadania. Co 15 sekund wysyłaj zapytanie GET /ai/v1/videos/{id}, aż status zmieni się na completed, failed lub cancelled. Do aktywnego sprawdzania statusu używaj ścieżki szczegółów wideo: odświeża ona stan u dostawcy, a ujednolicona lista zadań nie zastępuje takiego sprawdzenia. Po ukończeniu zadania pobierz plik przez GET /ai/v1/videos/{id}/content, używając tego samego nagłówka Bearer.

Kompletny klient w Pythonie

Zainstaluj zależność poleceniem python3 -m pip install requests, zapisz poniższy kod w pliku seedance_flash.py, a następnie uruchom python3 seedance_flash.py w powłoce, w której ustawiono klucz API. Ten przykład implementuje udokumentowany przepływ pracy; błąd limitu środków opisany wyżej uniemożliwił pełne przetestowanie generowania.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

Limit 20 minut to limit czasu oczekiwania po stronie klienta, a nie anulowanie po stronie serwera ani gwarantowany czas generowania. Jeśli sprawdzanie statusu lub pobieranie zakończy się niepowodzeniem, zachowaj identyfikator zadania i ponów tę operację. Po przekroczeniu limitu czasu lub przy niepewnym stanie u dostawcy nie wysyłaj automatycznie kolejnego żądania generowania.

Według oficjalnych stawek BytePlus za wnioskowanie online Flash kosztuje $7.00 za milion tokenów bez wejściowego wideo lub $4.30 z wejściowym wideo w rozdzielczości 480p/720p. Dla przykładu opartego wyłącznie na tekście szacowany koszt wynosi 10 × 1280 × 720 × 24 / 1024 = 216,000 tokenów: $1.51 w Flash w porównaniu z $2.31 we flagowym modelu 2.5 przy 720p. Są to wyliczenia na podstawie stawek BytePlus, a nie zmierzona opłata AIHubMix.

Materiały referencyjne i webhooki

Aby pokierować generowaniem klipu za pomocą multimediów, dodaj wpisy input_references zawierające type (image_url, video_url lub audio_url) oraz url wskazujący dostępny plik multimedialny. Schemat dopuszcza maksymalnie 10 / 5 / 5 elementów tych typów. Aby kontrolować pierwszą i ostatnią klatkę, użyj zamiast tego frame_images; każdy wpis zawiera frame_type i zagnieżdżone image_url.url. Nie łącz niepustych tablic frame_images i input_references. Przepływy pracy z klatkami wymagają aspect_ratio: "adaptive", a ostatnia klatka wymaga podania pierwszej.

Dokumentacja zadań asynchronicznych opisuje wywołania zwrotne HTTPS skonfigurowane przez webhook_url. Aktualny schemat Flash zawiera to pole, ale pomija webhook_events_filter i ustawia additionalProperties: false, dlatego korzystając z tego schematu modelu, pomiń filtr. Zgodnie z dokumentacją domyślnie wysyłane są zdarzenia completed, failed i cancelled. Dostarczenie następuje co najmniej raz, z maksymalnie sześcioma próbami i przerwami wynoszącymi 1, 4, 16, 64 oraz 256 sekund; zapobiegaj duplikatom na podstawie event_id. Wywołania zwrotne na poziomie zadania nie mają osobnego klucza do podpisu, dlatego sprawdź końcowy stan, wysyłając zapytanie o zadanie. Dokumentacja opisuje subskrypcje na poziomie konta dla aplikacji wymagających weryfikacji podpisu.

Błędy: co zmierzono, a co opisuje dokumentacja

1080p: zaobserwowane odrzucenie przez schemat

Oba identyfikatory modeli AIHubMix zwróciły HTTP 400 dla żądania klipu o długości 4 sekund z resolution: "1080p". Zwrócone pola błędu to:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

Odpowiedź zawierała też identyfikator śledzenia żądania, który pominięto. To zaobserwowane odrzucenie przez bramę, a nie wywnioskowany błąd usługi nadrzędnej. Nie potwierdza ono ani poprawnego wygenerowania filmu, ani pomiaru szybkości.

Pozostałe poniższe ograniczenia wynikają z aktualnego schematu Flash; tych nieprawidłowych kombinacji nie wysyłano osobno podczas bieżącej weryfikacji.

Problem z danymi wejściowymi Wymaganie schematu Rozwiązanie
Wyjście 4K 480p lub 720p Zmniejsz rozdzielczość
Za dużo materiałów referencyjnych 10 obrazów / 5 filmów / 5 nagrań audio Zmniejsz liczbę elementów
Dwie tablice materiałów referencyjnych Jedna niepusta tablica Wybierz jeden przepływ pracy
Sama ostatnia klatka Wymagana również pierwsza klatka Podaj obie klatki
Stałe proporcje obrazu przy klatkach Adaptacyjne proporcje obrazu Użyj trybu adaptacyjnego

Materiały referencyjne z wizerunkiem prawdziwej osoby: używaj zweryfikowanych zasobów

AIHubMix dokumentuje błąd doubao_real_person_required, który występuje, gdy Doubao zwraca charakterystyczne dla siebie odrzucenie prywatności związane z obrazem prawdziwej osoby. Ten błąd nie wystąpił podczas tej weryfikacji. Udokumentowany komunikat brzmi:

To żądanie wykorzystuje obraz prawdziwej osoby. Ukończ weryfikację osoby i użyj aktywnego odwołania do zasobu. Zobacz https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Postępuj zgodnie z przewodnikiem po zasobach Doubao z wizerunkiem prawdziwej osoby: utwórz grupę przez /ai/v1/asset-groups, utwórz sesję weryfikacyjną przez /ai/v1/asset-groups/{id}/verification-sessions, poproś osobę przedstawioną na obrazie o ukończenie weryfikacji internetowej, zarejestruj zasób przez /ai/v1/asset-groups/{id}/assets i zaczekaj, aż uzyska status aktywny. W odwołaniu użyj asset://<ASSET_ID>. Surowy adres URL zdjęcia nie zastępuje procesu uzyskania zgody i rejestracji zasobu.

Limity, rozmiar żądania i pobieranie

Zmierzony błąd 402 insufficient_quota uniemożliwił przejście poprawnego żądania z dozwoloną rozdzielczością do etapu generowania. Doładuj środki, zanim spróbujesz ponownie; zmiana poprawnego promptu lub identyfikatora modelu nie rozwiąże tego problemu. 403 async_not_enabled to inny, udokumentowany błąd dotyczący wymagań wstępnych, który wymaga włączenia funkcji w konsoli.

AIHubMix dokumentuje limit rozmiaru treści żądania wynoszący 32 MiB oraz błąd 413 request_too_large. Korzystanie z publicznych adresów URL pozwala uniknąć zwiększania treści żądania przez kodowanie Base64, ale wskazane pliki multimedialne nadal muszą spełniać limity rozmiaru i formatów narzucone przez model.

Pobierz ukończony film niezwłocznie. Istniejący przewodnik integracji AIHubMix z Seedance 2.5 ostrzega, że adresy URL wyników są krótkotrwałe i działają mniej więcej 30 minut; w tej weryfikacji nie potwierdzono określonego czasu przechowywania plików w Flash. API wideo może zwrócić expires_at: null, co nie oznacza gwarancji przechowywania bez ograniczeń czasowych. Udokumentowane błędy pobierania obejmują 410 artifact_expired i 429 too_many_downloads. Jeśli pobieranie zakończy się tymczasowym błędem usługi, ponów pobieranie istniejącego zadania zamiast ponownie generować klip.

Pułapki migracji, które mogą wystąpić nawet przy poprawnym żądaniu

Przewodnik Volcengine po Seedance 2.5 wyraźnie wymienia Flash jako część tej rodziny i potwierdza obsługę formatu MOV, edycji oraz przedłużania klipów. Te możliwości dostawcy należy jednak odróżnić od funkcji zweryfikowanych za pośrednictwem bramy.

  • Obsługa MOV i pola edycji są dostępne, ale nie zostały tu przetestowane od początku do końca. Schemat Flash akceptuje extra.output_format: "mp4" lub "mov" oraz wartości auto, reference, edit i extend dla extra.omni_reference_task_type. Jeśli jawnie przekażesz pole typu zadania, schemat wymaga niepustego input_references. Tryb edit wymaga ponadto materiału referencyjnego wideo, adaptacyjnych proporcji obrazu i duration: -1; tryb extend wymaga materiału referencyjnego wideo i adaptacyjnych proporcji obrazu.
  • Jawnie podany typ zadania nie gwarantuje, że model go zaakceptuje. Ark dokumentuje asynchroniczny błąd InvalidParameter.TaskTypeConstraint, gdy wywnioskowany typ zadania jest niezgodny z parametrami, oraz InvalidParameter.TaskTypeMismatch, gdy wywnioskowany typ różni się od jawnie żądanego. Dokładnego mapowania w AIHubMix nie zmierzono; sprawdź zwrócone pole error zadania, zamiast zakładać, że wystąpi określony kod bramy.
  • Flash nie obsługuje promocji z trybu Draft. Dostawca ogranicza dwuetapowy przepływ pracy Draft 480p → wynik końcowy do flagowego modelu 2.5. Flash go nie obsługuje, a aktualne schematy AIHubMix dla obu modeli pomijają draft i draft_task.
  • Wejściowe wideo zmienia sposób naliczania opłat. Oficjalne rozliczenia uwzględniają czas trwania wejściowego i wyjściowego wideo oraz mogą stosować minimalny próg tokenów. Stawka $4.30/M nie gwarantuje, że zadanie z materiałem wideo będzie tańsze niż analogiczne zadanie oparte wyłącznie na tekście. Sprawdź rzeczywiste zużycie i rozliczenie konta, zamiast polegać wyłącznie na tym wzorze.
  • Niektóre opisy pozostają niejednoznaczne. Schemat bramki Flash udostępnia pola extra.priority, extra.safety_identifier i extra.tools, ale ich opisy nadal mówią „tylko seria 2.0”. Dokumentacja tworzenia zadań Ark wymienia jednak priority i tools także dla rodziny 2.5. Sama obecność pól w schemacie nie potwierdza ich działania w AIHubMix; przed użyciem danej funkcji w środowisku produkcyjnym sprawdź ją.

Lista kontrolna przed uruchomieniem

  • Włącz zadania asynchroniczne i sprawdź saldo konta.
  • Użyj krótkiego identyfikatora Flash z /ai/v1/videos i pobierz aktualny schemat.
  • Wybierz rozdzielczość 480p lub 720p oraz jawnie określ czas trwania w zakresie 4–30 sekund.
  • Ogranicz liczbę materiałów referencyjnych do 10 obrazów, 5 filmów i 5 klipów audio.
  • Oddziel referencje klatek i ustaw dla nich proporcje adaptacyjne.
  • Referencje przedstawiające wizerunek prawdziwych osób kieruj przez zweryfikowane, aktywne zasoby.
  • Zapisz identyfikator zadania, sprawdź jego końcowy status i szybko pobierz wynik.
  • Jeśli stan generowania jest niepewny, ponawiaj zapytania lub pobieranie dla istniejącego zadania.

Najczęściej zadawane pytania

Czy mogę użyć zgodnej z OpenAI ścieżki /v1/videos dla Flash?
Aktualny schemat Flash wymienia tylko /ai/v1/videos. W przykładach z tego poradnika używaj tej natywnej ścieżki asynchronicznej.

Dlaczego żądanie z obrazem klatki kończy się błędem przy aspect_ratio: "16:9"?
Schemat Flash wymaga ustawienia aspect_ratio: "adaptive", jeśli podano niepustą wartość frame_images. Klatka końcowa wymaga też klatki początkowej, a referencji klatek nie można łączyć z niepustą wartością input_references.

Jak naprawić błąd doubao_real_person_required?
Przejdź procedurę weryfikacji osoby i rejestracji zasobu, poczekaj, aż zasób stanie się aktywny, a następnie odwołaj się do niego za pomocą URI zasobu. Kod oznacza specyficzne dla Doubao odrzucenie ze względów prywatności; nie udało się go odtworzyć podczas tej weryfikacji.

Dlaczego krótki film referencyjny może kosztować więcej, niż wynika ze wzoru?
Zasady rozliczeń dostawcy mogą uwzględniać minimalny próg tokenów, gdy dane wejściowe zawierają film. Wzór podaje szacunkowy koszt; rzeczywiste zużycie i naliczoną kwotę sprawdź w historii rozliczeń konta.

Czy nieudane generowanie lub odrzucenie przez moderację kosztuje?
Oficjalne zasady rozliczeń BytePlus i Volcengine przewidują opłaty za udane generowanie, a nie naliczają ich za nieudane generowanie ani odrzucenie przez moderację treści. Dokumentacja błędów AIHubMix zaleca sprawdzanie historii rozliczeń pod kątem wcześniejszych opłat; w tym przypadku nie zmierzono opłat za udane ani nieudane generowanie.

Ile mam czasu na pobranie wyniku Flash?
Pobierz go od razu po zakończeniu generowania. W istniejącym poradniku Seedance 2.5 ostrzeżono, że adresy URL działają około 30 minut, ale dokładny czas przechowywania wyników Flash nie został zweryfikowany, a puste pole wygaśnięcia nie oznacza, że wynik jest dostępny na stałe.

Czy AIHubMix obsługuje format MOV oraz edycję i rozszerzanie?
Aktualny schemat Flash udostępnia odpowiednie pola w sekcji extra, a dostawca dokumentuje te funkcje. Ich działanie od początku do końca za pośrednictwem AIHubMix nie zostało zweryfikowane, ponieważ test tworzenia zakończył się komunikatem o niewystarczającym limicie.

Czytaj dalej: seria Seedance 2.5 Flash

Źródła

Dokumentację i schemat sprawdzono 16 listopada 2026 r.; odpowiedzi walidacyjne zarejestrowano o 08:26 UTC. Ceny to oficjalne szacunki BytePlus, a nie zmierzone opłaty bramki.

Jedna brama do wielu dostawców AI. Stworzona z myślą o produkcji.

Odwiedź AIHubMix