Avvio rapido alle API Veo 3 e Sora — da testo a video e da immagine a video in cinque minuti

Veo 3 e Sora portano il text-to-video allo stesso livello qualitativo raggiunto dal text-to-image diciotto mesi fa. Il problema è che i provider limitano l’accesso tramite liste d’attesa, restrizioni regionali e flussi di fatturazione personalizzati che non si integrano bene con il resto del tuo stack AI.

Su Kunavo, oggi il modello text-to-video disponibile è Google Veo 3, offerto tramite un unico endpoint compatibile con OpenAI: nessuna lista d’attesa, autenticazione compatibile con OpenAI, fatturazione per video e risultati disponibili da un URL permanente. Sora (sora-2) è nella roadmap: poiché l’endpoint è indipendente dal modello, in futuro il passaggio richiederà una modifica di una sola parola, model. Questa guida ti permette di eseguire la prima chiamata a Veo 3 in circa cinque minuti. Per il quadro completo, consulta la guida all’API di Sora.

Configurazione

1. Registrati su kunavo.com/app/signup. Ricarica da $10 con fatturazione a consumo: è sufficiente per eseguire più volte ogni esempio di questa guida e il saldo non scade mai.
2. Crea una chiave in /app/keys. Inizia con sk-kn-.
3. Esportala: export KUNAVO_API_KEY=sk-kn-....

Text-to-video con Veo 3

Veo 3 è attualmente il miglior modello text-to-video sul mercato per le inquadrature cinematografiche: comprende il linguaggio della camera (dolly, push-in, rack focus), mantiene un’illuminazione stabile tra i tagli e gestisce correttamente il movimento a 24 fps. Le generazioni richiedono da 30 secondi a qualche minuto; la risposta HTTP è sincrona, quindi imposta un timeout client lungo.

import requests, os, time

KEY = os.environ["KUNAVO_API_KEY"]

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "model": "veo-3",
        "prompt": "A drone shot pulling back from a quiet mountain lake at dawn, mist rising off the water. Cinematic, 24fps, soft golden light.",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
    },
    timeout=600,   # generations take 30s to several minutes
)
resp.raise_for_status()
data = resp.json()
print(data["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.

La risposta segue lo stile OpenAI: { data: [{ url: '...' }] }. L’URL è permanente ed è offerto da files.kunavo.com; se ti serve un hosting a lungo termine, scaricalo una volta nel tuo storage.

Da immagine a video

Ancorare il video a un’immagine è di solito il modo migliore per ottenere risultati di qualità produttiva. Veo 3 supporta due modalità immagine:

• image_mode: "frame": una singola immagine è il primo fotogramma; due immagini sono il primo e l’ultimo fotogramma. Predefinito per image_url.
• image_mode: "reference": fino a 3 riferimenti di stile per mantenere coerenti personaggi e abbigliamento senza imporre i fotogrammi.

# image-to-video: pass an image_url to anchor the first frame.
resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "model": "veo-3",
        "prompt": "She smiles, then walks out of frame to the left",
        "image_url": "https://files.kunavo.com/<your-upload>.jpg",
        "image_mode": "frame",      # one image => first frame
        "aspect_ratio": "9:16",     # vertical, mobile-native
    },
    timeout=600,
)
print(resp.json()["data"][0]["url"])

Se non disponi già di un URL pubblico per l’immagine di ancoraggio, invia i byte a /v1/files e Kunavo ospiterà il file per te in files.kunavo.com:

# If you don't have a public URL, upload bytes; Kunavo hosts the file.
with open("anchor.jpg", "rb") as f:
    up = requests.post(
        "https://api.kunavo.com/v1/files",
        headers={"Authorization": f"Bearer {KEY}"},
        files={"file": f},
    )
image_url = up.json()["url"]   # permanent files.kunavo.com URL

Sora e altri modelli

La stessa struttura dell’endpoint funziona per ogni modello video del catalogo: passa lo slug del modello pertinente:

• veo-3: cinematografico, 1080p, supporta image-to-video. Disponibile ora.
• seedance-2, seedance-2-5: ByteDance, molto efficace nel movimento dei personaggi.

OpenAI Sora (sora-2) è nella roadmap e non è ancora chiamabile su Kunavo. Poiché /v1/video/generations è indipendente dal modello, quando arriverà l’unica modifica alle chiamate sopra sarà il campo model; fino ad allora Veo 3 è l’equivalente disponibile sullo stesso endpoint.

Consulta /models per l’elenco aggiornato e il prezzo di ciascun modello.

Da Node / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

// /v1/video/generations isn't in OpenAI's SDK shape, but the same auth
// header works — call it with fetch:
const resp = await fetch(
  "https://api.kunavo.com/v1/video/generations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.KUNAVO_API_KEY}`,
    },
    body: JSON.stringify({
      model: "veo-3",
      prompt: "A red origami crane unfolding into a paper plane and flying away through a window",
      resolution: "1080p",
    }),
  },
);
const { data } = await resp.json();
console.log(data[0].url);

Modello di prezzo

I modelli video vengono fatturati per video o al secondo di output, non per token: i modelli Veo per video, con ogni clip di 8 secondi, e i modelli Seedance e Wan 2.7 al secondo. Kunavo pubblica la tariffa di ogni modello in /pricing. Una clip da 8 secondi di Veo 3 a 1080p costa $0,42. Le generazioni fallite (4xx / 5xx) non vengono mai addebitate.

Checklist per la produzione

• Imposta un timeout HTTP di 10 minuti. Il gateway interroga il servizio a monte fino a 540 secondi e restituisce 504 se il modello sta ancora lavorando oltre quel limite. Un nuovo tentativo è una nuova attività, e ogni attività completata con successo viene addebitata. Per le attività molto lunghe, invia invece la richiesta a /v1/videos e interroga l’attività che ti restituisce: con un’intestazione Idempotency-Key, un secondo invio con la stessa chiave restituisce quell’attività invece di avviarne un’altra.
• Salva l’URL del risultato. Anche se gli URL files.kunavo.com sono permanenti, il tuo prodotto dovrebbe conservarne una copia nel proprio storage sotto il tuo controllo.
• Gestisci i 429 con il backoff. I modelli video sono vincolati dalle GPU; brevi periodi di contesa sono normali. Se presente, viene rispettato l’header retry-after.
• Memorizza nella cache usando l’hash del prompt quando è ragionevole. Inviare due volte lo stesso prompt genera due clip e viene addebitato due volte: il gateway non riutilizza un risultato precedente e non invia alcun seed al modello.

Domande: contact@kunavo.com. Il team che gestisce il gateway legge ogni email e risponde entro 24 ore.