Seedance 2.5

Funzionalità

Prezzi e crediti

La generazione di video viene tariffata in crediti in base alla durata fatturabile in secondi. Senza un video di input, la durata fatturabile corrisponde alla durata del video generato; in presenza di un video di input, include anche la durata del video di riferimento.

La tabella seguente mostra i crediti addebitati al secondo e non il costo totale di un'operazione. La tariffa varia a seconda del modello, della risoluzione finale e dell'eventuale inserimento di video di riferimento nella modalità reference-to-video. Per il calcolo del costo totale, consulta le formule e gli esempi riportati sotto la tabella.

• Senza video in input: secondi generati × tariffa senza video.
• Con video in input: (secondi generati + secondi effettivi del video di riferimento) × tariffa con video. Il server calcola la durata totale del video di riferimento arrotondandola al secondo superiore prima dell'addebito.
• I soli riferimenti di immagini o audio utilizzano la tariffa senza video. La tariffa con video si applica esclusivamente nella modalità da riferimento a video quando vengono forniti video come input.

I crediti vengono prenotati all'invio e addebitati solo a completamento avvenuto. I task falliti o andati in timeout avviano la procedura di rimborso. Lo stato di fatturazione refund_failed indica che il rimborso non è andato a buon fine; verifica i log delle API o contatta l'assistenza.

Autenticazione

Crea una chiave API nella dashboard. La chiave completa viene mostrata una sola volta. Conservala sul tuo server e inviala come token Bearer in ogni richiesta.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Imposta la variabile d'ambiente SEEVIO_API_KEY prima di eseguire questi esempi. Gli esempi in JavaScript vengono eseguiti sul server con Node.js; gli esempi in Python utilizzano la libreria requests.

Avvio rapido

Invia questa richiesta minima, salva il taskId restituito e usa l'esempio di query del task riportato di seguito. Il valore dei crediti nella risposta di creazione corrisponde all'importo prenotato.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

Esempio di risposta alla creazione del task

Una volta accettata la richiesta precedente, l'API restituisce questa risposta JSON. taskId è l'identificativo del task da utilizzare per le successive verifiche sullo stato; credits indica il numero di crediti riservati a questo task. Questa risposta conferma la corretta creazione del task, non che il video sia pronto. Sarà necessario monitorare periodicamente lo stato del task o utilizzare un Webhook per ricevere il video finale.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

Crea un task

Invia un oggetto JSON contenente model e input, insieme a un callback_url opzionale. Specifica sempre l'ID del modello indicato in questa pagina; se omesso, verrà selezionato seedance-2-0.

Corpo della richiesta

Parametri di input

Fornisci image_urls, video_urls e audio_urls sotto forma di array di stringhe URL (string[]). Ogni URL fornito deve essere accessibile pubblicamente tramite HTTPS, inclusi i contenuti multimediali ignorati dalla modalità selezionata.

I campi booleani devono essere impostati su true o false in formato JSON, non come stringhe o numeri.

Risposta di creazione

La risposta HTTP 200 restituisce taskId (stringa) e credits (numero). Questo conferma la creazione del task, non il suo completamento. L'importo indicato sotto corrisponde all'avvio rapido a 720p di 5 secondi.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 100
}

Anteprima Draft → Versione finale 1080p

Seedance 2.5 supporta un flusso di lavoro in due passaggi: genera prima un Draft a 480p per verificare la resa visiva e il movimento, quindi usalo come riferimento per creare il video finale a 1080p. Entrambi i passaggi utilizzano l'endpoint POST /v1/videos/generations e creano task separati e addebitabili.

La modalità Draft può ridurre i costi quando provi idee diverse. Invece di generare ogni tentativo a 1080p, crea diversi Draft a 480p a un costo inferiore, scegli quello che preferisci e usalo per generare un video finale a 1080p. Puoi così esplorare risultati diversi a un costo minore prima di pagare per la versione scelta in alta definizione.

1. Genera un Draft a 480p

Imposta input.draft=true e fornisci il prompt consueto, i riferimenti e le impostazioni di generazione. Nella modalità Draft la risoluzione predefinita è 480p; altre risoluzioni verranno rifiutate. È possibile abilitare return_last_frame per il Draft, come mostrato di seguito.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "draft": true,
    "duration": 5,
    "resolution": "480p",
    "return_last_frame": true
  }
}'

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 50
}

2. Attendi il completamento del Draft

Salva il taskId ricevuto dalla risposta di creazione ed effettua una chiamata GET /v1/tasks/TASK_ID finché lo stato non diventa completed. La risposta della query conterrà is_draft=true; puoi visualizzare l'anteprima del video in data.results. Se richiesto e disponibile, l'ultimo fotogramma sarà visibile in data.last_frame_url.

