API Seedance 2.0: testo e immagine in video con Python

Seedance 2.0 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 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 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.

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 e la panoramica dell'API media 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.

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, 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.

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.

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

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.

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.

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.

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 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.

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 (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, 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, 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, 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, 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, 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.

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.

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, verificata il 30 ottobre 2026
• BytePlus ModelArk: API per creare un task di generazione video, verificata il 30 ottobre 2026
• BytePlus ModelArk: prezzi dei modelli e formula token, verificata il 30 ottobre 2026

La documentazione di OmniaKey, verificata il 30 ottobre 2026: API video, panoramica dell'API media e errori API.