Guida all'API Sora — generazione video AI utilizzabile subito (Veo 3.1)

Sora è il modello text-to-video di OpenAI e «API Sora» indica il modo di generare video programmaticamente, non un'app per consumatori. Attualmente su Kunavo il text-to-video viene eseguito con Google Veo 3 tramite un unico endpoint video OpenAI-style — il supporto a Sora è nella roadmap e, poiché l'endpoint non dipende dal modello, in futuro passare a Sora richiederà di cambiare una sola parola. Questa guida mostra il workflow con Veo 3 affinché tutti gli esempi siano eseguibili subito.

Che cos'è l'API Sora?

Sora (Sora 2 e Sora 2 Pro) trasforma prompt testuali o immagini statiche in brevi clip video e, con Sora 2, fornisce anche audio sincronizzato. In forma API, puoi inserire la generazione in una pipeline: clip di marketing, animazioni di prodotto, b-roll, anteprime di storyboard. I modelli video più recenti hanno tutti la stessa forma: invii prompt e parametri e ricevi un URL video ospitato.

Video attualmente disponibili su Kunavo: Veo 3

Kunavo offre la generazione video tramite un unico endpoint OpenAI-style /v1/video/generations. Sora non è ancora attivo nel catalogo e il modello text-to-video attualmente disponibile è Google Veo 3, che crea clip cinematografiche con audio nativo. Gli esempi seguenti usano veo-3 e, quando Sora verrà aggiunto, sarà sufficiente cambiare il campo model.

Avvio rapido text-to-video

Con una sola richiesta POST usando la tua chiave Kunavo. La generazione può richiedere alcuni minuti, quindi la 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": "빨간 종이학이 펼쳐지는 영화적인 돌리인, 부드러운 조명",
        "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 aggiungere movimento a un'immagine statica, invia image_url (un URL https o un file caricato su /v1/files) insieme al prompt. Per un movimento controllato, puoi inviare il primo e l'ultimo fotogramma con image_urls e image_mode: "frame". L'esempio completo è nella documentazione video.

Ciclo di vita dei lavori asincroni

In produzione, non mantenere una connessione aperta per 10 minuti. Invia il lavoro a /v1/videos, ricevi immediatamente un ID del lavoro e interroga GET /v1/videos/{id} finché non è completato. 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 tratta il ciclo completo di polling, le chiavi di idempotenza e la consegna tramite webhook.

Prezzi

Veo 3 viene addebitato per video (qui in base a una clip di 8 secondi a 720p) ed è circa 50–70% più economico del listino Google. Una risoluzione maggiore aumenta il costo: consulta la pagina dei prezzi per la tabella completa dei livelli.

Suggerimenti per i prompt video

• Descrivi l'inquadratura, non solo il soggetto. I movimenti della camera (carrellata, panoramica, avvicinamento), l'effetto dell'obiettivo, l'illuminazione e il ritmo contano più 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 (image-to-video). È utile quando devi mantenere coerenti un personaggio o un prodotto specifico.

Domande frequenti