Seedance 2.5 Flash API-handleiding: asynchrone taken, limieten en fouten

AIHubMix8 min leestijd
Seedance 2.5 Flash API-handleiding: asynchrone taken, limieten en fouten

Gebruik doubao-seedance-2-5-flash met POST /ai/v1/videos, controleer de taakstatus en download vervolgens het resultaat. Het huidige AIHubMix-schema biedt uitvoer in 480p/720p, clips van 4–30 seconden en maximaal 10 afbeeldings-, 5 video- en 5 audioverwijzingen. Oudere clients die /v1/videos gebruiken, moeten zowel het eindpunt als de model-ID wijzigen.

Deze handleiding is gecontroleerd op 16 november 2026. Zowel de korte ID hierboven als doubao-seedance-2-5-flash-261115 leverden een modelschema op en wezen een aanvraag voor 1080p af met 400 schema_violation. Een afzonderlijke aanmaakpoging voor een clip van 4 seconden in 480p leverde 402 insufficient_quota op; er is geen video gegenereerd. De onderstaande workflow volgt het huidige schema en de documentatie, maar succesvolle generatie, latentie, MOV-uitvoer en bewerking zijn bij deze controle niet end-to-end geverifieerd.

Vereisten en schemadetectie

De Seedance 2.5 Flash-modelpagina vermeldt het model onder de korte ID die in deze handleiding wordt gebruikt. Voordat je een taak indient:

  1. Schakel asynchrone mediataken in via de AIHubMix-console. De gedocumenteerde fout voor een account zonder deze functie is 403 async_not_enabled.
  2. Zorg dat de API-sleutel toegang heeft en dat het account voldoende saldo heeft. De livecontrole leverde 402 insufficient_quota op met het bericht Your account has insufficient quota. Add credits and try again.
  3. Exporteer AIHUBMIX_API_KEY in je shell. Bewaar de sleutel niet in bronbestanden of browsercode.
  4. Haal het actuele schema op; voor het detectieverzoek is geen authenticatie nodig.
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'

Het schema van 16 november vermeldt voor Flash alleen /ai/v1/videos. Het accepteert resolution-waarden 480p en 720p (standaard 720p), een geheel getal voor duration van 4 tot en met 30, of -1 voor een door het model gekozen duur. Gebruik een expliciete duur als je een voorspelbaar budget nodig hebt.

Aanmaken, status controleren en downloaden

De AIHubMix Video Generation API scheidt het aanmaken, status opvragen en downloaden van elkaar. Een geslaagd HTTP-antwoord bij het aanmaken betekent dat een taak is geaccepteerd; alleen status: "completed" bevestigt dat de taak is voltooid. Een statusaanvraag kan HTTP 200 retourneren terwijl de taak zelf status: "failed" heeft.

Dien een tekst-naar-video-taak in

Dit voorbeeld vraagt om een productclip van 10 seconden in 720p, beeldverhouding 16:9 en met audio. Het gebruikt alleen tekst en is dus niet afhankelijk van elders gehoste referentieafbeeldingen.

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
  }'

Sla de geretourneerde taak-id meteen op. Poll GET /ai/v1/videos/{id} elke 15 seconden totdat de status completed, failed of cancelled is. Gebruik tijdens het pollen de route voor videodetails: die ververst de aanbiederstatus, terwijl de uniforme takenlijst geen vervanging is voor die controle. Download na voltooiing via GET /ai/v1/videos/{id}/content met dezelfde Bearer-header.

Een complete Python-client

Installeer de afhankelijkheid met python3 -m pip install requests, sla het volgende op als seedance_flash.py en voer vervolgens python3 seedance_flash.py uit in de shell waarin je API-sleutel beschikbaar is. Dit voorbeeld implementeert de gedocumenteerde workflow; door de bovenstaande quotafout kon de generatie niet volledig worden getest.

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")

