Démarrage rapide des API Veo 3 et Sora — texte vers vidéo et image vers vidéo en cinq minutes

Veo 3 et Sora placent le text-to-video au même niveau de qualité que le text-to-image il y a dix-huit mois. Le problème : les fournisseurs limitent l’accès par des listes d’attente, des restrictions régionales et des processus de facturation personnalisés qui s’intègrent mal au reste de votre stack IA.

Sur Kunavo, le modèle text-to-video actuellement disponible est Google Veo 3, fourni via un endpoint compatible OpenAI — sans liste d’attente, avec une authentification compatible OpenAI, facturé à la vidéo, et des résultats servis depuis une URL permanente. Sora (sora-2) est prévu sur la feuille de route : l’endpoint étant indépendant du modèle, le passage à Sora se fera plus tard par une modification d’un seul mot, model. Ce guide vous permet d’effectuer votre premier appel Veo 3 en environ cinq minutes. Consultez le guide de l’API Sora pour une vue complète.

Configuration

1. Inscrivez-vous sur kunavo.com/app/signup. Rechargez à partir de $10, avec une facturation à l’usage — assez pour exécuter plusieurs fois chaque exemple de ce guide ; votre solde n’expire jamais.
2. Créez une clé dans /app/keys. Elle commence par sk-kn-.
3. Exportez-la : export KUNAVO_API_KEY=sk-kn-....

Text-to-video avec Veo 3

Veo 3 est actuellement le meilleur modèle text-to-video du marché pour les plans cinématographiques : il comprend le langage de caméra (travelling, push-in, rack focus), produit un éclairage stable entre les plans et gère correctement les mouvements à 24 images/s. Les générations prennent de 30 secondes à quelques minutes ; la réponse HTTP est synchrone : définissez un délai d’expiration client suffisamment long.

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 (en secondes) définit la durée du clip pour les modèles facturés à la seconde : les modèles Seedance et le modèle Wan 2.7. Les modèles Veo l’ignorent ; chaque clip Veo dure 8 secondes et est facturé par vidéo.

La réponse suit le style OpenAI : { data: [{ url: '...' }] }. L’URL est permanente et servie depuis files.kunavo.com — téléchargez-la une fois dans votre propre stockage si vous avez besoin d’un hébergement à long terme.

Génération de vidéo à partir d’images

L’ancrage avec une image est généralement la meilleure façon d’obtenir des résultats de qualité production. Veo 3 prend en charge deux modes d’image :

• image_mode: "frame" — une seule image correspond à la première frame ; deux images correspondent à la première et à la dernière frame. Par défaut pour image_url.
• image_mode: "reference" — jusqu’à 3 références de style pour assurer la cohérence du personnage et de la tenue sans imposer de frames.

# 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"])

Si vous ne disposez pas déjà d’une URL publique pour votre image d’ancrage, envoyez les octets à /v1/files et Kunavo hébergera le fichier pour vous sous 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 et les autres modèles

La même structure d’endpoint fonctionne pour chaque modèle vidéo du catalogue : transmettez le slug du modèle concerné :

• veo-3 — cinématique, 1080p, prend en charge image-to-video. Disponible actuellement.
• seedance-2, seedance-2-5 — ByteDance, très performant pour les mouvements des personnages.

OpenAI Sora (sora-2) est prévu sur la feuille de route — il n’est pas encore appelable sur Kunavo. Comme /v1/video/generations est indépendant du modèle, le jour où il sera disponible, le seul changement à apporter aux appels ci-dessus concernera le champ model ; d’ici là, Veo 3 est l’équivalent disponible sur le même endpoint.

Consultez /models pour obtenir la liste en temps réel et le prix de chaque modèle.

Depuis 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);

Modèle tarifaire

Les modèles vidéo sont facturés à la vidéo ou à la seconde de sortie, et non au token : les modèles Veo à la vidéo, chaque clip durant 8 secondes, et les modèles Seedance et Wan 2.7 à la seconde. Kunavo publie le tarif sur /pricing pour chaque modèle. Un clip Veo 3 de 8 secondes en 1080p coûte $0.42. Les générations échouées (4xx / 5xx) ne sont jamais facturées.

Checklist de production

• Définissez un délai d’expiration HTTP de 10 minutes. La passerelle interroge le service en amont jusqu’à 540 s et renvoie 504 si le modèle travaille encore au-delà. Pour les tâches très longues, réessayez — les générations sont idempotentes pour un prompt donné.
• Conservez l’URL du résultat. Même si les URL files.kunavo.com sont permanentes, votre produit doit conserver sa propre copie dans le stockage que vous contrôlez.
• Gérez les erreurs 429 avec un backoff. Les modèles vidéo sont limités par les ressources GPU ; une brève contention est normale. L’en-tête retry-after est respecté lorsqu’il est présent.
• Mettez en cache par hash du prompt si cela est raisonnable. Envoyer deux fois le même prompt génère deux clips et est facturé deux fois : la passerelle ne réutilise aucun résultat antérieur et n’envoie aucun seed au modèle.

Questions : contact@kunavo.com. L’équipe derrière la passerelle lit chaque e-mail et répond sous 24 heures.