È anche possibile ricevere un Webhook al completamento del Draft. Imposta callback_url a livello principale nella richiesta di creazione del Draft. Una volta completato il Draft, verrà inviata una notifica a quell'URL: il tuo servizio potrà così salvare il risultato, aggiornare lo stato del task o avviare i passaggi successivi. Consulta la sezione Webhook di questa pagina per i formati di callback.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "is_draft": true,
  "draft_task_id": null,
  "status": "completed",
  "billing_status": "charged",
  "credits": 50,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": "https://cdn.seevio.ai/api/images/draft-last-frame.jpg",
    "processing_time": 48
  }
}

3. Genera la versione finale a 1080p

Sostituisci draft_task_id in questo esempio con il taskId del tuo Draft completato. Il video finale erediterà i contenuti e la durata del Draft. La risoluzione predefinita è 1080p e non sono accettate altre risoluzioni. I parametri output_format, watermark e return_last_frame possono essere impostati in modo indipendente per ciascun video finale; il callback_url rimane definito a livello principale della richiesta.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "draft_task_id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
    "resolution": "1080p",
    "output_format": "mp4",
    "watermark": false,
    "return_last_frame": true
  }
}'

La risposta contiene un nuovo taskId per il video finale. Effettua il polling su questo nuovo ID o attendi la notifica del webhook. La risposta alla query del video finale conterrà is_draft=false e il parametro draft_task_id corrispondente all'ID del task del Draft originale. Il Draft originale rimarrà comunque disponibile. Ogni richiesta di generazione finale accettata crea un nuovo task fatturato separatamente.

{
  "taskId": "final_7mQx2pN8kR4vT9cL6bW3",
  "credits": 150
}

Fatturazione dei Draft e dei video finali

I Draft utilizzano le tariffe della risoluzione 480p sopra indicate, inclusi i video di riferimento se applicabili. I video finali utilizzano la tariffa per solo output a 1080p, pari a 30 crediti/secondo; l'eventuale video di riferimento in input non viene riaddebitato. Ad esempio, un Draft da 5 secondi senza video di riferimento costa 50 crediti, mentre il relativo video finale da 5 secondi costerà ulteriori 150 crediti.

Con duration=-1, il Draft e il relativo video finale riservano ciascuno crediti per un massimo di 30 secondi di output, più il video di riferimento in input solo per il Draft. Al completamento, se è possibile determinare la durata effettiva dell’output, il costo viene adeguato a tale durata e i crediti riservati non utilizzati vengono restituiti. Un video finale riserva fino a 900 crediti.

Modalità di generazione ed esempi

Da testo a video

Genera a partire da un prompt testuale. Gli URL dei file multimediali non vengono considerati in questa modalità.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

Primo fotogramma

Fornisci un'immagine come primo fotogramma e descrivi il movimento nel prompt.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "aspect_ratio": "adaptive"
  }
}'

Primo e ultimo fotogramma

Fornisci due URL di immagini in ordine: primo fotogramma, poi ultimo fotogramma. Questo esempio richiede anche il fotogramma finale del video generato.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "aspect_ratio": "adaptive",
    "return_last_frame": true
  }
}'

Riferimento multimodale

Combina riferimenti immagine, video e audio. Il prompt rimane obbligatorio. L'inserimento di un video di riferimento modifica la formula di fatturazione.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "Follow the reference camera movement and keep the character consistent. Use the audio for ambience.",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "reference-to-video",
    "image_urls": [
      "https://example.com/character.jpg"
    ],
    "video_urls": [
      "https://example.com/camera.mp4"
    ],
    "audio_urls": [
      "https://example.com/ambience.mp3"
    ],
    "aspect_ratio": "adaptive"
  }
}'

Riferimento audio

Usa un file audio come unico riferimento, accompagnato da un prompt testuale obbligatorio che descrive il video desiderato.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "Create a coastal sunrise scene matching the rhythm of this audio.",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "reference-to-video",
    "audio_urls": [
      "https://example.com/music.mp3"
    ]
  }
}'

Modifica video

Descrivi le modifiche e fornisci il video sorgente. Imposta duration=-1 e usa proporzioni adaptive. Per questo flusso di lavoro, usa una clip sorgente di almeno 4 secondi. La regola di fatturazione per duration=-1 è indicata sopra.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "Edit the source video: change the character’s coat to blue and preserve the camera movement.",
    "duration": -1,
    "resolution": "720p",
    "generation_type": "reference-to-video",
    "video_urls": [
      "https://example.com/source.mp4"
    ],
    "aspect_ratio": "adaptive"
  }
}'

Estensione video

Descrivi come deve proseguire il video sorgente. Usa proporzioni adaptive e imposta una durata standard entro i limiti del modello.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "Continue the camera movement from the source video, revealing a forest clearing.",
    "duration": 8,
    "resolution": "720p",
    "generation_type": "reference-to-video",
    "video_urls": [
      "https://example.com/source.mp4"
    ],
    "aspect_ratio": "adaptive"
  }
}'

