How to use the Sora API — AI video generation that works now (Veo 3.1 / OpenAI-compatible)

Sora is OpenAI's text-to-video model, and the “Sora API” is a way to generate videos programmatically rather than through a consumer application. On Kunavo, text-to-video generation currently runs on Google Veo 3 through a single OpenAI-style video endpoint — Sora support is on the roadmap, and because the endpoint is model-independent, moving to Sora later requires changing only one word. This guide demonstrates the workflow with Veo 3 so that every example works right now.

What is the Sora API?

Sora (Sora 2 and Sora 2 Pro) turns a text prompt — or a single still image — into a short video clip, with synchronized audio in Sora 2. In API form, you can integrate generation into a pipeline: marketing videos, product animations, b-roll, or storyboard previews. The shape is common across modern video models: send prompts and parameters, then receive a hosted video URL.

Video currently available on Kunavo: Veo 3

Kunavo exposes video generation through one OpenAI-style endpoint /v1/video/generations. Sora has not yet been enabled in the catalog; the text-to-video model currently available is Google Veo 3, which generates cinematic clips with native audio. The examples below use veo-3 — when Sora arrives, you will change only the model field.

Text-to-video quickstart

Make one POST request with your Kunavo key. Generation can take several minutes, so the synchronous call keeps the connection open until the clip is ready.

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 (seconds) sets the clip length on the models billed per second: the Seedance models and Wan 2.7. The Veo models ignore it; every Veo clip is 8 seconds, billed per video.

Image-to-video

To animate a still image, pass image_url (an https URL or a file uploaded to /v1/files) together with the prompt. To control the motion, you can pass the first and last frames with image_urls and image_mode: "frame". See the video documentation for a detailed example.

Asynchronous task lifecycle

In production, do not keep a connection open for 10 minutes. Submit the task to /v1/videos and you immediately receive a task ID; poll GET /v1/videos/{id} until completion. The result URL is permanent.

# 本番: タスクを投入してからポーリング——長時間の接続を保持しません。
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"]} を完了までポーリングします

Video documentation explains the complete polling loop, idempotency keys, and webhook delivery.

Pricing

Veo 3 is billed per video (here, per 8-second 720p clip) and is approximately 50–70% cheaper than Google's list price. Higher resolutions cost more — see the pricing page for the complete tier table.

Video prompt tips

• Describe the shot, not only the subject. Camera movement (dolly, pan, push-in), lens feel, lighting, and pacing matter more than adjectives.
• Specify the aspect ratio — 16:9 for landscape and 9:16 for portrait/social.
• Every Veo clip is 8 seconds long. Plan each shot to fit, and stitch multiple generations for longer sequences.
• Use reference frames (image-to-video) — useful when you need a specific character or product to remain consistent.

Frequently asked questions