De deadline van 20 minuten is een wachttijdlimiet aan de clientzijde, geen annulering door de server en ook geen garantie voor de generatieduur. Als het pollen of downloaden mislukt, bewaar dan de taak-ID en probeer die bewerking opnieuw. Dien na een time-out of bij een onzekere status bij de aanbieder niet automatisch opnieuw een generatieverzoek in.

Volgens de officiële tarieven voor online inferentie van BytePlus kost Flash $7.00 per miljoen tokens zonder video-invoer of $4.30 met video-invoer in 480p/720p. Voor het tekstuele voorbeeld is de schatting 10 × 1280 × 720 × 24 / 1024 = 216,000 tokens: $1.51 met Flash tegenover $2.31 met flagship 2.5 in 720p. Dit zijn berekende schattingen op basis van BytePlus, geen gemeten AIHubMix-factuur.

Referenties en webhooks

Om een clip met media te sturen, voeg je input_references-items toe met een type (image_url, video_url of audio_url) en een url die verwijst naar media waartoe toegang mogelijk is. Het schema beperkt deze typen tot 10 / 5 / 5. Gebruik voor controle over het eerste en laatste frame in plaats daarvan frame_images; elk item bevat een frame_type en een geneste image_url.url. Gebruik frame_images en input_references niet tegelijk met niet-lege inhoud. Voor workflows met frames is aspect_ratio: "adaptive" vereist, en voor een laatste frame is ook een eerste frame nodig.

De documentatie over asynchrone taken beschrijft HTTPS-callbacks via webhook_url. Het huidige Flash-schema bevat dit veld, maar laat webhook_events_filter weg en stelt additionalProperties: false in. Laat het filter dus weg als je dit modelschema volgt. Volgens de documentatie worden standaard completed, failed en cancelled verzonden. De bezorging gebeurt ten minste één keer, met maximaal zes pogingen en tussenpozen van 1, 4, 16, 64 en 256 seconden; dedupliceer op basis van event_id. Taakcallbacks hebben geen afzonderlijk ondertekeningsgeheim, dus vraag de taakstatus op om de eindstatus te bevestigen. De documentatie beschrijft abonnementen op accountniveau voor toepassingen die handtekeningverificatie nodig hebben.

Fouten: wat is gemeten en wat de documentatie beschrijft

1080p: een gemeten afwijzing door het schema

Beide AIHubMix-model-ID's retourneerden HTTP 400 voor een aanvraag van 4 seconden met resolution: "1080p". De geretourneerde foutvelden waren:

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

Het antwoord bevatte ook een trace-ID voor het verzoek, die hier is weggelaten. Dit is een waargenomen afwijzing door de gateway, geen afgeleide upstream-fout. Dit bewijst noch dat generatie lukt, noch iets over de snelheid.

De overige onderstaande beperkingen komen uit het huidige Flash-schema; deze ongeldige combinaties zijn niet afzonderlijk ingediend tijdens de livecontrole.

Invoerprobleem Schema-eis Oplossing
4K-uitvoer 480p of 720p Verlaag de resolutie
Te veel referenties 10 afbeeldingen / 5 video's / 5 audio Verminder het aantal
Twee referentiearrays Eén niet-lege array Kies een workflow
Alleen het laatste frame Ook het eerste frame is vereist Geef beide frames op
Vaste beeldverhouding met frames Adaptieve beeldverhouding Gebruik adaptive

Referenties met echte personen: gebruik geverifieerde assets

AIHubMix documenteert doubao_real_person_required wanneer Doubao een specifieke privacyafwijzing retourneert voor een afbeelding van een echt persoon. Deze fout trad bij deze controle niet op. Het gedocumenteerde bericht luidt:

Dit verzoek gebruikt een afbeelding van een echt persoon. Rond de verificatie van echte personen af en gebruik een actieve assetreferentie. Zie https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Volg de Handleiding voor assets van echte personen van Doubao: maak een groep aan via /ai/v1/asset-groups, maak een verificatiesessie aan via /ai/v1/asset-groups/{id}/verification-sessions, laat de afgebeelde persoon de webverificatie voltooien, registreer de asset via /ai/v1/asset-groups/{id}/assets en wacht totdat deze actief is. Gebruik asset://<ASSET_ID> in de generatiereferentie. Een URL naar een losse foto vervangt de toestemmings- en assetworkflow niet.

