Tutorial API di Seedance 2.5 Flash: job asincroni, limiti, errori

AIHubMix8 min di lettura
Tutorial API di Seedance 2.5 Flash: job asincroni, limiti, errori

Usa doubao-seedance-2-5-flash con POST /ai/v1/videos, interroga l'attività e poi scaricane il risultato. Lo schema attuale di AIHubMix espone output a 480p/720p, clip da 4–30 secondi e fino a 10 riferimenti immagine, 5 video e 5 audio. I client meno recenti che usano /v1/videos devono cambiare sia l'endpoint sia l'ID del modello.

Questa guida è stata verificata il 16 novembre 2026. Sia l'ID breve indicato sopra sia doubao-seedance-2-5-flash-261115 hanno restituito uno schema del modello e rifiutato una richiesta a 1080p con 400 schema_violation. Un tentativo separato di creazione a 480p per 4 secondi ha restituito 402 insufficient_quota; non ha generato un video. Il flusso di lavoro seguente si basa sullo schema e sulla documentazione attuali, ma in questa verifica non sono stati verificati end-to-end la generazione riuscita, la latenza, l'output MOV e l'editing.

Prerequisiti e individuazione dello schema

La pagina del modello Seedance 2.5 Flash elenca il modello usando l'ID breve impiegato in tutta questa guida. Prima di inviare un'attività:

  1. Abilita le attività multimediali asincrone nella console AIHubMix. L'errore documentato per gli account senza questa funzionalità è 403 async_not_enabled.
  2. Assicurati che la chiave API abbia accesso e che l'account disponga di credito sufficiente. La verifica dal vivo ha restituito 402 insufficient_quota con il messaggio Your account has insufficient quota. Add credits and try again.
  3. Esporta AIHUBMIX_API_KEY nella shell. Non inserire la chiave nei file sorgente o nel codice del browser.
  4. Recupera lo schema attuale; la richiesta di individuazione non richiede autenticazione.
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'

Lo schema del 16 novembre elenca solo /ai/v1/videos per Flash. Accetta i valori di resolution 480p e 720p (valore predefinito 720p), un valore intero per duration da 4 a 30 oppure -1 per una durata selezionata dal modello. Specifica una durata esplicita se ti serve un budget prevedibile.

Crea, interroga e scarica

La API di generazione video di AIHubMix separa la creazione, le query sullo stato e i download. Una risposta HTTP positiva alla creazione indica che l'attività è stata accettata; solo status: "completed" ne conferma il completamento. Una query può restituire HTTP 200 mentre l'attività ha status: "failed".

Invia un'attività da testo a video

Questo esempio richiede una clip di prodotto di 10 secondi, a 720p e 16:9, con audio. Usa solo testo, quindi non dipende da immagini di riferimento ospitate altrove.

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

Salva subito l'id dell'attività restituito. Interroga GET /ai/v1/videos/{id} ogni 15 secondi fino a completed, failed o cancelled. Per le query periodiche, usa la route dei dettagli video: aggiorna lo stato del fornitore, mentre l'elenco unificato delle attività non sostituisce questo controllo. Una volta completata l'attività, scarica il contenuto tramite GET /ai/v1/videos/{id}/content, usando la stessa intestazione Bearer.

Un client Python completo

Installa la dipendenza con python3 -m pip install requests, salva il codice seguente come seedance_flash.py, quindi esegui python3 seedance_flash.py nella shell in cui è disponibile la chiave API. Questo esempio implementa il flusso documentato; l'errore di quota riportato sopra ha impedito di testare una generazione completa.

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

Il limite di 20 minuti è un limite di attesa lato client, non una cancellazione lato server né una garanzia sui tempi di generazione. Se l'interrogazione o il download non riescono, conserva l'ID dell'attività e riprova l'operazione. Non inviare automaticamente un'altra richiesta di generazione dopo un timeout o quando lo stato del fornitore è incerto.

Alle tariffe ufficiali di BytePlus per l'inferenza online, Flash costa $7.00 per milione di token senza input video o $4.30 con input video a 480p/720p. Per l'esempio di solo testo, la stima è 10 × 1280 × 720 × 24 / 1024 = 216,000 token: $1.51 con Flash contro $2.31 con flagship 2.5 a 720p. Sono stime calcolate in base alle tariffe BytePlus, non un addebito AIHubMix misurato.

Riferimenti e webhook

Per guidare una clip con contenuti multimediali, aggiungi voci a input_references che contengano un type (image_url, video_url o audio_url) e un url che punti ai tuoi contenuti multimediali accessibili. Lo schema limita queste tipologie a 10 / 5 / 5. Per controllare il primo e l'ultimo fotogramma, usa invece frame_images; ogni voce contiene un frame_type e un image_url.url annidato. Non combinare frame_images e input_references se entrambi non sono vuoti. I flussi di lavoro basati sui fotogrammi richiedono aspect_ratio: "adaptive" e, per specificare l'ultimo fotogramma, è necessario specificare anche il primo.

