Sora API 使用方法——立即可執行的 AI 影片生成（Veo 3.1／相容 OpenAI）

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 與分鏡預覽。其形式與近期的影片模型大致相同：傳送提示詞與參數，接收代管的影片 URL。

目前可在 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,  # 生成には数分かかることがあります
)
print(resp.json()["data"][0]["url"])

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

圖片轉影片

若要將靜態圖片製作成動畫，請在提示詞中一併傳送image_url（https URL，或上傳至/v1/files的檔案）。若要控制動作，可以透過image_urls與image_mode: "frame"傳送開始與結束影格。詳細範例請參閱影片文件。

非同步工作生命週期

在正式環境中，不要保持連線 10 分鐘。將工作提交至/v1/videos後會立即回傳工作 ID，接著輪詢GET /v1/videos/{id}直到完成。結果 URL 是永久的。

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

影片文件說明完整的輪詢迴圈、冪等性金鑰與 Webhook 傳遞。

費用

Veo 3 按影片計費（此處以每個 720p、8 秒片段計算），價格比 Google 官方定價約低50〜70%。解析度越高，成本也越高——完整的方案表請參閱價格頁面。

影片提示詞技巧

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

常見問題