跳转到主要内容
视频使用异步任务:创建后保存网关返回的 id,用同一用户/项目范围内的凭据查询,完成后下载。不要使用供应商后台里的私有任务 ID。 截至 2026-10-14,OpenAI 官方说明已注明 Sora 2 / Videos API 于 2026-09-24 停用。本页说明项目仍提供的兼容接口;使用前必须确认部署中有实际可用、支持 openai_video 的渠道或插件。代码中存在 Sora 插件或 SDK 方法,不代表 OpenAI 上游仍可调用。

任务生命周期

progress 只是提示,不以 100 代替 status: completed。查询可能返回后台轮询保存的快照,频繁查询不保证更快更新。

Python:创建、续查和下载

按 Python SDK配置环境,API_MODEL 必须是管理员确认可用的视频模型。保存为 videos.py。固定版本 SDK 仍提供兼容方法,但可能显示 Sora 弃用提示;它只用于访问你配置的网关,不能恢复已停用的上游。 先运行 python videos.py create,保存输出的 id。下方的 task_example 必须替换为该 ID;每次 create 都是新任务,不要把创建命令放入轮询循环。
wait 默认最多查询 60 次,间隔 5 秒,每次请求还有 120 秒超时,因此不承诺五分钟内结束。可用 --max-polls 设置 1–120 次。达到上限、退出或网络错误都不会取消服务端任务,可以稍后用相同 ID 继续查询。

图生视频与 Remix

创建接口支持 JSON 或 multipart,但 input_reference、时长和尺寸取决于执行插件。上传参考图时用 multipart 的 input_reference 文件字段;确认模型支持的编码、尺寸和文件大小。示例可执行 python videos.py create --image /path/to/reference.png,会将图片上传到配置的网关及其上游。只提供 prompt 是文生视频,输入图片不是上传待转写的视频。 Remix使用已有任务:python videos.py remix task_example。仅在原任务所属渠道和插件支持时使用;网关会关联原任务并固定到原渠道。返回的是新任务的提交摘要,保存新 id 后继续查询。不要假定所有视频插件都有 Remix 能力。

下载与恢复

下载内容返回二进制;HEAD仅检查响应头。使用网关内容端点并保留 Bearer 认证,不向供应商返回的任意 URL 发送网关密钥。不要把长期 API Key 放进浏览器 <video> 的 URL。 本例只保存 MP4 / octet-stream,单次上限 256 MiB,且不覆盖 video.mp4;这些是示例约束。失败后可能留下部分文件,删除该部分文件或换输出名后再下载。完整下载不代表已进行媒体解码校验。Range、缓存头、文件大小和其他内容类型依赖内容源,不保证每个插件一致。任务完成也不代表内容永久保留;410 表示内容已不可用,502 可能是内容代理失败。

兼容边界

旧的 /v1/video/generations 接口与 /v1/videos 不具有相同响应结构;不要混用解析器。本指南统一使用 /v1/videos。不承诺 OpenAI SDK 中的列表、删除、扩展、角色、独立编辑端点在本项目可用,也不承诺 webhook 或取消任务接口。 提交超时且没有收到 ID 时,先用请求日志确认是否已创建;重复 POST 可能生成多份内容。查询和下载失败时保留 ID,按错误处理恢复。 Read in English 相关指南:视频理解