Sora API 指南 — 立即使用 AI 影片生成（Veo 3.1）

Sora 是 OpenAI 的 text-to-video 模型，而「Sora API」是以程式設計產生影片的方法，不是消費者應用程式。目前 Kunavo 的 text-to-video 透過單一 OpenAI 風格的影片端點，使用 Google Veo 3 執行——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 尚未在目錄中啟用，目前可用的 text-to-video 模型是 Google Veo 3，可搭配原生音訊產生電影感片段。以下範例使用 veo-3——Sora 加入後，只需變更 model 欄位。

Text-to-video 快速入門

使用 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": "빨간 종이학이 펼쳐지는 영화적인 돌리인, 부드러운 조명",
        "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 秒。請依這個長度規劃每個鏡頭；較長的序列可將多次生成串接起來。
• 使用參考影格（image-to-video）。當你需要讓特定角色或產品保持一致時，這很有用。

常見問題