Come usare l'API Sora — generazione video AI funzionante subito (Veo 3.1 / compatibile con OpenAI)

Sora è il modello OpenAI per la generazione di video da testo e “API Sora” indica un metodo per generare video programmaticamente, non tramite un'applicazione per consumatori. In Kunavo, la generazione da testo a video funziona attualmente con Google Veo 3 tramite un unico endpoint video in stile OpenAI — il supporto a Sora è previsto nella roadmap e l'endpoint è indipendente dal modello, quindi in seguito basterà modificare una parola per passare a Sora. Questa guida mostra il flusso di lavoro con Veo 3, così tutti gli esempi funzionano subito.

Che cos'è l'API Sora?

Sora (Sora 2 e Sora 2 Pro) trasforma un prompt testuale — o una singola immagine statica — in una breve clip video, con audio sincronizzato in Sora 2. In forma di API, puoi integrare la generazione nelle pipeline, ad esempio per video di marketing, animazioni di prodotti, b-roll e anteprime di storyboard. La forma è comune ai moderni modelli video: invii prompt e parametri e ricevi un URL video ospitato.

Video disponibili ora su Kunavo: Veo 3

Kunavo espone la generazione video tramite un unico endpoint in stile OpenAI /v1/video/generations. Sora non è ancora abilitato nel catalogo; il modello da testo a video attualmente disponibile è Google Veo 3, che genera clip cinematografiche con audio nativo. Gli esempi seguenti usano veo-3: quando arriverà Sora, dovrai modificare solo il campo model.

Avvio rapido da testo a video

Basta una richiesta POST con la tua chiave Kunavo. La generazione può richiedere alcuni minuti, quindi una chiamata sincrona mantiene la connessione aperta 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,  # 生成には数分かかることがあります
)
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 insieme al prompt (un URL https oppure un file caricato in /v1/files). Per controllare il movimento, puoi fornire il primo e l'ultimo fotogramma con image_urls e image_mode: "frame". Esempi dettagliati sono disponibili nella documentazione video.

Ciclo di vita delle attività asincrone

In produzione, non mantenere una connessione aperta per 10 minuti. Inserendo un'attività in /v1/videos ricevi subito un ID attività, quindi esegui il polling di GET /v1/videos/{id} finché non viene completata. L'URL del risultato è permanente.

# 本番: タスクを投入してからポーリング——長時間の接続を保持しません。
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "my-task-uuid",   # 約 24 時間はリトライしても安全
    },
    json={"model": "veo-3", "prompt": "...", "aspect_ratio": "16:9"},
    timeout=60,
).json()
# その後 GET /v1/videos/{task["id"]} を完了までポーリングします

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 si considera una clip di 8 secondi a 720p) ed è circa il 50–70% più economico dei prezzi ufficiali di Google. Il costo aumenta con la risoluzione: per la tabella completa dei livelli, consulta la pagina dei prezzi.

Consigli per i prompt video

• Descrivi l'inquadratura, non solo il soggetto. Movimento della fotocamera (carrellata, panoramica, avvicinamento), resa dell'obiettivo, illuminazione e ritmo sono più efficaci degli aggettivi.
• Specifica 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 fotogrammi di riferimento (da immagine a video): è utile per mantenere coerenti personaggi o prodotti specifici.

Domande frequenti