API Sora — text-to-video in un flusso di lavoro compatibile con OpenAI

Sora è il modello text-to-video di OpenAI e “la Sora API” è il modo in cui i team generano video programmaticamente invece di usare l’app consumer. Oggi su Kunavo, il text-to-video funziona con Google Veo 3 tramite un unico endpoint video in stile OpenAI — l’accesso a Sora è nella roadmap e, poiché l’endpoint è indipendente dal modello, passare a Sora in seguito richiederà una modifica di una sola parola. Questa guida mostra il flusso di lavoro con Veo 3, così ogni esempio può essere eseguito subito.

Che cos’è la Sora API?

Sora (Sora 2 e Sora 2 Pro) trasforma un prompt testuale — o un’immagine fissa — in una breve clip video, con audio sincronizzato in Sora 2. Il formato dell’API permette di inserire la generazione in una pipeline: riprese di marketing, animazioni di prodotto, b-roll, anteprime di storyboard. La struttura è la stessa nei moderni modelli video: invia un prompt e i parametri, ricevi un URL video ospitato.

Video su Kunavo oggi: Veo 3

Kunavo espone la generazione video tramite un unico endpoint in stile OpenAI, /v1/video/generations. Sora non è ancora abilitata nel catalogo; il modello text-to-video disponibile è Google Veo 3, che produce clip cinematografiche con audio nativo. Gli esempi seguenti usano veo-3 — quando arriverà Sora, l’unica modifica sarà il campo model.

Quickstart text-to-video

Una POST con la tua chiave Kunavo. La generazione può richiedere un paio di minuti, quindi la chiamata sincrona mantiene aperta la connessione finché la clip non è pronta:

import requests

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo-3",
        "prompt": "a cinematic dolly-in on a red origami crane unfolding, soft light",
        "aspect_ratio": "16:9",
    },
    timeout=600,  # generation can take minutes
)
print(resp.json()["data"][0]["url"])

duration (in secondi) imposta la durata del clip nei modelli con fatturazione al secondo: i modelli Seedance e il modello Wan 2.7. I modelli Veo lo ignorano; ogni clip Veo dura 8 secondi e viene fatturato per video.

Da immagine a video

Per animare un’immagine fissa, passa image_url (un URL https o un file caricato su /v1/files) insieme al prompt. Per un movimento controllato puoi passare un primo e un ultimo fotogramma con image_urls e image_mode: "frame". Gli esempi completi sono nella documentazione video.

Ciclo di vita delle attività asincrone

In produzione, non mantenere aperta una connessione per 10 minuti. Invia un’attività a /v1/videos, ricevi immediatamente un ID dell’attività, quindi esegui il polling di GET /v1/videos/{id} finché non viene completata. Gli URL dei risultati sono permanenti.

# Production: submit a task, then poll — no long-lived connection.
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "my-task-uuid",   # retry-safe within ~24h
    },
    json={"model": "veo-3", "prompt": "...", "aspect_ratio": "16:9"},
    timeout=60,
).json()
# then poll GET /v1/videos/{task["id"]} until it completes

La documentazione video illustra l’intero ciclo di polling, le chiavi di idempotenza e la consegna tramite webhook.

Prezzi

Veo 3 viene fatturato per video (qui è mostrata una clip di 8 secondi a 720p), circa 50–70% in meno rispetto al listino di Google. Le risoluzioni superiori costano di più — consulta la pagina dei prezzi per la tabella completa dei livelli.

Suggerimenti per i prompt video

• Descrivi la ripresa, non solo il soggetto. Il movimento della camera (dolly, panoramica, avvicinamento), la resa dell’obiettivo, l’illuminazione e il ritmo contano più degli aggettivi.
• Imposta esplicitamente il rapporto d’aspetto — 16:9 per il formato orizzontale, 9:16 per il formato verticale/social.
• Ogni clip Veo dura 8 secondi. Pianifica ogni ripresa per questa durata e concatena più generazioni per sequenze più lunghe.
• Usa un fotogramma di riferimento (image-to-video) quando hai bisogno che un personaggio o un prodotto specifico rimanga coerente.

Domande frequenti