La documentazione sulle attività asincrone descrive i callback HTTPS tramite webhook_url. Lo schema attuale di Flash include questo campo, ma omette webhook_events_filter e imposta additionalProperties: false; quindi, per seguire lo schema di questo modello, ometti il filtro. Il comportamento predefinito documentato invia completed, failed e cancelled. La consegna avviene almeno una volta, con un massimo di sei tentativi e intervalli di ripetizione di 1, 4, 16, 64 e 256 secondi; deduplica usando event_id. I callback a livello di attività non dispongono di un segreto di firma separato, quindi interroga l'attività per confermarne lo stato finale. La documentazione descrive le sottoscrizioni a livello di account per le applicazioni che richiedono la verifica della firma.

Errori: cosa è stato misurato e cosa descrive la documentazione

1080p: rifiuto dello schema misurato

Entrambi gli ID del modello AIHubMix hanno restituito HTTP 400 per una richiesta di 4 secondi con resolution: "1080p". I campi di errore restituiti erano:

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

La risposta conteneva anche un ID di tracciamento della richiesta, omesso qui. Si tratta di un rifiuto del gateway osservato, non di un errore upstream dedotto. Non dimostra né l'avvenuta generazione né una misurazione della velocità.

Gli altri vincoli riportati sotto provengono dallo schema attuale di Flash; queste combinazioni non valide non sono state inviate separatamente durante la verifica dal vivo.

Problema di input Requisito dello schema Soluzione
Output 4K 480p o 720p Riduci la risoluzione
Troppi riferimenti 10 immagini / 5 video / 5 audio Riduci il numero
Due array di riferimenti Un solo array non vuoto Scegli un flusso di lavoro
Solo ultimo fotogramma È richiesto anche il primo fotogramma Fornisci entrambi i fotogrammi
Rapporto fisso con i fotogrammi Rapporto adattivo Usa quello adattivo

Riferimenti a persone reali: usa risorse verificate

AIHubMix documenta doubao_real_person_required quando Doubao restituisce il suo specifico rifiuto per motivi di privacy relativo a un'immagine di una persona reale. Questo errore non si è verificato durante questa verifica. Il messaggio documentato è:

Questa richiesta usa un'immagine di una persona reale. Completa la verifica delle persone reali e usa un riferimento a una risorsa attiva. Consulta https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Segui la Guida alle risorse di persone reali di Doubao: crea un gruppo su /ai/v1/asset-groups, crea una sessione di verifica su /ai/v1/asset-groups/{id}/verification-sessions, chiedi alla persona raffigurata di completare la verifica web, registra la risorsa su /ai/v1/asset-groups/{id}/assets e attendi che diventi attiva. Usa asset://<ASSET_ID> nel riferimento per la generazione. Un URL diretto a una foto non sostituisce il flusso di consenso e gestione delle risorse.

Quota, dimensione delle richieste e download

L'errore misurato 402 insufficient_quota ha impedito alla richiesta con risoluzione valida di arrivare alla fase di generazione. Aggiungi credito prima di riprovare; modificare un prompt corretto o l'ID del modello non risolve questa risposta. 403 async_not_enabled è un errore distinto, documentato come prerequisito e risolvibile tramite attivazione nella console.

AIHubMix documenta un limite di 32 MiB per il corpo della richiesta e l'errore 413 request_too_large. Gli URL pubblici evitano che la codifica Base64 aumenti le dimensioni del corpo della richiesta, ma i contenuti multimediali a cui fanno riferimento devono comunque rispettare i limiti di dimensione e formato del modello.

Salva tempestivamente i video completati. La guida all'integrazione Seedance 2.5 esistente di AIHubMix avverte che gli URL di output hanno una durata breve, circa 30 minuti; qui non è stato verificato un periodo di conservazione fisso per Flash. L'API video può restituire expires_at: null, che non garantisce una conservazione indefinita. Gli errori di download documentati includono 410 artifact_expired e 429 too_many_downloads. Se il download restituisce un errore temporaneo del servizio, riprova a scaricare il video usando l'attività esistente anziché generare di nuovo la clip.

Insidie di migrazione che possono verificarsi anche con una richiesta valida

