Quickstart API Veo 3 dan Sora — teks-ke-video dan gambar-ke-video dalam lima menit

Veo 3 dan Sora menempatkan text-to-video pada standar kualitas yang sama seperti text-to-image delapan belas bulan lalu. Kendalanya: penyedia membatasi akses melalui daftar tunggu, pembatasan wilayah, dan alur penagihan khusus yang tidak terintegrasi dengan stack AI lainnya.

Di Kunavo, model text-to-video yang tersedia saat ini adalah Google Veo 3, melalui satu endpoint yang kompatibel dengan OpenAI — tanpa daftar tunggu, autentikasi kompatibel dengan OpenAI, ditagih per video, dan hasil disajikan dari URL permanen. Sora (sora-2) ada dalam roadmap: karena endpoint bersifat agnostik terhadap model, perpindahan nanti hanya memerlukan perubahan satu kata pada model. Panduan ini menjalankan pemanggilan Veo 3 pertama Anda dalam sekitar lima menit. Lihat panduan Sora API untuk gambaran lengkap.

Pengaturan

1. Daftar di kunavo.com/app/signup. Isi saldo mulai $10, bayar sesuai pemakaian — cukup untuk menjalankan setiap contoh dalam panduan ini beberapa kali, dan saldo tidak pernah kedaluwarsa.
2. Buat kunci di /app/keys. Kunci dimulai dengan sk-kn-.
3. Ekspor: export KUNAVO_API_KEY=sk-kn-....

Text-to-video dengan Veo 3

Veo 3 saat ini merupakan model text-to-video terbaik di pasar untuk bidikan sinematik — memahami bahasa kamera (dolly, push-in, rack focus), menghasilkan pencahayaan stabil antar-potongan, dan menangani gerakan 24fps dengan benar. Generasi memerlukan 30 detik hingga beberapa menit; respons HTTP bersifat sinkron, jadi tetapkan timeout klien yang panjang.

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 (dalam detik) menentukan durasi klip pada model dengan penagihan per detik: model-model Seedance dan model Wan 2.7. Model-model Veo mengabaikannya; setiap klip Veo berdurasi 8 detik dan ditagih per video.

Responsnya bergaya OpenAI: { data: [{ url: '...' }] }. URL tersebut permanen dan disajikan dari files.kunavo.com — unduh sekali ke penyimpanan Anda sendiri jika memerlukan hosting jangka panjang.

Gambar menjadi video

Penambatan dengan gambar biasanya menghasilkan kualitas produksi. Veo 3 mendukung dua mode gambar:

• image_mode: "frame" — satu gambar menjadi frame pertama; dua gambar menjadi frame pertama + terakhir. Default untuk image_url.
• image_mode: "reference" — hingga 3 referensi gaya untuk konsistensi karakter / pakaian tanpa memaksa frame.

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

Jika belum memiliki URL publik untuk gambar acuan, kirim byte-nya ke /v1/files dan Kunavo akan meng-host file tersebut di bawah 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 dan model lainnya

Bentuk endpoint yang sama berlaku untuk setiap model video dalam katalog — kirim slug model yang sesuai:

• veo-3 — sinematik, 1080p, mendukung image-to-video. Tersedia sekarang.
• seedance-2, seedance-2-5 — ByteDance, sangat kuat dalam gerakan karakter.

OpenAI Sora (sora-2) ada dalam roadmap — belum dapat dipanggil di Kunavo. Karena /v1/video/generations agnostik terhadap model, saat tersedia nanti satu-satunya perubahan pada pemanggilan di atas adalah field model; sampai saat itu Veo 3 adalah padanan aktif pada endpoint yang sama.

Lihat /models untuk daftar aktif dan harga masing-masing model.

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

Model harga

Model video ditagih per video atau per detik output, bukan per token: model Veo per video, dengan setiap klip berdurasi 8 detik, serta model Seedance dan Wan 2.7 per detik. Kunavo menerbitkan tarif setiap model di /pricing. Klip Veo 3 1080p berdurasi 8 detik berharga $0,42. Generasi yang gagal (4xx / 5xx) tidak pernah ditagih.

Daftar periksa produksi

• Tetapkan batas waktu HTTP 10 menit. Gateway melakukan pemeriksaan berkala ke layanan hulu hingga 540 detik dan mengembalikan 504 jika model masih bekerja setelah itu. Percobaan ulang adalah tugas baru, dan setiap tugas yang berhasil akan ditagih. Untuk tugas yang berlangsung sangat lama, kirim permintaan ke /v1/videos sebagai gantinya dan periksa secara berkala tugas yang dikembalikannya: dengan header Idempotency-Key, pengiriman kedua dengan kunci yang sama mengembalikan tugas itu alih-alih memulai tugas lain.
• Simpan URL hasil. Meskipun URL files.kunavo.com permanen, produk Anda sebaiknya menyimpan salinan sendiri di penyimpanan yang Anda kendalikan.
• Tangani 429 dengan backoff. Model video bergantung pada GPU; kontensi singkat adalah hal normal. Header retry-after dihormati jika tersedia.
• Cache berdasarkan hash prompt jika masuk akal. Mengirim prompt yang sama dua kali menghasilkan dua klip dan ditagih dua kali: gateway tidak memakai ulang hasil sebelumnya dan tidak mengirim seed ke model.

Pertanyaan: contact@kunavo.com. Tim di balik gateway membaca setiap email dan membalas dalam 24 jam.