Quota, verzoekgrootte en downloads

De gemeten 402 insufficient_quota zorgde ervoor dat de aanvraag met een geldige resolutie niet tot generatie kwam. Waardeer je saldo op voordat je het opnieuw probeert; een correcte prompt of model-ID wijzigen lost dit antwoord niet op. 403 async_not_enabled is een andere, gedocumenteerde fout voor een vereiste die nog niet is vervuld en waarvoor activering in de console nodig is.

AIHubMix documenteert een limiet van 32 MiB voor de aanvraagbody en 413 request_too_large. Met openbare URL's voorkom je dat Base64 de aanvraagbody vergroot, maar de media waarnaar wordt verwezen moet nog steeds voldoen aan de eigen limieten van het model voor bestandsgrootte en formaat.

Sla een voltooide video meteen op. De bestaande Seedance 2.5-integratiehandleiding van AIHubMix waarschuwt dat uitvoer-URL's maar kort geldig zijn, ongeveer 30 minuten; een vaste bewaartermijn voor Flash is hier niet geverifieerd. De video-API kan expires_at: null retourneren, wat geen onbeperkte opslag garandeert. De gedocumenteerde downloadfouten zijn onder meer 410 artifact_expired en 429 too_many_downloads. Als er bij het downloaden tijdelijk een servicefout optreedt, probeer dan de download opnieuw voor de bestaande taak in plaats van de clip opnieuw te genereren.

Migratievalkuilen die ook bij een geldige aanvraag kunnen optreden

De Seedance 2.5-handleiding van Volcengine vermeldt Flash expliciet als onderdeel van de modelfamilie en bevestigt MOV-uitvoer, bewerking en verlenging, maar deze mogelijkheden van de aanbieder moeten worden onderscheiden van wat via de gateway is geverifieerd.

  • MOV- en bewerkingsvelden zijn beschikbaar, maar hier niet end-to-end getest. Het Flash-schema accepteert extra.output_format: "mp4" of "mov" en voor extra.omni_reference_task_type de waarden auto, reference, edit en extend. Als je het taaktypeveld expliciet verstuurt, vereist het schema niet-lege input_references. edit vereist bovendien een videoreferentie, een adaptieve beeldverhouding en duration: -1; extend vereist een videoreferentie en een adaptieve beeldverhouding.
  • Een expliciet taaktype garandeert niet dat het model ermee instemt. Ark documenteert asynchrone InvalidParameter.TaskTypeConstraint wanneer het afgeleide taaktype en de parameters met elkaar in strijd zijn, en InvalidParameter.TaskTypeMismatch wanneer het afgeleide type afwijkt van het expliciet aangevraagde type. De exacte AIHubMix-mapping is niet gemeten; controleer de geretourneerde taak-error in plaats van één gatewaycode te veronderstellen.
  • Flash ondersteunt geen promotie vanuit Draft. De aanbieder beperkt de workflow in twee fasen van Draft in 480p naar een eindresultaat tot flagship 2.5. Flash ondersteunt deze workflow niet en de huidige AIHubMix-schema's voor beide modellen laten draft en draft_task weg.
  • Video-invoer verandert de facturering. De officiële facturering is gebaseerd op de duur van de video-invoer en -uitvoer en kan een minimaal aantal tokens opleggen. Het tarief van $4.30/M garandeert niet dat een taak met videoreferentie minder kost dan een verder identieke taak die alleen tekst gebruikt. Controleer het werkelijke gebruik en de accountfacturering; vertrouw niet alleen op de formule.
  • Sommige beschrijvingen blijven dubbelzinnig. Het gatewayschema van Flash stelt extra.priority, extra.safety_identifier en extra.tools beschikbaar, maar in de beschrijvingen staat nog steeds ‘alleen voor de 2.0-serie’. In de referentie voor het aanmaken van taken op Ark staan priority en tools ook vermeld voor de 2.5-familie. Dat iets in het schema beschikbaar is, bevestigt op zichzelf niet dat het effect heeft op AIHubMix; test de specifieke functie voordat je erop vertrouwt in productie.

