Sora API 文档
使用 OpenAI 兼容的 API 接口生成高质量视频内容
概述
Sora API 提供了强大的视频生成能力,支持文本到视频(Text-to-Video)和图像到视频(Image-to-Video)的转换。通过简单的 API 调用,您可以创建高质量的视频内容。
重要提示:Sora API 使用异步任务模式。提交任务后会立即返回任务 ID,您需要定期查询任务状态,直到任务完成。
快速开始
使用 curl 快速生成一个视频:
curl https://codeyy.top/v1/videos \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "model=sora_video2" \ -F "prompt=A calico cat playing a piano on stage"
响应示例:
{
"id": "task_abc123",
"object": "video",
"model": "sora_video2",
"status": "queued",
"progress": 0,
"created_at": 1704067200
}
认证
所有 API 请求都需要在请求头中包含您的 API 密钥:
Authorization: Bearer YOUR_API_KEY
您可以在 codeyy.top 控制台的 API 管理页面生成 API 密钥。
API 端点
1. 提交视频生成任务
POST /v1/videos
提交一个新的视频生成任务。支持文本到视频和图像到视频两种模式。
2. 查询任务状态
GET /v1/videos/:task_id
查询指定任务的状态和进度。任务状态包括:
queued- 任务已排队,等待处理pending- 任务待处理processing/in_progress- 任务正在处理中completed- 任务已完成failed- 任务失败cancelled- 任务已取消
3. 获取视频内容
GET /v1/videos/:task_id/content
当任务状态为 completed 时,可以通过此端点获取生成的视频文件。
支持的模型
codeyy.top 支持以下 Sora 模型:
Sora Video2 系列 (推荐)
推荐使用:Sora Video2 系列是当前推荐的模型,提供更好的视频生成质量和稳定性。
| 模型名称 | 描述 | 支持尺寸 | 时长限制 |
|---|---|---|---|
sora_video2 |
标准 Video2 模型 | 720x1280, 1280x720 | 固定 10 秒 |
sora_video2-15s |
15 秒版本 Video2 模型 | 720x1280, 1280x720 | 固定 15 秒 |
sora_video2-landscape |
横向 Video2 模型 | 720x1280, 1280x720 | 固定 10 秒 |
sora_video2-landscape-15s |
横向 15 秒版本 Video2 模型 | 720x1280, 1280x720 | 固定 15 秒 |
sora_video2-portrait |
纵向 Video2 模型 | 720x1280, 1280x720 | 固定 10 秒 |
sora_video2-portrait-15s |
纵向 15 秒版本 Video2 模型 | 720x1280, 1280x720 | 固定 15 秒 |
Sora 2 系列 (不推荐)
不推荐使用:Sora 2 系列模型已不推荐使用,建议使用 Sora Video2 系列模型以获得更好的效果。
| 模型名称 | 描述 | 支持尺寸 | 时长限制 |
|---|---|---|---|
sora-2 |
标准 Sora 2 模型(不推荐) | 720x1280, 1280x720 | 可配置(默认 10 秒) |
sora-2-pro |
增强版 Sora 2 Pro 模型(不推荐) | 720x1280, 1280x720, 1792x1024, 1024x1792 | 可配置(默认 10 秒) |
Veo 3.1 系列
| 模型名称 | 描述 | 支持尺寸 | 时长限制 |
|---|---|---|---|
veo_3_1 |
标准 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-fast |
快速版 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-fl |
FL 版本 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-landscape |
横向 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-landscape-fast |
横向快速版 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-landscape-fl |
横向 FL 版本 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-portrait |
纵向 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-portrait-fast |
纵向快速版 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
veo_3_1-portrait-fl |
纵向 FL 版本 Veo 3.1 模型 | 720x1280, 1280x720 | 固定 8 秒 |
请求参数
提交任务(POST /v1/videos)
支持两种请求格式:multipart/form-data(用于文件上传)和 application/json。
必需参数
| 参数名 | 类型 | 说明 |
|---|---|---|
model |
string | 要使用的模型名称(推荐使用 "sora_video2" 系列,如 "sora_video2", "sora_video2-15s" 等) |
prompt |
string | 文本提示词,描述要生成的视频内容 |
可选参数
| 参数名 | 类型 | 说明 |
|---|---|---|
input_reference |
file | 参考图片文件(用于图像到视频模式)。支持常见图片格式(JPG, PNG 等) |
seconds |
integer | 视频时长(秒)。注意:某些模型有固定的时长限制,此参数可能被忽略 |
size |
string | 视频尺寸,格式为 "宽度x高度"(如 "720x1280", "1280x720")。默认值取决于模型 |
character_url |
string | (Sora Video2 专用)角色视频链接 |
character_timestamps |
string | (Sora Video2 专用)角色时间戳范围 |
watermark |
string | (Sora Video2 专用)水印标识 |
重要提示:
sora_video2系列模型的时长是固定的(10 秒或 15 秒),seconds参数会被自动调整veo_3_1系列模型固定为 8 秒- 不同模型支持的尺寸不同,请参考模型列表中的说明
响应格式
提交任务响应
提交任务后,API 会立即返回任务信息:
{
"id": "task_abc123",
"object": "video",
"model": "sora_video2",
"status": "queued",
"progress": 0,
"created_at": 1704067200
}
查询任务响应
查询任务状态时,返回完整的任务信息:
{
"id": "task_abc123",
"object": "video",
"model": "sora_video2",
"status": "completed",
"progress": 100,
"created_at": 1704067200,
"completed_at": 1704067500,
"expires_at": 1704153600,
"seconds": "10",
"size": "720x1280"
}
响应字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
id |
string | 任务唯一标识符 |
object |
string | 对象类型,固定为 "video" |
model |
string | 使用的模型名称 |
status |
string | 任务状态:queued, pending, processing, in_progress, completed, failed, cancelled |
progress |
integer | 任务进度(0-100) |
created_at |
integer | 任务创建时间(Unix 时间戳) |
completed_at |
integer | 任务完成时间(Unix 时间戳,仅当 status 为 completed 时存在) |
expires_at |
integer | 视频过期时间(Unix 时间戳,仅当 status 为 completed 时存在) |
seconds |
string | 视频时长(秒,仅当 status 为 completed 时存在) |
size |
string | 视频尺寸(仅当 status 为 completed 时存在) |
remixed_from_video_id |
string | 如果是从其他视频混音生成,此字段包含源视频 ID |
error |
object | 错误信息(仅当 status 为 failed 时存在) |
错误响应
当请求失败时,API 会返回错误信息:
{
"id": "task_abc123",
"status": "failed",
"error": {
"message": "Invalid model specified",
"code": "invalid_model"
}
}
代码示例
使用 curl 提交任务
curl https://codeyy.top/v1/videos \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "model=sora_video2" \ -F "prompt=A beautiful sunset over the ocean" \ -F "size=1280x720"
使用 curl 提交图像到视频任务
curl https://codeyy.top/v1/videos \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "model=sora_video2" \ -F "prompt=Make this image come to life" \ -F "input_reference=@image.jpg"
使用 curl 查询任务状态
curl https://codeyy.top/v1/videos/task_abc123 \ -H "Authorization: Bearer YOUR_API_KEY"
使用 curl 获取视频内容
curl https://codeyy.top/v1/videos/task_abc123/content \ -H "Authorization: Bearer YOUR_API_KEY" \ -o video.mp4
Python 示例
import requests
# 提交视频生成任务
def create_video(prompt, model="sora_video2", size="1280x720"):
url = "https://codeyy.top/v1/videos"
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
data = {
"model": model,
"prompt": prompt,
"size": size
}
response = requests.post(url, headers=headers, data=data)
return response.json()
# 查询任务状态
def get_task_status(task_id):
url = f"https://codeyy.top/v1/videos/{task_id}"
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
return response.json()
# 使用示例
task = create_video("A cat playing piano")
print(f"Task ID: {task['id']}")
# 轮询任务状态
import time
while True:
status = get_task_status(task['id'])
print(f"Status: {status['status']}, Progress: {status['progress']}%")
if status['status'] == 'completed':
print(f"Video ready! Download from: /v1/videos/{task['id']}/content")
break
elif status['status'] == 'failed':
print(f"Task failed: {status.get('error', {}).get('message', 'Unknown error')}")
break
time.sleep(5) # 等待 5 秒后再次查询
JavaScript/Node.js 示例
const axios = require('axios');
// 提交视频生成任务
async function createVideo(prompt, model = 'sora_video2', size = '1280x720') {
const response = await axios.post(
'https://codeyy.top/v1/videos',
{
model: model,
prompt: prompt,
size: size
},
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
return response.data;
}
// 查询任务状态
async function getTaskStatus(taskId) {
const response = await axios.get(
`https://codeyy.top/v1/videos/${taskId}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
return response.data;
}
// 使用示例
(async () => {
const task = await createVideo('A cat playing piano');
console.log(`Task ID: ${task.id}`);
// 轮询任务状态
const checkStatus = setInterval(async () => {
const status = await getTaskStatus(task.id);
console.log(`Status: ${status.status}, Progress: ${status.progress}%`);
if (status.status === 'completed') {
console.log(`Video ready! Download from: /v1/videos/${task.id}/content`);
clearInterval(checkStatus);
} else if (status.status === 'failed') {
console.log(`Task failed: ${status.error?.message || 'Unknown error'}`);
clearInterval(checkStatus);
}
}, 5000); // 每 5 秒查询一次
})();
错误处理
API 可能返回以下错误:
| 错误代码 | HTTP 状态码 | 说明 |
|---|---|---|
missing_prompt |
400 | 缺少必需的 prompt 参数 |
missing_model |
400 | 缺少必需的 model 参数 |
invalid_model |
400 | 指定的模型不存在或不可用 |
invalid_size |
400 | 指定的尺寸不被该模型支持 |
invalid_multipart_form |
400 | multipart/form-data 格式错误 |
unauthorized |
401 | API 密钥无效或缺失 |
insufficient_quota |
403 | 配额不足 |
rate_limit_exceeded |
429 | 请求频率超过限制 |
internal_error |
500 | 服务器内部错误 |
常见问题
视频生成时间取决于模型类型、视频长度和当前服务器负载。通常需要几分钟到十几分钟不等。建议通过轮询任务状态来跟踪进度。
根据您的需求选择:
- sora_video2 系列(推荐):适合大多数场景,提供更好的视频质量和稳定性,支持 10 秒或 15 秒时长
- sora_video2-15s:需要 15 秒视频时使用
- sora_video2-landscape / sora_video2-portrait:需要特定方向(横向/纵向)时使用
- veo_3_1 系列:需要 8 秒视频时使用
- sora-2 / sora-2-pro(不推荐):已不推荐使用,建议迁移到 sora_video2 系列
某些模型(如 sora_video2 系列和 veo_3_1 系列)有固定的时长限制。系统会自动调整 seconds 参数以匹配模型的限制。
生成的视频会在 expires_at 时间后过期。请在过期前下载视频。具体保存时间取决于您的套餐类型。
支持常见的图片格式,包括 JPG、JPEG、PNG 等。建议使用高质量的图片以获得更好的视频生成效果。
以下建议可以帮助提高视频质量:
- 使用详细、具体的提示词
- 选择合适的模型和尺寸
- 对于图像到视频,使用高质量的参考图片
- 根据场景选择合适的模型(横向/纵向)
可以。如果任务失败,您可以重新提交相同的请求。建议检查错误信息以了解失败原因,并相应调整参数后重试。
相关链接
- 官方文档:https://docs.codeyy.top/
- API 参考:OpenAI Videos API