La guida Seedance 2.5 di Volcengine include esplicitamente Flash nella famiglia e conferma l'output MOV, l'editing e l'estensione, ma queste funzionalità del fornitore vanno distinte da ciò che è stato verificato attraverso il gateway.

  • I campi per MOV e editing sono esposti, ma non sono stati testati end-to-end qui. Lo schema di Flash accetta extra.output_format: "mp4" o "mov" e i valori di extra.omni_reference_task_type auto, reference, edit e extend. Se invii esplicitamente il campo del tipo di attività, lo schema richiede un input_references non vuoto. edit richiede inoltre un riferimento video, un rapporto adattivo e duration: -1; extend richiede un riferimento video e un rapporto adattivo.
  • Il tipo di attività esplicito non garantisce che il modello sia d'accordo. Ark documenta l'errore asincrono InvalidParameter.TaskTypeConstraint quando il tipo di attività dedotto è in conflitto con i parametri e InvalidParameter.TaskTypeMismatch quando il tipo dedotto differisce da quello richiesto esplicitamente. La corrispondenza esatta con AIHubMix non è stata misurata; controlla il campo error dell'attività restituita invece di presumere un codice del gateway.
  • Flash non supporta la promozione da Draft. Il fornitore limita il flusso in due fasi da Draft a 480p a finale a flagship 2.5. Flash non lo supporta e gli schemi AIHubMix attuali per entrambi i modelli omettono draft e draft_task.
  • L'input video modifica la fatturazione. La fatturazione ufficiale calcola la durata del video di input e di output e può applicare una soglia minima di token. La tariffa di $4.30/M non garantisce che un'attività guidata da video costi meno di un'attività altrimenti identica basata solo sul testo. Controlla l'utilizzo effettivo e la fatturazione dell'account, invece di basarti solo sulla formula.
  • Alcune descrizioni restano ambigue. Lo schema del gateway di Flash espone extra.priority, extra.safety_identifier e extra.tools, ma le relative descrizioni indicano ancora «solo serie 2.0». Anche la documentazione di riferimento di Ark per la creazione delle attività elenca priority e tools per la famiglia 2.5. La sola presenza nello schema non conferma che queste funzionalità siano operative su AIHubMix: verificate la singola funzione prima di farvi affidamento in produzione.

Lista di controllo prima dell'avvio

  • Abilitate le attività asincrone e verificate il credito dell'account.
  • Usate l'ID breve di Flash con /ai/v1/videos e recuperate lo schema aggiornato.
  • Scegliete 480p o 720p e indicate una durata esplicita compresa tra 4 e 30 secondi.
  • Mantenete i riferimenti entro 10 immagini, 5 video e 5 clip audio.
  • Tenete separati i riferimenti ai fotogrammi e usate il rapporto d'aspetto adattivo per questi ultimi.
  • Fate passare i riferimenti che raffigurano persone reali tramite asset attivi e verificati.
  • Memorizzate l'ID dell'attività, controllate lo stato terminale e scaricate il risultato tempestivamente.
  • Se lo stato della generazione è incerto, ripetete le richieste di stato o di download per un'attività già esistente.

Domande frequenti

Posso usare il percorso compatibile con OpenAI /v1/videos per Flash?
Lo schema attuale di Flash elenca solo /ai/v1/videos. Per gli esempi di questa guida, usate quel percorso asincrono nativo.

Perché una richiesta con immagini dei fotogrammi non riesce con aspect_ratio: "16:9"?
Lo schema di Flash richiede aspect_ratio: "adaptive" quando si specifica un valore non vuoto per frame_images. È inoltre necessario indicare il primo fotogramma per poter specificare l'ultimo, e i riferimenti ai fotogrammi non possono essere combinati con un valore non vuoto di input_references.

Come posso risolvere doubao_real_person_required?
Seguite la procedura di verifica personale e registrazione degli asset, attendete che l'asset risulti attivo e includetelo tramite un URI dell'asset. Il codice indica il rifiuto specifico di Doubao per motivi di privacy; non è stato riprodotto durante questa verifica.

Perché un breve video di riferimento può costare più di quanto previsto dalla formula?
Le regole di fatturazione del fornitore possono applicare una soglia minima di token quando l'input include un video. La formula fornisce una stima: controllate il consumo effettivo e i dati di fatturazione dell'account per verificare l'importo addebitato.

Le generazioni non riuscite o rifiutate dalla moderazione comportano un costo?
Le regole di fatturazione ufficiali di BytePlus e Volcengine prevedono l'addebito delle generazioni riuscite e specificano che le generazioni non riuscite e i rifiuti della moderazione dei contenuti non vengono fatturati. La documentazione sugli errori di AIHubMix consiglia di controllare i dati di fatturazione per gli addebiti precedenti; in questa verifica non è stato misurato alcun addebito per generazioni riuscite o non riuscite.

Quanto tempo ho per scaricare un risultato di Flash?
Scaricatelo subito dopo il completamento. La guida esistente su Seedance 2.5 avverte che gli URL durano circa 30 minuti, ma la durata esatta per Flash non è stata verificata e un campo di scadenza con valore null non significa che il risultato sia permanente.

AIHubMix supporta l'output MOV e le funzioni di modifica/estensione?
Lo schema attuale di Flash espone i campi corrispondenti sotto extra e il fornitore documenta queste funzionalità. Il loro comportamento end-to-end tramite AIHubMix non è stato verificato, perché il test di creazione si è fermato davanti a una risposta di quota insufficiente.

Continua a leggere: la serie Seedance 2.5 Flash

Fonti

Documentazione e schema verificati il 16 novembre 2026; risposte di convalida registrate alle 08:26 UTC. I prezzi sono stime ufficiali di BytePlus, non addebiti misurati tramite il gateway.

Un unico gateway per più provider di IA. Pensato per la produzione.

Visita AIHubMix