Checklist vóór de start

  • Schakel asynchrone taken in en controleer het accountsaldo.
  • Gebruik de korte Flash-ID met /ai/v1/videos en haal het actuele schema op.
  • Kies 480p of 720p en geef expliciet een duur van 4–30 seconden op.
  • Beperk referenties tot 10 afbeeldingen, 5 video's en 5 audiofragmenten.
  • Houd framereferenties gescheiden en gebruik daarvoor de adaptieve beeldverhouding.
  • Gebruik voor referenties met de gelijkenis van echte personen geverifieerde, actieve assets.
  • Sla de taak-ID op, controleer de eindstatus van de taak en download het resultaat tijdig.
  • Probeer bij onzekerheid over de generatiestatus de bestaande taak opnieuw op te vragen of te downloaden.

Veelgestelde vragen

Kan ik voor Flash het OpenAI-compatibele pad /v1/videos gebruiken?
In het actuele Flash-schema staat alleen /ai/v1/videos. Gebruik voor de voorbeelden in deze handleiding dat native asynchrone pad.

Waarom mislukt een aanvraag met frameafbeeldingen en aspect_ratio: "16:9"?
Het schema van Flash vereist aspect_ratio: "adaptive" wanneer er niet-lege frame_images worden meegegeven. Een laatste frame vereist ook een eerste frame, en framereferenties kunnen niet worden gecombineerd met niet-lege input_references.

Hoe los ik doubao_real_person_required op?
Volg de procedure voor persoonlijke verificatie en assetregistratie, wacht tot de asset actief is en verwijs ernaar met een asset-URI. De code duidt op Doubao's specifieke afwijzing om privacyredenen; die is bij deze controle niet opnieuw opgetreden.

Waarom kan een korte referentievideo meer kosten dan de formule voorspelt?
De factureringsregels van de leverancier kunnen een minimumaantal tokens toepassen wanneer de invoer video bevat. De formule is een schatting; controleer het werkelijke verbruik en de factureringsgegevens van het account om het in rekening gebrachte bedrag te zien.

Zijn mislukte generaties of afwijzingen door moderatie betalend?
Volgens de officiële factureringsregels van BytePlus en Volcengine worden succesvolle generaties in rekening gebracht, maar mislukte generaties en afwijzingen door contentmoderatie niet. In de foutdocumentatie van AIHubMix wordt aangeraden de factureringsgegevens te controleren op historische kosten; hier is geen factuur voor een geslaagde of mislukte generatie gemeten.

Hoe lang heb ik de tijd om een Flash-resultaat te downloaden?
Download het meteen nadat het is voltooid. In de bestaande Seedance 2.5-handleiding wordt gewaarschuwd dat URL's ongeveer 30 minuten geldig zijn, maar de exacte bewaartermijn van Flash is niet geverifieerd. Een vervaldatum met de waarde null betekent niet dat het resultaat permanent beschikbaar is.

Worden MOV-uitvoer en bewerken/verlengen ondersteund via AIHubMix?
In het actuele Flash-schema zijn de bijbehorende velden beschikbaar onder extra en de leverancier documenteert deze mogelijkheden. Het volledige gedrag via AIHubMix is niet geverifieerd, omdat de aanmaaktest strandde op een melding dat het quotum ontoereikend was.

Lees verder: de Seedance 2.5 Flash-serie

Bronnen

Documentatie en schema gecontroleerd op 16 november 2026; validatiereacties vastgelegd om 08:26 UTC. De prijzen zijn officiële schattingen van BytePlus, geen gemeten kosten via de gateway.

Eén gateway naar meerdere AI-aanbieders. Gebouwd voor productie.

Bezoek AIHubMix