Sora-2 视频生成 API 使用指南：创建异步视频任务

概述

Sora-2 是一个先进的视频生成平台，提供基于 AI 的视频创建服务。本文档详细介绍了如何使用 Sora-2 的异步请求接口创建视频生成任务。

API 端点

创建视频任务

• 请求方法: POST

• 端点路径 : n.lconai.com/v1/videos

• 描述: 提交一个视频生成任务，系统将异步处理并返回任务结果

认证方式

所有 API 请求都需要通过 Bearer Token 进行身份验证：

Authorization: Bearer <your_token_here>

将上述格式的 Authorization 头部添加到所有请求中，其中 <your_token_here> 替换为您的实际访问令牌。

请求参数

Header 参数

参数名	类型	必需	描述	示例
Content-Type	string	可选	内容类型，默认为 multipart/form-data	multipart/form-data
Authorization	string	必需	认证令牌	Bearer ********************

Body 参数 (multipart/form-data)

必需参数

1. model (enum)

   • 描述: 选择使用的模型版本
   • 枚举值 :
     • sora-2: 标准版模型
     • sora-2-pro: 高级版模型
   • 示例: sora-2

2. prompt (string)

   • 描述: 视频生成提示词，描述您想要生成的视频内容
   • 示例 : 画面动起来

可选参数

1. seconds (string)

   • 描述: 视频时长（秒）
   • 示例 : 15

2. input_reference (file)

   • 描述: 参考图像文件路径，用于引导视频生成
   • 示例 : file:///Users/xiangsx/Downloads/RHTtTcBrlY5wGxop9ux8DqRckyIKxd.png

3. size (enum)

   • 描述: 视频分辨率尺寸。注意：宽度大于高度为横屏，宽度小于高度为竖屏
   • 枚举值 :
     • 1024x1792: 高清竖屏（仅 sora-2-pro 可用）
     • 1792x1024: 高清横屏（仅 sora-2-pro 可用）
     • 720x1280: 标清竖屏
     • 1280x720: 标清横屏
   • 示例 : 1280x720

4. watermark (boolean)

   • 描述: 是否添加水印。不传递此参数时默认不添加水印
   • 示例 : false

5. private (boolean)

   • 描述 : 是否将视频设为私有。设置为 true 时，视频不会公开发布，且无法进行二次编辑（remix）
   • 默认值 : false
   • 示例 : false

6. character_url (string)

   • 描述 : 创建角色所需的视频链接。重要：视频中不能出现真人，否则会失败
   • 注意 : 此参数需要与 character_timestamps 配合使用

7. character_timestamps (string)

   • 描述 : 角色在视频中出现的秒数范围，格式为 {start},{end}
   • 限制 : end - start 的范围必须在 1～3 秒之间
   • 示例 : 1.5,3.5

响应格式

成功响应 (HTTP 200)

• Content-Type : application/json
• 格式: JSON 对象
• 说明: 成功创建任务后，将返回一个 JSON 对象，通常包含任务 ID 和其他相关信息

代码示例

Python 请求示例

import http.client
import mimetypes
from codecs import encode

conn = http.client.HTTPSConnection("n.lconai.com")
dataList = []
boundary = 'wL36Yn8afVp8Ag7AmP8qZ0SA4n1v9T'

# 添加 model 参数
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=model;'))
dataList.append(encode('Content-Type: {}'.format('text/plain')))
dataList.append(encode(''))
dataList.append(encode("sora_video2"))

# 添加 prompt 参数
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=prompt;'))
dataList.append(encode('Content-Type: {}'.format('text/plain')))
dataList.append(encode(''))
dataList.append(encode("画面动起来"))

# 添加 seconds 参数
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=seconds;'))
dataList.append(encode('Content-Type: {}'.format('text/plain')))
dataList.append(encode(''))
dataList.append(encode("15"))

# 添加 size 参数
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=size;'))
dataList.append(encode('Content-Type: {}'.format('text/plain')))
dataList.append(encode(''))
dataList.append(encode("1280x720"))

# 添加 watermark 参数
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=watermark;'))
dataList.append(encode('Content-Type: {}'.format('text/plain')))
dataList.append(encode(''))
dataList.append(encode("false"))

# 结束边界
dataList.append(encode('--'+boundary+'--'))
dataList.append(encode(''))

body = b'\r\n'.join(dataList)
payload = body

headers = {
   'Authorization': 'Bearer <your_token_here>',
   'Content-type': 'multipart/form-data; boundary={}'.format(boundary)
}

conn.request("POST", "/v1/videos", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

注意事项

1. 异步处理: 此接口提交的是异步任务，视频生成需要一定时间处理
2. 文件上传 : 使用 input_reference 参数时，确保文件路径正确且文件可访问
3. 角色创建 : 使用 character_url 和 character_timestamps 时，确保视频中不包含真人内容
4. 分辨率限制: 高清分辨率（1024x1792 和 1792x1024）仅 sora-2-pro 模型可用
5. 隐私设置: 私有视频将不会公开发布，且无法进行二次编辑

错误处理

虽然本文档未包含具体的错误响应格式，但实际使用中应处理各种 HTTP 状态码：

• 2xx: 请求成功
• 4xx: 客户端错误（如参数错误、认证失败）
• 5xx: 服务器错误

建议在实现时添加适当的错误处理逻辑，包括重试机制和用户友好的错误提示。