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）。当需要保持特定角色或产品的一致性时非常有用。

常见问题