Sora Videos Generation API 对接说明

本文将介绍 Sora Videos Generation API 的对接说明，通过该 API 可以输入自定义参数来生成 Sora 官方的视频。本 API 支持两种版本模式：

Version 1（经典模式）：支持 duration（10/15/25 秒）、orientation（横屏/竖屏）、size（small/large 清晰度）、参考图 image_urls、角色视频 character_url 等参数。
Version 2（合作商模式）：支持 seconds（4/8/12 秒）、像素级分辨率 size（如 1280x720）、参考图 input_reference 等参数。

申请流程

要使用 API，需要先到 Sora Videos Generation API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费使用该 API。

基本使用（Version 1）

首先先了解 Version 1 的基本使用方式，就是输入提示词 prompt、参考图片链接数组 image_urls 以及模型 model，便可获得处理后的结果，具体的内容如下：

可以看到这里我们设置了 Request Headers，包括：

accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。
authorization：调用 API 的密钥，申请之后可以直接下拉选择。

另外设置了 Request Body，包括：

model：生成视频的模型，支持 sora-2（标准模式）和 sora-2-pro（高清模式）。其中 sora-2-pro 可以支持 duration 为 25 秒的视频，而 sora-2 只支持 10、15 秒。
size：视频清晰度，small 为标准清晰度、large 为 HD 清晰度（仅 Version 1）。
duration：视频时长，支持 10、15、25 秒，其中 25 秒仅 sora-2-pro 支持（仅 Version 1）。
orientation：画幅方向，支持 landscape（横屏）、portrait（竖屏）（仅 Version 1）。
image_urls：参考图片链接数组，用于图生视频（仅 Version 1）。
character_url：角色视频链接，视频中不能出现真人（仅 Version 1）。
character_start/character_end：角色出现的起止秒数，范围差值为 1-3 秒（仅 Version 1）。
prompt：提示词（必填）。
callback_url：异步回调结果的 URL。
version：API 版本，"1.0"（默认）或 "2.0"。

选择之后，可以发现右侧也生成了对应代码，如图所示：

点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果：

{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}

返回结果一共有多个字段，介绍如下：

success，此时视频生成任务的状态情况。
task_id，此时视频生成任务ID。
trace_id，此时视频生成跟踪ID。
data，此时视频生成任务的结果列表。
- id，此时视频生成任务的视频ID。
- video_url，此时视频生成任务的视频链接。
- state，此时视频生成任务的状态。

可以看到我们得到了满意的视频信息，我们只需要根据结果中 data 的视频链接地址获取生成的Sora视频即可。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "size": "large",
  "duration": 15,
  "orientation": "landscape",
  "prompt": "cat running on the river",
  "model": "sora-2"
}'

图生视频任务（Version 1）

如果想进行图生视频任务，首先参数 image_urls 必须传入参考图片链接，就可以指定如下内容：

image_urls：该图生视频任务采用的参考图链接数组。注意不可传递真实的带有头像的人物图像，否则可能导致任务失败。

填写样例如下：

填写完毕之后自动生成了代码如下：

对应的代码：

import requests

url = "https://api.acedata.cloud/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "size": "large",
    "duration": 15,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

点击运行，可以发现会立即得到一个结果，如下：

{
  "success": true,
  "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a",
  "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172",
  "data": [
    {
      "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}

可以看到，生成的效果是图生建视频的，结果与上文类似。

角色生成视频任务（Version 1）

如果想进行角色生成视频任务，首先参数 character_url 必须传入创建角色需要的视频链接，注意视频中一定不能出现真人，否则会失败，就可以指定如下内容：

character_url：创建角色需要的视频链接，注意视频中一定不能出现真人，否则会失败。

填写样例如下：

填写完毕之后自动生成了代码如下：

对应的代码：

import requests

url = "https://api.acedata.cloud/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "size": "small",
    "duration": 10,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "character_url": "https://cdn.acedata.cloud/pdidf5.mp4",
    "model": "sora-2",
    "character_end": 3,
    "character_start": 1
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

点击运行，可以发现会立即得到一个结果，如下：

{
  "success": true,
  "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259",
  "trace_id": "b7992643-9207-40d6-956b-7577728acc67",
  "data": [
    {
      "id": "sora-2:task_01k8ykrztefavaypw6xanw305b",
      "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

可以看到，生成的效果是角色生成视频，结果与上文类似。

Version 2.0 模式

除了上述 Version 1.0 模式之外，本 API 还支持 Version 2.0 模式，通过设置 version 参数为 "2.0" 即可启用。Version 2.0 模式支持更短的视频时长和像素级的分辨率控制。

Version 2.0 参数说明

参数	类型	是否必填	说明
`version`	string	是	设置为 `"2.0"`
`prompt`	string	是	生成视频的提示词
`model`	string	否	`sora-2`（默认）或 `sora-2-pro`
`duration`	integer	否	视频时长：`4`（默认）、`8`、`12` 秒
`size`	string	否	分辨率：`720x1280`（默认）、`1280x720`、`1024x1792`、`1792x1024`
`image_urls`	array	否	参考图片 URL 数组，仅使用第一张图片，图片尺寸需要与 `size` 参数一致
`callback_url`	string	否	异步回调 URL

基本示例

curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "version": "2.0",
  "prompt": "cat running on the river",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'

对应的 Python 代码：

import requests

url = "https://api.acedata.cloud/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "version": "2.0",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

对应的 JavaScript 代码：

const response = await fetch('https://api.acedata.cloud/sora/videos', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'authorization': 'Bearer {token}',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    version: '2.0',
    prompt: 'cat running on the river',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);

返回结果格式与 Version 1 相同：

{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "c0cc8dad-0954-421f-be8d-02eb063b3263",
      "video_url": "https://platform.cdn.acedata.cloud/sora/xxxxx.mp4",
      "state": "succeeded"
    }
  ]
}

使用参考图片（Version 2.0）

在 Version 2.0 模式下，可以通过 image_urls 参数传入参考图片来引导视频生成（仅使用第一张图片）：

import requests

url = "https://api.acedata.cloud/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "version": "2.0",
    "prompt": "a person walking through a beautiful garden",
    "model": "sora-2",
    "duration": 4,
    "size": "1280x720",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

注意：参考图片的尺寸应与 size 参数保持一致，例如 size 为 1280x720 时，参考图片尺寸应为 1280×720。

Version 1.0 与 Version 2.0 参数对比

参数	Version 1.0	Version 2.0
`version`	1.0（默认）	2.0
`prompt`	✅	✅
`model`	✅ sora-2 / sora-2-pro	✅ sora-2 / sora-2-pro
`duration`	✅ 10/15/25 秒	✅ 4/8/12 秒
`orientation`	✅ landscape/portrait	❌
`size`	✅ small/large	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ 多张参考图	✅ 仅使用第一张
`character_url`	✅	❌
`callback_url`	✅	✅

异步回调

由于 Sora Videos Generation API生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。

整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成视频的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。

下面我们通过示例来了解下具体怎样操作。

首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa。

接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下：

1
2
3

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

稍等片刻，我们可以在 https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa 上观察到生成视频的结果，如图所示：

内容如下：

{
    "success": true,
    "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
    "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
    "data": [
        {
            "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5",
            "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus",
            "state": "succeeded"
        }
    ]
}

可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
401 invalid_token：Unauthorized, invalid or missing authorization token.
429 too_many_requests：Too many requests, you have exceeded the rate limit.
500 api_error：Internal server error, something went wrong on the server.

错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 Sora Videos Generation API 可通过输入提示词以及参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。