# API Seedance 2.0: testo e immagine in video con Python > Chiama Seedance 2.0 da Python con un solo script: campi della richiesta, polling, limiti, errori e due clip 720p veri del 30 ottobre 2026. - Canonical HTML: https://omniakey.com/it/blog/seedance-2-0-api - Markdown: https://omniakey.com/it/blog/seedance-2-0-api.md - Published: 2026-10-30 (updated 2026-10-30) - Author: Kiki, COO at OmniaKey - Language: it - Category: API setup - Reading time: 11 min - All posts: https://omniakey.com/blog/llms.txt --- [Seedance 2.0](https://omniakey.com/it/dreamina-seedance-2-0-260128) gira sull'API media di OmniaKey con l'ID modello `dreamina-seedance-2-0-260128`. Si invia un task in POST a `https://api.omniakey.com/v1/media/tasks`, si interroga l'ID del task e si scarica l'MP4. I nostri due clip da 5 secondi in 720p, uno da testo e uno da un'immagine ferma, hanno impiegato 159 e 139 secondi il 30 ottobre 2026. ## Risposta breve - ID modello `dreamina-seedance-2-0-260128`, con tre operazioni: `text_to_video`, `image_to_video` e `reference_to_video` ([documentazione dell'API video](https://docs.omniakey.com/en/media/video) di OmniaKey, verificata il 30 ottobre 2026). - Crea, interroga, scarica: la chiamata di creazione risponde 202 con un id, poi chiami `GET /v1/media/tasks/{id}` ogni pochi secondi finché lo stato è `succeeded` ([panoramica dell'API media](https://docs.omniakey.com/en/media/overview) di OmniaKey, verificata il 30 ottobre 2026). - La durata va da 4 a 15 secondi interi e l'ID 2.0 completo produce 480P, 720P e 1080P. - Il corpo della richiesta resta sotto 1 MiB, base64 incluso. - I nostri due render da 5 secondi in 720p hanno richiesto 159 secondi (testo in video) e 139 secondi (primo fotogramma). ## Cosa serve prima della prima chiamata? Una chiave API OmniaKey, Python 3 e l'ID modello esatto. Lo script importa solo la libreria standard, quindi gira senza virtualenv e senza installare pacchetti. Esporta la chiave come `OMNIAKEY_API_KEY` prima della prima chiamata. Lo script la legge una volta e la invia come Bearer token a ogni richiesta, così la chiave resta fuori dal file e dalla cronologia git. Crea con `POST https://api.omniakey.com/v1/media/tasks` e interroga con `GET https://api.omniakey.com/v1/media/tasks/{id}`. Questi due più `POST /v1/media/tasks/{id}/cancel` sono tutta l'API media (panoramica dell'API media, verificata il 30 ottobre 2026). Scrivi gli ID modello per intero. OmniaKey non serve gli alias brevi `seedance-2` e `seedance-2-5`, che rispondono `503 no_available_channel` (documentazione dell'API video, verificata il 30 ottobre 2026). I job video vengono addebitati in anticipo per ogni secondo di output generato e l'addebito torna automaticamente quando un job finisce `failed` o `canceled` (panoramica dell'API media, verificata il 30 ottobre 2026). Per il costo attuale al secondo, vedi [la pagina del modello Seedance 2.0](https://omniakey.com/it/dreamina-seedance-2-0-260128). ## Quali campi accetta una richiesta Seedance 2.0? Quattro campi di primo livello portano il job e un oggetto `parameters` porta le impostazioni di output. Solo `duration` non ha un valore predefinito sensato, quindi invialo sempre. - `model`: l'ID modello completo (gli alias brevi falliscono) - `type`: `video` (il tipo di media) - `operation`: `text_to_video`, `image_to_video`, `reference_to_video` (nome senza prefisso) - `input.prompt`: una stringa (scena, azione e camera, fino a 12,000 caratteri) - `input.media[]`: `{"type": "first_frame", "url": …}` (un primo fotogramma, oppure `reference_image`) Dentro `parameters`: - `duration`: da 4 a 15, secondi interi (decide il prezzo) - `resolution`: `480P`, `720P`, `1080P` (Fast e Mini si fermano a 720P) - `ratio`: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive` (`adaptive` segue il fotogramma) - `generate_audio`: `true` per impostazione predefinita, oppure `false` (`false` produce un MP4 muto) - `n`: `1` (deve essere 1) Le due liste seguono [la documentazione dell'API video](https://docs.omniakey.com/en/media/video) e [la panoramica dell'API media](https://docs.omniakey.com/en/media/overview) di OmniaKey (verificate il 30 ottobre 2026), con il limite del prompt preso dalla pagina del modello. Invia il nome dell'operazione senza prefisso; il prefisso del tipo di media lo aggiunge OmniaKey (documentazione dell'API video, verificata il 30 ottobre 2026). I parametri che non riconosce arrivano al provider così come sono (panoramica dell'API media, verificata il 30 ottobre 2026). Una trappola attende chi parte dalla documentazione del fornitore: l'API di creazione task di BytePlus mette i campi dentro `content[]` e al primo livello, quindi il codice di un tutorial BytePlus non gira così com'è su `/v1/media/tasks` (API di creazione task di BytePlus, verificata il 30 ottobre 2026). ## Lo script Python Un solo file esegue entrambe le operazioni e l'unica differenza è il corpo che costruisce. Salvalo come `seedance_video.py` ed eseguilo con `python3 seedance_video.py`. ```python import base64 import json import os import time import urllib.error import urllib.request import uuid API = "https://api.omniakey.com/v1/media/tasks" KEY = os.environ["OMNIAKEY_API_KEY"] MODEL = "dreamina-seedance-2-0-260128" def request(method, url, body=None, extra_headers=None): headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"} data = None if body is not None: headers["Content-Type"] = "application/json" data = json.dumps(body).encode() headers.update(extra_headers or {}) req = urllib.request.Request(url, data=data, headers=headers, method=method) with urllib.request.urlopen(req, timeout=120) as resp: return json.load(resp) def poll(url, attempts=5): for attempt in range(attempts): try: return request("GET", url) except urllib.error.HTTPError as err: if err.code < 500 or attempt == attempts - 1: raise except urllib.error.URLError: if attempt == attempts - 1: raise time.sleep(5 * (attempt + 1)) def run_task(body, out_path): task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"] print("task", task, flush=True) for _ in range(180): # polling ogni 5 secondi, fino a 15 minuti time.sleep(5) state = poll(f"{API}/{task}") if state["status"] not in ("queued", "processing"): break else: raise TimeoutError(f"{task} is still {state['status']}: poll it again later, do not resubmit") if state["status"] != "succeeded": raise RuntimeError(state.get("error") or state["status"]) asset_url = state["assets"][0]["url"] # link firmato: dura poco, scarica subito req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"}) with urllib.request.urlopen(req, timeout=300) as resp, open(out_path, "wb") as f: f.write(resp.read()) return task def text_to_video(prompt, out_path, duration=5, resolution="720P", ratio="16:9"): body = { "model": MODEL, "type": "video", "operation": "text_to_video", "input": {"prompt": prompt}, "parameters": {"duration": duration, "resolution": resolution, "ratio": ratio}, } return run_task(body, out_path) def image_to_video(prompt, image_path, out_path, duration=5, resolution="720P", audio=False): with open(image_path, "rb") as f: raw = f.read() if len(raw) > 700_000: # base64 aggiunge un terzo, e il corpo deve restare sotto 1 MiB raise ValueError("first frame too large: save it as a JPEG about 1024 px wide") frame = "data:image/jpeg;base64," + base64.b64encode(raw).decode() body = { "model": MODEL, "type": "video", "operation": "image_to_video", "input": {"prompt": prompt, "media": [{"type": "first_frame", "url": frame}]}, "parameters": {"duration": duration, "resolution": resolution, "ratio": "adaptive", "generate_audio": audio}, } return run_task(body, out_path) if __name__ == "__main__": print("done", text_to_video( "Close-up of a tall glass on a wooden bar counter. Sparkling water is poured over ice; bubbles " "rise and the ice cubes clink and shift. Warm evening light from the left. The camera slowly " "pushes in. Sound of pouring, fizzing and clinking ice. No people, no text.", "sparkling-glass.mp4", )) print("done", image_to_video( "The cat slowly wakes, stretches its front paws and yawns, then looks toward the window. " "Raindrops keep running down the glass. The camera stays still.", "cat.jpg", "cat-wakes.mp4", )) ``` Sei punti di questo file contano prima di cambiare qualsiasi cosa. - Ogni richiesta di creazione porta un `Idempotency-Key` casuale; ripetere quella chiave con lo stesso corpo restituisce il task originale con HTTP 200 e non addebita due volte (panoramica dell'API media, verificata il 30 ottobre 2026). - Il ciclo dorme 5 secondi tra un polling e l'altro e si ferma dopo 180 tentativi, cioè 15 minuti. - Un timeout significa che il job sta ancora renderizzando. Interroga di nuovo lo stesso ID più tardi e non inviare mai di nuovo, altrimenti paghi un secondo clip. - `assets[0].url` è un link firmato che dura circa un'ora, quindi lo script scarica appena il task riesce (panoramica dell'API media, verificata il 30 ottobre 2026). - `progress.percent` può restare a 0 mentre il job gira, quindi il ciclo segue solo `status` (documentazione dell'API video, verificata il 30 ottobre 2026). - La funzione per le immagini rifiuta un file oltre 700,000 byte, perché base64 aggiunge un terzo e il corpo deve restare sotto 1 MiB. La forma della richiesta è la stessa di [Kling 3.0 sulla stessa API](https://omniakey.com/it/blog/kling-3-0-api), quindi cambiare modello cambia l'ID e i parametri, non il codice intorno. ## Come si invia un primo fotogramma per image to video? Metti l'immagine in `input.media[]` con `"type": "first_frame"`, inline come URI `data:image/jpeg;base64,...`, la forma usata dal nostro clip del gatto. `input.media[]` accetta un URL HTTPS pubblico o un data URI inline, e l'intero corpo è limitato a 1 MiB (documentazione dell'API video, verificata il 30 ottobre 2026). Un test di OmniaKey ha visto un normale link HTTPS al fotogramma rifiutato con `provider_submit_rejected`, ed è per questo che l'esempio invia un data URI (documentazione dell'API video, verificata il 30 ottobre 2026). Base64 aggiunge un terzo, quindi parti da un JPEG largo circa 1024 pixel: il nostro primo fotogramma era di 134,356 byte, e un PNG da 4 MB verrebbe respinto. Qui lascia `parameters.ratio` su `adaptive`: segue la forma dell'immagine che hai inviato, ed è così che un fermo immagine 1024×571 è diventato un clip 1280×720. Per `reference_to_video` lo stesso array accetta `"type": "reference_image"` (documentazione dell'API video, verificata il 30 ottobre 2026). ## Due clip che abbiamo prodotto Entrambi i task sono partiti il 30 ottobre 2026 con il file qui sopra, senza modifiche. Il primo è testo in video, task `task_uF2QUtbeAAUW11lXEaLxNw1ZnBUoqvNk`, creato alle 01:39:43 UTC e riuscito alle 01:42:22 UTC. Il prompt chiedeva il suono della mescita, quindi l'audio è rimasto attivo. ```prompt Close-up of a tall glass on a wooden bar counter. Sparkling water is poured over ice; bubbles rise and the ice cubes clink and shift. Warm evening light from the left. The camera slowly pushes in. Sound of pouring, fizzing and clinking ice. No people, no text. ``` ![Otto fotogrammi di un bicchiere alto su un bancone di legno, dalla mescita a bicchiere vuoto fino al bicchiere pieno con bollicine sul fondo.](https://omniakey.com/_img/blog/seedance-2-0-api/seedance-sparkling-glass-frames.e6c0aae7.1280.webp) _Otto fotogrammi del clip del bicchiere in ordine temporale, da 0.0 a 5.0 secondi. Seedance 2.0 tramite l'API OmniaKey, testo in video, 5 secondi, 720P, prodotto il 30 ottobre 2026._ I fotogrammi mostrano un bicchiere con ghiaccio su un bancone di legno, con bottiglie e luci calde sfocate dietro. Il bicchiere cresce dal primo all'ultimo fotogramma, la carrellata che il prompt chiedeva, e finisce pieno con le bollicine sul fondo. Il secondo è immagine in video, task `task_u85W0jn1sQLkrszJlxqXF1hxJYhsndxK`, creato alle 01:42:33 UTC e riuscito alle 01:44:52 UTC. Il primo fotogramma è un fermo immagine di un gatto rosso che dorme su una pila di libri vecchi accanto a una finestra sotto la pioggia (1024×571 pixel), inviato come data URI con `"type": "first_frame"`. ```prompt The cat slowly wakes, stretches its front paws and yawns, then looks toward the window. Raindrops keep running down the glass. The camera stays still. ``` ![Otto fotogrammi di un gatto rosso che dorme su una pila di libri accanto a una finestra piovosa, si sveglia, allunga le zampe e sbadiglia.](https://omniakey.com/_img/blog/seedance-2-0-api/seedance-cat-wakes-frames.32a57df5.1280.webp) _Otto fotogrammi del clip del gatto in ordine temporale, da 0.0 a 5.0 secondi. Seedance 2.0 tramite l'API OmniaKey, immagine in video, 5 secondi, 720P, prodotto il 30 ottobre 2026._ Il gatto alza la testa, apre gli occhi, allunga entrambe le zampe anteriori oltre il bordo dei libri, sbadiglia a lungo e gira la testa verso la finestra, nell'ordine dato dal prompt. La pioggia continua a scorrere sul vetro e l'inquadratura resta ferma, come richiesto. ![A sinistra il fermo immagine del gatto rosso inviato come primo fotogramma, a destra l'ultimo fotogramma del clip, con le zampe allungate sui libri e la testa girata verso la finestra.](https://omniakey.com/_img/blog/seedance-2-0-api/cat-first-last.60a2db0f.1600.webp) _A sinistra: il fermo immagine inviato come primo fotogramma. A destra: l'ultimo fotogramma del clip del gatto. Seedance 2.0 tramite l'API OmniaKey, immagine in video, 5 secondi, 720P, prodotto il 30 ottobre 2026._ Queste due esecuzioni coprono testo in video e primo fotogramma a 720P per 5 secondi. Non abbiamo provato 1080P, Fast, Mini, 2.5, `reference_to_video`, un link HTTPS al fotogramma né altre durate. ### Cosa hanno misurato i file Entrambi i download sono MP4 H.264 a 1280×720 e 24 fps: 121 fotogrammi, 5.04 secondi. |Clip|Bicchiere|Gatto| |-|-|-| |Operazione|testo in video|immagine in video| |Tempo di completamento|159 s|139 s| |Dimensione file|2,070,248 bytes|1,352,027 bytes| |Video|1280×720, 24 fps, 121 fotogrammi|1280×720, 24 fps, 121 fotogrammi| |Audio|traccia AAC|nessuna| La traccia del clip del bicchiere porta mescita, frizzio e tintinnio del ghiaccio, senza voci e senza musica. Il clip del gatto non ha alcuna traccia, perché la richiesta ha inviato `generate_audio: false`. Entrambi i record dei task riportano `usage.completion_tokens: 108900`, cioè 121 × 1280 × 720 ÷ 1024, la formula token che BytePlus usa per stimare la fatturazione video (pagina dei prezzi di BytePlus, verificata il 30 ottobre 2026). La documentazione di OmniaKey dice che un clip da 6 secondi in 720p di solito finisce entro circa un minuto (documentazione dell'API video, verificata il 30 ottobre 2026). I nostri hanno impiegato 159 e 139 secondi, e tre clip da 5 secondi in 720p nel nostro [confronto del 26 ottobre](https://omniakey.com/it/blog/happyhorse-1-1-vs-seedance-2-0) hanno impiegato 144.8, 319.0 e 184.7 secondi. Metti in conto da 2 a 5 minuti e interroga invece di tenere aperta la richiesta. ## Quali errori e limiti incontrerai? Controlla prima tre impostazioni: l'ID modello, una durata da 4 a 15 e l'audio, che il filtro del provider può rifiutare. |Stato / Codice|Cosa cambiare| |-|-| |400 `invalid_request`|corpo o `input.prompt`| |400 `model_price_error`|durata a 4–15 s| |403 `model_not_allowed`|accesso ai modelli della chiave| |409 `idempotency_key_reused`|una chiave nuova per ogni corpo| |503 `no_available_channel`|ID completo, operazione senza prefisso| |task fallito, errore del provider|leggi `error`, poi riprova| Questi codici vengono dalla panoramica dell'API media e dalla documentazione dell'API video (verificate il 30 ottobre 2026). Un task che finisce `failed` restituisce l'addebito anticipato, quindi un render rifiutato ti costa solo tempo. Attento all'impostazione audio. Seedance produce una traccia per impostazione predefinita, e lasciarla attiva ha fatto rifiutare al provider una richiesta 480P da 4 secondi con `OutputAudioSensitiveContentDetected.PolicyViolation`, quindi invia `parameters.generate_audio: false` se la scena non ha bisogno di suono (documentazione dell'API video, verificata il 30 ottobre 2026). BytePlus scrive che la serie 2.0 non accetta immagini o video di riferimento con volti umani reali (pagina Seedance 2.0 di BytePlus, verificata il 30 ottobre 2026). Seedance 2.0 non ha nemmeno `seed` e `camera_fixed`, che pure sono campi dell'API di creazione task del fornitore (API di creazione task di BytePlus, verificata il 30 ottobre 2026). Quindici secondi sono il tetto di questa famiglia e `duration: -1` non dà nulla in più; un take da 20 o 30 secondi sta su [Seedance 2.5](https://omniakey.com/it/dreamina-seedance-2-5-260628) (pagina del modello Seedance 2.0, verificata il 30 ottobre 2026). OmniaKey non pubblica limiti di frequenza fissi; tratta l'HTTP 429 come ritentabile con backoff esponenziale ([pagina degli errori API di OmniaKey](https://docs.omniakey.com/en/api/errors), verificata il 30 ottobre 2026). ## Seedance 2.0, Fast, Mini o 2.5? Quattro livelli accettano lo stesso corpo di richiesta, quindi passare da uno all'altro costa un ID modello e, su Fast e Mini, un tetto di risoluzione più basso. - [Seedance 2.0](https://omniakey.com/it/dreamina-seedance-2-0-260128), `dreamina-seedance-2-0-260128`: 480P, 720P e 1080P, da 4 a 15 secondi. Il prezzo di listino BytePlus per un clip da 5 secondi è $0.76 a 720p e $0.35 a 480p (pagina dei prezzi di BytePlus, verificata il 30 ottobre 2026). - [Seedance 2.0 Fast](https://omniakey.com/it/dreamina-seedance-2-0-fast-260128), `dreamina-seedance-2-0-fast-260128`: 480P e 720P, da 4 a 15 secondi. Il prezzo di listino BytePlus per un clip da 5 secondi è $0.60 a 720p e $0.28 a 480p. - [Seedance 2.0 Mini](https://omniakey.com/it/dreamina-seedance-2-0-mini-260615), `dreamina-seedance-2-0-mini-260615`: 480P e 720P, da 4 a 15 secondi. Il prezzo di listino BytePlus per un clip da 5 secondi è $0.38 a 720p e $0.18 a 480p. - [Seedance 2.5](https://omniakey.com/it/dreamina-seedance-2-5-260628), `dreamina-seedance-2-5-260628`: l'unico ID della famiglia che accetta un take da 20 o 30 secondi, e il più lento: circa quattro minuti per un clip 480P da 4 secondi (documentazione dell'API video, verificata il 30 ottobre 2026). Il lato immagine è trattato nella [nostra recensione di Seedance 2.5](https://omniakey.com/it/blog/seedance-2-5-review). Le pagine modello di OmniaKey indicano un clip 480P da 4 secondi in circa un minuto su 2.0, due minuti su Fast e 100 secondi su Mini (verificate il 30 ottobre 2026). Prendi l'ID 2.0 completo quando ti serve un master 1080P, perché Fast e Mini si fermano a 720P (documentazione dell'API video, verificata il 30 ottobre 2026). OmniaKey applica tariffe proprie a questi ID, quindi vedi le tariffe attuali sulla [pagina del modello Seedance 2.0](https://omniakey.com/it/dreamina-seedance-2-0-260128). ## FAQ ### Esiste un'API ufficiale di Seedance 2.0? Sì. La vende BytePlus ModelArk, e per attivarla lì serve un saldo del conto sopra USD 30, un Savings Plan o un pacchetto di risorse Seedance (pagina Seedance 2.0 di BytePlus, verificata il 30 ottobre 2026). Lo script qui sopra chiama lo stesso ID modello tramite l'API media di OmniaKey. ### Posso inviare l'URL di un'immagine invece di base64? La documentazione di OmniaKey elenca un URL HTTPS pubblico accanto al data URI inline (documentazione dell'API video, verificata il 30 ottobre 2026). Le nostre esecuzioni sono andate inline perché un link HTTPS al fotogramma è tornato come `provider_submit_rejected` nel test di OmniaKey stesso, quindi prova prima un URL su un clip di test. ### Come disattivo l'audio? Invia `parameters.generate_audio: false` e l'MP4 arriva senza alcuna traccia audio, come nel clip del gatto. Su questo modello l'audio è attivo per impostazione predefinita. ### Perché la mia richiesta è andata in timeout? Il clip di solito sta ancora renderizzando, dato che i job da 5 secondi in 720p hanno richiesto da 139 a 319 secondi nelle nostre esecuzioni. Interroga di nuovo lo stesso ID, non inviare mai di nuovo e alza il limite del ciclo di 15 minuti per i clip da 15 secondi. ### Quanto durano i link ai video? Il link firmato in `assets[0].url` dura circa un'ora e il record del task viene conservato per 24 ore dalla creazione (panoramica dell'API media, verificata il 30 ottobre 2026). Scarica al primo successo, oppure interroga di nuovo il task per un link fresco. ## Fonti controllate - [BytePlus ModelArk: guida a Seedance 2.0](https://docs.byteplus.com/en/docs/ModelArk/seedance-2-0), verificata il 30 ottobre 2026 - [BytePlus ModelArk: API per creare un task di generazione video](https://docs.byteplus.com/en/docs/ModelArk/create-video-generation-task-api), verificata il 30 ottobre 2026 - [BytePlus ModelArk: prezzi dei modelli e formula token](https://docs.byteplus.com/en/docs/ModelArk/model-pricing), verificata il 30 ottobre 2026 La documentazione di OmniaKey, verificata il 30 ottobre 2026: [API video](https://docs.omniakey.com/en/media/video), [panoramica dell'API media](https://docs.omniakey.com/en/media/overview) e [errori API](https://docs.omniakey.com/en/api/errors).