Interroga un task

Sostituisci l'ID di esempio con il taskId restituito alla creazione. Le query restituiscono solo i task associati all'utente della chiave API; ID non accessibili o inesistenti restituiscono HTTP 404.

Come punto di partenza, effettua un polling ogni 10–20 secondi, rallenta le richieste in caso di HTTP 429 e interrompi quando lo stato diventa completed o failed. Per gli ambienti di produzione, consigliamo l'uso dei webhook. Ogni esempio di codice seguente esegue una singola query.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Task completato: risposta alla query con i risultati video

Quando la query restituisce status=completed, la generazione del video è terminata. Puoi trovare gli URL del video in data.results; assicurati di scaricarli prima della data indicata in data.video_expires_at. Lo stato billing_status=charged indica che i crediti prenotati sono stati effettivamente addebitati.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "is_draft": false,
  "draft_task_id": null,
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

Task fallito: risposta alla query con dettagli sul fallimento e sulla fatturazione

Se la query restituisce status=failed, significa che la generazione non è andata a buon fine. Consulta failed_reason per conoscerne il motivo e billing_status per l'esito del rimborso. In questo esempio, lo stato refunded indica che i crediti sono stati riaccreditati. La voce credits mostra la quota inizialmente prenotata e la risposta non include la chiave data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-5",
  "is_draft": false,
  "draft_task_id": null,
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Webhook

Imposta callback_url nella richiesta di creazione per ricevere una richiesta POST JSON al completamento o al fallimento del task. Restituisci una risposta 2xx entro 15 secondi. Gli invii non riusciti verranno riprovati; gestisci le notifiche duplicate in modo idempotente tramite l'ID del task.

L'endpoint di callback deve accettare richieste POST con un corpo in formato JSON (Content-Type: application/json).

Crea un task con callback

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-5",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Attività completata: payload di callback riuscito

In caso di generazione riuscita, la callback conterrà lo stato status=completed. Utilizza id per identificare l'attività e data.results per recuperare gli URL dei video. Assicurati di scaricare e salvare i risultati prima della scadenza indicata in data.video_expires_at.

created_at indica la creazione dell’evento; task_created_at quella del task, in secondi Unix. Gli esempi mostrano i campi consigliati; le risposte possono contenere campi aggiuntivi.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652848,
  "model": "seedance-2-5",
  "status": "completed",
  "task_created_at": 1788652800,
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

Attività non riuscita: payload di callback fallito

In caso di errore durante la generazione, la callback conterrà lo stato status=failed. Utilizza id per identificare l'attività, failed_reason per conoscere il motivo del fallimento e credits_refunded per verificare il numero di crediti riaccreditati.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652848,
  "model": "seedance-2-5",
  "status": "failed",
  "task_created_at": 1788652800,
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed",
  "credits_refunded": 100
}

Esempio di ricevitore

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

Questo esempio in Next.js legge il corpo JSON della callback e gestisce direttamente le attività completate e fallite. Ti consigliamo di aggiungere logiche di persistenza e deduplicazione dei task-ID per la tua applicazione, e di accodare i processi più lenti prima di confermare la callback.

Requisiti e limitazioni dei media

• Tutti i media e gli URL di callback devono essere URL HTTPS pubblici. Evita l'uso di localhost, IP privati o file che richiedono cookie o autenticazione. Gli URL dei file video/audio di riferimento devono indirizzare a file multimediali leggibili direttamente.
• In reference-to-video, fornisci almeno un riferimento, con un limite massimo di 30 immagini, 10 video, 10 file audio e 50 elementi multimediali complessivi. La durata totale dei video e quella degli audio non devono superare i 30 secondi ciascuna.
• La modalità text-to-video ignora tutti i riferimenti multimediali. La modalità image-to-video considera solo le immagini del primo e dell'ultimo fotogramma, ignorando i riferimenti video e audio. Usa la modalità reference-to-video per combinare più formati.
• Ogni file video o audio di riferimento deve avere una durata compresa tra 2 e 30 secondi. Per gli esempi di modifica video, usa clip sorgente di almeno 4 secondi.

Errori

Gli errori HTTP contengono un oggetto error con code e message. Un task accettato correttamente può comunque fallire in una fase successiva; interroga lo stato del task o gestisci la chiamata di callback per l'errore.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Limiti di frequenza

Creazione task: per impostazione predefinita, ciascuna chiave API consente fino a 100 richieste al minuto. Al momento non sono disponibili limiti di frequenza personalizzati.

Interrogazione task: per impostazione predefinita, ciascuna chiave API consente fino a 120 richieste al minuto. Le richieste di interrogazione e quelle di creazione dei task vengono conteggiate separatamente.