Sora API——通过 OpenAI 兼容流程实现文生视频

Sora 是 OpenAI 的文本到视频模型，“Sora API”指的是团队以编程方式生成视频，而不是通过消费端应用操作。目前在 Kunavo 中，文本到视频生成通过 Google Veo 3 和一个 OpenAI 风格的视频端点运行——Sora 访问已列入路线图；由于端点与模型无关，今后迁移到 Sora 只需更改一个单词。本指南展示 Veo 3 工作流，因此所有示例现在都可以运行。

什么是 Sora API？

Sora（Sora 2 和 Sora 2 Pro）可将文本 prompt 或静态图像转换为短视频片段，并支持 Sora 2 中的同步音频。API 方式允许您将生成编排到流水线中：营销镜头、产品动画、补充镜头、分镜预览。现代视频模型使用相同的格式：发送 prompt 和参数，然后接收托管视频的 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": "um dolly-in cinematográfico em um origami de garça vermelha se abrindo, luz suave",
        "aspect_ratio": "16:9",
    },
    timeout=600,  # a geração pode levar minutos
)
print(resp.json()["data"][0]["url"])

duration（秒）用于在按秒计费的模型（Seedance 系列模型和 Wan 2.7）上设置片段时长。Veo 模型会忽略它；每个 Veo 片段都是 8 秒，按视频计费。

图像到视频

要为静态图像添加动画，请将 image_url（https URL 或上传到 /v1/files的文件）与 prompt 一起传递。要控制运动，您可以使用 image_urls 和 image_mode: "frame"传递首帧和末帧。完整示例请参阅 视频文档。

异步任务生命周期

在生产环境中，不要保持一个连接 10 分钟。将任务发送到 /v1/videos，立即接收任务 id，然后轮询 GET /v1/videos/{id}直到完成。结果 URL 永久有效。

# Produção: envie uma tarefa e faça polling — sem conexão de longa duração.
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "meu-uuid-de-tarefa",   # seguro para retry em ~24h
    },
    json={"model": "veo-3", "prompt": "...", "aspect_ratio": "16:9"},
    timeout=60,
).json()
# depois faça polling em GET /v1/videos/{task["id"]} até concluir

视频文档介绍完整的轮询循环、幂等键和 webhook 交付。

价格

Veo 3 按视频计费（此处显示的是 720p、8 秒片段），价格约比 Google 目录价低 50–70%。更高分辨率的价格更高——完整档位表请参阅 价格页面。

视频 prompt 技巧

• 描述镜头，而不只是主体。摄像机运动（dolly、pan、push-in）、镜头质感、光线和节奏比形容词更重要。
• 明确指定宽高比——横屏使用 16:9，竖屏/社交媒体使用 9:16。
• 每个 Veo 片段都是 8 秒。请按这个时长设计每个镜头；如需更长的序列，可将多个生成结果拼接起来。
• 需要保持特定角色或产品一致时，请使用 参考帧（图像到视频）。

常见问题