Vai al contenuto principale
Seedance 2.0 genera video a partire da asset di riferimento affidabili — un volto, un abito, un prodotto, una voce. Per mantenere la generazione coerente e conforme, questi riferimenti risiedono in una libreria asset privata di cui il modello si fida al momento dell’inferenza. OrcaRouter espone questa libreria sotto /v1/asset. Questa pagina spiega come funziona la libreria e cosa serve. Per gli endpoint esatti, i parametri e una console di prova, vedi API Reference → Seedance Assets.

​
Come è strutturata la libreria

  • Gruppo di asset — un contenitore. Per un gruppo con persone reali, un gruppo corrisponde a una sola persona reale; per un gruppo virtuale è un raggruppamento logico (ad es. un personaggio).
  • Asset — un singolo file (immagine, video o audio) all’interno di un gruppo. Solo gli asset che raggiungono lo stato Active possono essere referenziati nella generazione video.
In una richiesta video referenzi un asset pronto come asset://<asset_id>.

​
Due tipi di gruppo

Le operazioni di caricamento e gestione sono identiche per entrambi; differiscono solo in come viene creato il gruppo.
Virtuale (AIGC)Persona reale (LivenessFace)
Da usare perPersonaggi di fantasia / IA, oggetti, sceneLa somiglianza di una persona reale
Creato tramiteUna chiamata di creazione direttaUna verifica del volto una tantum eseguita da quella persona
PerchéNessuna identità da proteggereDiritti d’immagine — il consenso viene raccolto alla fonte
Entrambe le librerie richiedono i Advanced Creation Rights; la quota di capacità è condivisa tra loro. La libreria con persone reali è disponibile per gli account invitati.

​
Requisiti dei file asset

Gli asset vengono forniti come URL accessibile pubblicamente (nessun caricamento di file, nessun base64). Limiti:
TipoFormatiVincoli
Immaginejpeg, png, webp, bmp, tiff, gif, heic/heifrapporto d’aspetto (L/A) 0.4–2.5 · 300–6000 px per lato · < 30 MB
Videomp4, mov480p/720p/1080p · 2–15 s · rapporto 0.4–2.5 · 300–6000 px · pixel totali 409,600–2,086,876 · 24–60 fps · ≤ 50 MB
Audiowav, mp32–15 s · ≤ 15 MB
Contenuti ritratto, buone pratiche (per la coerenza del volto):
  • Riferimento a figura intera: scatto verticale, frontale, a figura intera della persona.
  • Primo piano del viso: verticale, espressione neutra, inquadratura sopra le spalle, con il volto che occupa circa due terzi dell’inquadratura.
Caricare più riferimenti di buona qualità della stessa persona in un unico gruppo migliora la fedeltà con cui il video generato riproduce il suo volto e l’abbigliamento.

​
Ciclo di vita dell’asset (il caricamento è asincrono)

Il caricamento di un asset restituisce immediatamente un asset_id; il file viene poi preelaborato in background. Esegui il polling dell’asset finché il suo Status non si stabilizza:
  • Processing — ancora in preelaborazione; continua il polling.
  • Active — pronto; usalo nella generazione video.
  • Failed — la preelaborazione lo ha rifiutato; ispeziona Error (ad es. formato/dimensione, un blocco da moderazione dei contenuti o — per i gruppi con persone reali — FaceMismatch).
La SLA sui tempi di caricamento non è garantita; gli asset video richiedono più tempo delle immagini. L’URL di download firmato restituito per un asset è temporaneo (~12 ore).

​
Flusso di verifica con persona reale

Un gruppo con persona reale viene creato dalla persona che si verifica una sola volta. Il tuo backend non gestisce mai i dati del suo volto — si limita a orchestrare il flusso:
1

Avvia una sessione

Il tuo backend chiede a OrcaRouter di avviare una sessione di verifica. Ricevi in risposta un link H5 (una pagina di controllo del volto in hosting) e un session_id.
2

La persona si verifica

Consegni il link H5 all’utente finale. Lo apre sul proprio dispositivo — nessun login a OrcaRouter richiesto — e completa il controllo del volto. Autorizza una volta; in seguito, nuovi look per la stessa persona possono essere aggiunti allo stesso gruppo senza riverificare.
3

Il gruppo viene creato

In caso di successo, la pagina di verifica reindirizza il browser dell’utente finale a una callback di OrcaRouter (gestita automaticamente) e il nuovo gruppo viene registrato per te. Se hai passato un return_url, l’utente torna sulla tua pagina.
4

Esegui il polling del risultato

Il tuo backend esegue il polling della sessione finché status non è success (con il nuovo group_id) o failed. Poi carichi gli asset e generi il video esattamente come per un gruppo virtuale.
Coerenza del volto. Quando carichi un’immagine in un gruppo con persona reale, viene confrontata con il riferimento verificato. Una persona diversa (o più volti in un’unica immagine) viene rifiutata — l’asset si risolve in Failed / FaceMismatch. Il nome e la descrizione di un gruppo possono essere impostati dopo la creazione tramite l’operazione di aggiornamento del gruppo.

​
Quota

Il tuo account ha un numero massimo di asset (predefinito 100, su tutti i gruppi). I caricamenti oltre il limite vengono rifiutati con 403.

​
Referenziare un asset nella generazione video

Una volta che un asset è Active, referenzialo con asset://<asset_id> nel metadata.content[] della richiesta video Seedance e indirizzalo nel prompt per tipo + posizione ([Image 1], [Video 1], [Audio 1]) — mai tramite l’asset id grezzo: 
{
  "model": "byteplus/dreamina-seedance-2-0-260128",
  "prompt": "The girl in [Image 1] arranges items on the counter.",
  "metadata": {
    "content": [
      { "type": "image_url", "role": "reference_image",
        "image_url": { "url": "asset://asset-20260318071009-xy98z" } }
    ]
  }
}

​
Prossimi passi

  • API Reference → Seedance Assets — ogni endpoint, parametri completi e una playground interattiva (è qui che si trovano gli esempi di richiesta/risposta).
  • Seedance Video — l’endpoint di generazione video che consuma questi asset.