# Seedance 2.5 Flash API Guida completa all’API dei modelli di generazione video Seedance 2.5 Flash di ByteDance. ## Varianti del modello Questa API supporta tre varianti del modello: | Modello | ID | Descrizione | |-------|----|-------------| | **Seedance 2.5 Flash Text to Video** | `seedance-v2.5-flash-text-to-video` | Generazione di video di alta qualità a partire da un testo | | **Seedance 2.5 Flash Image to Video** | `seedance-v2.5-flash-image-to-video` | Generazione di video a partire dal primo fotogramma o dal primo e dall’ultimo fotogramma | | **Seedance 2.5 Flash Reference to Video** | `seedance-v2.5-flash-reference-to-video` | Generazione di video guidata da immagini, video e audio di riferimento | ## Confronto rapido | Caratteristica | Da testo a video | Da immagine a video | Da riferimenti a video | |---------|---------------|----------------|--------------------| | Durata | 4–30 secondi | 4–30 secondi | 4–30 secondi | | Risoluzioni disponibili | 480p, 720p | 480p, 720p | 480p, 720p | | Rapporto d’aspetto | Facoltativo (predefinito: 16:9) | Non supportato | Facoltativo (predefinito: 16:9) | | Contenuti multimediali obbligatori | Nessuno | Immagine del primo fotogramma | Nessuno | | Contenuti multimediali facoltativi | Nessuno | Immagine dell’ultimo fotogramma | Immagini, video e audio | ### Rapporti d’aspetto supportati Le varianti che generano video da testo e da riferimenti supportano i seguenti rapporti d’aspetto: `21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4` La variante che genera video da un’immagine non supporta il parametro `aspect_ratio`. ### Risoluzioni disponibili | Risoluzione | Descrizione | |------------|-------------| | `480p` | Definizione standard | | `720p` | Alta definizione | ## Seedance 2.5 Flash Text to Video ### Endpoint ``` POST /api/v1/video/task ``` ### Parametri della richiesta #### Obbligatori | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `model_name` | string | Deve essere `"seedance-v2.5-flash-text-to-video"` | | `prompt` | string | Prompt per la generazione del video, fino a 5000 caratteri | | `resolution` | string | Risoluzione di uscita: `"480p"` o `"720p"`. Nessun valore predefinito | | `duration` | integer | Durata del video in secondi interi, da 4 a 30 con incrementi di 1. Nessun valore predefinito | #### Facoltativi | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `aspect_ratio` | string | Rapporto d’aspetto del video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` o `"3:4"`. Valore predefinito: `"16:9"` | | `sound` | boolean | Indica se generare l’audio. Il valore predefinito è `true`. Con `false` si ottiene un video senza audio | ### Esempio di richiesta ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model_name: 'seedance-v2.5-flash-text-to-video', prompt: 'A golden retriever running through a sunlit meadow', resolution: '720p', duration: 8, aspect_ratio: '16:9', sound: true }) }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Seedance 2.5 Flash Image to Video ### Parametri della richiesta #### Obbligatori | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `model_name` | string | Deve essere `"seedance-v2.5-flash-image-to-video"` | | `prompt` | string | Prompt per la generazione del video, fino a 5000 caratteri | | `resolution` | string | Risoluzione di uscita: `"480p"` o `"720p"`. Nessun valore predefinito | | `duration` | integer | Durata del video in secondi interi, da 4 a 30 con incrementi di 1. Nessun valore predefinito | | `image_url` | string | URL dell’immagine del primo fotogramma. Il video generato mantiene il rapporto d’aspetto di questa immagine. Vedere la sezione «Limiti dei contenuti multimediali» di seguito | #### Facoltativi | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `image_end_url` | string | URL facoltativo dell’immagine dell’ultimo fotogramma. Si consiglia di usare lo stesso rapporto d’aspetto del primo fotogramma. Vedere la sezione «Limiti dei contenuti multimediali» di seguito | | `sound` | boolean | Indica se generare l’audio. Il valore predefinito è `true`. Con `false` si ottiene un video senza audio | > Non includere `aspect_ratio` nelle richieste di generazione video da un’immagine. Il modello non supporta questo parametro. ### Esempio di richiesta ```javascript { model_name: 'seedance-v2.5-flash-image-to-video', image_url: 'https://example.com/first-frame.jpg', image_end_url: 'https://example.com/last-frame.jpg', prompt: 'Camera slowly pulls back to reveal the full landscape', resolution: '720p', duration: 8, sound: true } ``` ## Seedance 2.5 Flash Reference to Video ### Parametri della richiesta #### Obbligatori | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `model_name` | string | Deve essere `"seedance-v2.5-flash-reference-to-video"` | | `prompt` | string | Prompt per la generazione del video, fino a 5000 caratteri. Scrivere un normale prompt senza segnaposto oppure usare la funzione di riferimento @ (AT) con `<<>>`, `<<>>` e `<<>>` per richiamare esplicitamente gli elementi degli array multimediali corrispondenti | | `resolution` | string | Risoluzione di uscita: `"480p"` o `"720p"`. Nessun valore predefinito | | `duration` | integer | Durata del video in secondi interi, da 4 a 30 con incrementi di 1. Nessun valore predefinito | #### Contenuti multimediali di riferimento Tutti i contenuti multimediali di riferimento sono facoltativi. È possibile inviare richieste con sole immagini, solo video, solo audio oppure senza alcun riferimento. Per la generazione senza riferimenti si consiglia la variante Text to Video. | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `images` | string[] | Da 0 a 10 URL di immagini di riferimento, richiamate nell’ordine dell’array. Vedere «Limiti dei contenuti multimediali» di seguito | | `videos` | string[] | Da 0 a 5 URL di video di riferimento in formato MP4 o MOV. Ogni video deve durare da 2 a 30 secondi, per un massimo di 30 secondi complessivi. Vedere «Limiti dei contenuti multimediali» di seguito. Ai fini della fatturazione, la durata totale dei video di riferimento viene arrotondata al secondo più vicino (i mezzi secondi si arrotondano per eccesso) e poi sommata alla durata del video generato | | `audios` | string[] | Da 0 a 5 URL di clip audio di riferimento in formato WAV o MP3. Ogni clip deve durare da 2 a 30 secondi e non superare i 15 MB. La durata totale non deve superare i 30 secondi | #### Segnaposto di riferimento @ (AT) La funzione di riferimento @ (AT) collega i contenuti multimediali di riferimento al prompt tramite segnaposto numerati nel formato `<<<...>>>`. Per ogni tipo di contenuto la numerazione parte da `1` e segue l’ordine dell’array corrispondente: | Segnaposto | Valore richiamato | |-------------|------------------| | `<<>>` | `images[0]` | | `<<>>` | `images[1]` | | `<<>>` | `videos[0]` | | `<<>>` | `audios[0]` | Ad esempio, se la prima immagine è il riferimento per un personaggio e la seconda per una scena, usare `<<>>` per il personaggio e `<<>>` per la scena in `prompt`. Ogni segnaposto deve corrispondere a un elemento presente nel relativo array. #### Facoltativi | Parametro | Tipo | Descrizione | |-----------|------|-------------| | `aspect_ratio` | string | Rapporto d’aspetto del video: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` o `"3:4"`. Valore predefinito: `"16:9"` | | `sound` | boolean | Indica se generare l’audio. Il valore predefinito è `true`. Con `false` si ottiene un video senza audio | ### Esempio di richiesta ```javascript { model_name: 'seedance-v2.5-flash-reference-to-video', prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere', resolution: '720p', duration: 8, aspect_ratio: '16:9', sound: true, images: ['https://example.com/subject-reference.jpg'], videos: ['https://example.com/motion-reference.mp4'], audios: ['https://example.com/atmosphere-reference.mp3'] } ``` ### Esempio di richiesta di generazione video con riferimenti @ (AT) ```javascript { model_name: 'seedance-v2.5-flash-reference-to-video', prompt: 'Place the explorer from <<>> in the environment from <<>>, following the camera movement in <<>> and speaking with the reference voice from <<>>', resolution: '720p', duration: 10, aspect_ratio: '16:9', sound: true, images: [ 'https://example.com/explorer-reference.jpg', 'https://example.com/environment-reference.png' ], videos: ['https://example.com/camera-movement-reference.mp4'], audios: ['https://example.com/voice-reference.mp3'] } ``` ## Limiti dei contenuti multimediali Questi limiti si applicano alle immagini del primo e dell’ultimo fotogramma e ai contenuti multimediali di riferimento per i modelli descritti in questa pagina. | Contenuto | Formati | Limiti | |-------|---------|--------| | Immagini | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | Ogni immagine deve essere inferiore a 30 MB. Larghezza e altezza devono essere entrambe comprese tra 300 e 6000 px, con un rapporto larghezza/altezza compreso tra 0,4 e 2,5 | | Video | MP4, MOV | Massimo 200 MB per video. Larghezza e altezza devono essere entrambe comprese tra 300 e 6000 px, con un rapporto larghezza/altezza compreso tra 0,4 e 2,5. La frequenza deve essere di 24–60 fotogrammi al secondo e il numero totale di pixel deve essere compreso tra 407696 e 8295044 | | Audio | WAV, MP3 | Massimo 15 MB per file | Le clip audio e i video di riferimento hanno limiti di durata complessiva separati, pari a 30 secondi per ciascun tipo. Anche i limiti numerici sono indipendenti: fino a 10 immagini, 5 video e 5 clip audio. Tutti i modelli richiedono `resolution` e `duration`, senza valori predefiniti. Se si omette `aspect_ratio`, le varianti che generano video da testo e da riferimenti usano `16:9`. L’audio è attivo per impostazione predefinita (`true`). Impostare il valore su `false` per generare un video muto. ## Formato della risposta ### Risposta iniziale Tutti i modelli restituiscono un `task_id` da usare per le richieste periodiche di verifica dello stato: ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "submitted" } } ``` ### Risposta alla richiesta di stato Interrogare periodicamente `GET /api/v1/video/{taskId}` per verificare lo stato: ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "succeed", "task_status_msg": null, "task_result": { "credit": 0.2, "videos": [ { "url": "https://example.com/generated-video.mp4" } ] } } } ``` ### Valori di stato - `submitted`: Richiesta accettata e in attesa di elaborazione - `processing`: Generazione del video in corso - `succeed`: Generazione del video completata - `failed`: Generazione del video non riuscita ## Tempo di elaborazione Il tempo di elaborazione varia in base alla durata, alla risoluzione e allo stato della coda. Verificare lo stato ogni 5–10 secondi. ## Buone pratiche 1. **Parametri obbligatori**: fornire sempre `prompt`, `resolution` e `duration`. Per la generazione da testo e da riferimenti, `aspect_ratio` è facoltativo e il valore predefinito è `16:9` 2. **Rapporto d’aspetto per la generazione da un’immagine**: non inviare `aspect_ratio` nelle richieste di questo tipo 3. **Video di riferimento**: i video sono facoltativi. La durata di ciascun video e la durata complessiva devono rispettare i limiti indicati 4. **Immagini di riferimento**: le immagini sono facoltative indipendentemente dai video e dall’audio. Fornire fino a 10 URL di immagini in formati supportati 5. **Audio di riferimento**: ogni clip deve durare da 2 a 30 secondi e non superare i 15 MB, con una durata complessiva massima di 30 secondi 6. **Ordine dei riferimenti**: disporre gli elementi di `images`, `videos` e `audios` nell’ordine desiderato e rispettare tale ordine quando si richiamano i riferimenti nel prompt 7. **Audio**: omettere `sound` per usare il valore predefinito `true` oppure impostarlo su `false` per disattivare la generazione dell’audio