Sora API——在類 OpenAI Endpoint 產生 AI 影片（目前使用 Veo 3.1）

Sora 是 OpenAI 的文字轉影片模型，而「Sora API」是讓團隊以程式方式生成影片、而非透過消費者應用程式操作的方式。在 Kunavo，目前文字轉影片透過 Google Veo 3，使用 OpenAI 相容的影片端點——Sora 存取權已列入產品路線圖，由於端點與模型無關，日後切換至 Sora 只需修改一個字。本指南使用 Veo 3 示範工作流程，因此每個範例都能立即執行。

什麼是 Sora API？

Sora（Sora 2 與 Sora 2 Pro）可將文字提示或靜態影像轉換為短片；Sora 2 也支援同步音訊。API 形式讓您能將生成流程編寫進管線：行銷鏡頭、產品動畫、B-roll、分鏡預覽。現代影片模型的介面形式大致相同：傳送提示與參數，取得託管影片網址。

Kunavo 目前的影片功能：Veo 3

Kunavo 透過單一 OpenAI 相容端點 /v1/video/generations 提供影片生成。Sora 尚未在目錄中啟用；目前啟用的文字轉影片模型是 Google Veo 3，可生成具備原生音訊的電影感片段。以下範例使用 veo-3——Sora 上線後，唯一需要變更的是 model 欄位。

文字轉影片快速入門

使用您的 Kunavo 金鑰發出 POST 請求。生成可能需要幾分鐘，因此同步呼叫會保持連線，直到片段完成：

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,  # die Generierung kann Minuten dauern
)
print(resp.json()["data"][0]["url"])

duration（秒數）用來在按秒計費的模型（Seedance 系列模型和 Wan 2.7）上設定片段長度。Veo 模型會忽略它；每個 Veo 片段都是 8 秒，按影片計費。

圖片轉影片

若要讓靜態影像動起來，請將 image_url（https 網址，或上傳至 /v1/files 的檔案）與提示一併傳送。若要控制動態，可以使用 image_urls 與 image_mode: "frame" 傳送起始影格和結束影格。完整範例請參閱影片文件。

非同步工作生命週期

在正式環境中，不應保持 10 分鐘的連線。將工作提交至 /v1/videos，立即取得工作 ID，然後輪詢 GET /v1/videos/{id} 直到工作完成。結果網址永久有效。

# Produktion: Task einreichen, dann pollen — keine langlebige Verbindung.
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "my-task-uuid",   # innerhalb von ~24h retry-sicher
    },
    json={"model": "veo-3", "prompt": "...", "aspect_ratio": "16:9"},
    timeout=60,
).json()
# dann GET /v1/videos/{task["id"]} pollen, bis er fertig ist

影片文件 涵蓋完整的輪詢迴圈、Idempotency-Key 與 Webhook 傳遞。

價格

Veo 3 按影片計費（此處以每個 720p、8 秒片段計算），價格約比 Google 定價低 50–70%。更高解析度的費用較高——完整級距表請參閱定價頁面。

影片提示技巧

• 描述場景，而不只是主體。 鏡頭運動（推軌、搖攝、推近）、鏡頭質感、照明與節奏比形容詞更重要。
• 明確指定寬高比——16:9 用於橫向格式，9:16 用於直向格式／社群媒體。
• 每個 Veo 片段都是 8 秒。請依這個長度規劃每個鏡頭；較長的序列可將多次生成串接起來。
• 若要讓特定角色或產品保持一致，請使用參考影格（圖片轉影片）。

常見問題