API Sora — generare video AI su un endpoint simile a OpenAI (oggi con Veo 3.1)

Sora è il modello di OpenAI per la conversione da testo a video e “l'API Sora” è il modo con cui i team generano video programmaticamente anziché tramite l'app consumer. Su Kunavo oggi la conversione da testo a video avviene tramite Google Veo 3 su un endpoint video OpenAI-like: l'accesso a Sora è nella roadmap e, poiché l'endpoint è indipendente dal modello, il futuro passaggio a Sora richiederà una modifica di una sola parola. Questa guida mostra il flusso di lavoro con Veo 3, così ogni esempio funziona subito.

Cos'è l'API Sora?

Sora (Sora 2 e Sora 2 Pro) trasforma un prompt testuale — o un'immagine statica — in un breve clip video, con audio sincronizzato in Sora 2. La forma dell'API ti permette di inserire la generazione in una pipeline: riprese di marketing, animazioni di prodotto, B-roll, anteprime di storyboard. La forma è la stessa tra i moderni modelli video: invia prompt e parametri e ricevi un URL video ospitato.

Video su Kunavo oggi: Veo 3

Kunavo rende disponibile la generazione video tramite un unico endpoint OpenAI-like, /v1/video/generations. Sora non è ancora attivato nel catalogo; il modello attivo per la conversione da testo a video è Google Veo 3, che genera clip cinematografici con audio nativo. Gli esempi seguenti utilizzano veo-3: quando arriverà Sora, l'unica modifica sarà il campo model.

Guida rapida da testo a video

Una POST con la tua chiave Kunavo. La generazione può richiedere alcuni minuti, quindi la chiamata sincrona mantiene aperta la connessione finché il clip non è pronto:

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,  # die Generierung kann Minuten dauern
)
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 statica, 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". Esempi completi sono disponibili nella documentazione video.

Ciclo di vita dell'attività asincrona

In produzione, non mantenere aperta una connessione per 10 minuti. Invia un'attività a /v1/videos, ricevi immediatamente un'ID dell'attività e poi interroga GET /v1/videos/{id} finché non viene completata. Gli URL dei risultati sono permanenti.

# Produktion: Task einreichen, dann pollen — keine langlebige Verbindung.
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "my-task-uuid",   # innerhalb von ~24h retry-sicher
    },
    json={"model": "veo-3", "prompt": "...", "aspect_ratio": "16:9"},
    timeout=60,
).json()
# dann GET /v1/videos/{task["id"]} pollen, bis er fertig ist

La documentazione video tratta l'intero ciclo di polling, le chiavi di idempotenza e la consegna dei webhook.

Prezzi

Veo 3 viene addebitato per video (qui per clip di 8 secondi in 720p), circa 50–70% in meno rispetto al prezzo di listino di Google. Le risoluzioni superiori costano di più: la tabella completa delle fasce è disponibile nella pagina dei prezzi.

Suggerimenti per il prompting video

• Descrivi l’inquadratura, non solo il soggetto. Il movimento della camera (carrellata, panoramica, avvicinamento), l’aspetto dell’obiettivo, l’illuminazione e il ritmo contano più degli aggettivi.
• Imposta esplicitamente le proporzioni — 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 (da immagine a video) quando vuoi mantenere coerenti un determinato personaggio o prodotto.

Domande frequenti