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

查询指定任务的状态和进度。任务状态包括:

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 服务器内部错误

常见问题

Q1
视频生成需要多长时间?

视频生成时间取决于模型类型、视频长度和当前服务器负载。通常需要几分钟到十几分钟不等。建议通过轮询任务状态来跟踪进度。

Q2
如何选择合适的模型?

根据您的需求选择:

  • 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 系列
Q3
为什么某些模型的 seconds 参数被忽略了?

某些模型(如 sora_video2 系列和 veo_3_1 系列)有固定的时长限制。系统会自动调整 seconds 参数以匹配模型的限制。

Q4
生成的视频会保存多久?

生成的视频会在 expires_at 时间后过期。请在过期前下载视频。具体保存时间取决于您的套餐类型。

Q5
支持哪些图片格式作为 input_reference?

支持常见的图片格式,包括 JPG、JPEG、PNG 等。建议使用高质量的图片以获得更好的视频生成效果。

Q6
如何提高视频生成质量?

以下建议可以帮助提高视频质量:

  • 使用详细、具体的提示词
  • 选择合适的模型和尺寸
  • 对于图像到视频,使用高质量的参考图片
  • 根据场景选择合适的模型(横向/纵向)
Q7
任务失败后可以重试吗?

可以。如果任务失败,您可以重新提交相同的请求。建议检查错误信息以了解失败原因,并相应调整参数后重试。

相关链接