YoYAI

主题

Sora Videos 视频生成 API 对接说明 ​

YoYAI 套餐明细（企业商业合作请联系邮箱：support@yoy-ai.com） ​

套餐等级积分总量优惠价格 (税前)税后价格 (加5.3%)折扣力度
基础版100¥98.0¥1039.8折
白银版540¥520.0¥5489.629折
黄金版1,120¥1050.0¥1,1069.375折
铂金版6,000¥5,450.00¥5,7399.083折
钻石版13,000¥11,400.00¥12,0048.769折
尊享版25,200¥21,550.00¥22,6928.551折
旗舰版68,000¥55,800.00¥58,7578.206折
至尊版143,000¥114,400.00¥120,4638.0折

注：只有在要求开具 6% 增值税专用发票时，才需按照“税后价格”进行结算。

积分消耗说明 ​

模型视频分辨率视频时长专业模型(is_pro)消耗积分
sora-2/10/15false0.25
sora-2/10/15true0.75
sora-2-prosmall10/15暂不支持2.8
sora-2-prosmall25暂不支持3.5
sora-2-prolarge10/15/25暂不支持3.5

基本使用 ​

想些提示词来生成视频，可以任意输入一段文字，比如我想生成一个关于小猫的视频，就可以输入 cat running on the road，下面使用apifox进行发送请求，具体的参数如下所示：

json
{
  "image_urls": [],
  "model": "sora-2",
  "orientation": "landscape",
  "size": "small",
  "duration": 10,
  "prompt": "cat running on the road",
  "action": "generate"
}

传入参数的字段说明如下：

  • action 生成视频的行为参数，主要包含生成视频（包含了文生视频和图生视频俩种生成）generate，默认是生成视频。
  • prompt：生成视频的提示词。
  • duration：生成视频的时长，目前支持：10、15。
  • orientation：生成视频的orientation参数，目前支持：landscape、portrait。
  • size：生成视频的size参数，目前支持：small、large。
  • model：生成视频的模型，默认：sora-2、sora-2-pro。
  • image_urls：当视频任务是图生视频时，该值是必填参数，它是生成视频的参考图片链接数组，按照官方要求它可传入1、2、4个图片链接。

2025.10.13 更新：新功能上线！

我们推出了全新模型 sora-2-pro，支持生成 10秒 或 15秒 的视频。

  • 10秒 HD 视频 生成时间：10-20 分钟
  • 15秒 HD 视频 生成时间：25-35 分钟

（注：HD 对应 size 参数值为 large，以上时间为 OpenAI 官方预估。）

视频模糊？试试优化提示词！
如果生成的视频不够清晰，可能是提示词不够精准。建议：

  1. 加入 高清相关关键词（如 "4K"、"超清" 等）。
  2. 用 AI 工具优化提示词，效果更佳。

未优化的提示词可能导致官方生成的视频效果模糊，优化后画质会有显著提升！

可以点击测试按钮直接测试 API，稍等 1-2 分钟，结果如下：

json
{
    "success": true,
    "task_id": "3ad94e1d-0a6c-4d35-a188-a32787fc1f93",
    "trace_id": "3680afb7-7b79-4388-98b8-3e24bb3a4ddd",
    "data": [
        {
            "id": "7edb9e9d-e294-4afa-9a1c-2f36075cafa7",
            "video_url": "https://cdn.sunohub.cn/suno/3ad94e1d-0a6c-4d35-a188-a32787fc1f93.mp4",
            "created_at": "2025-10-10T01:44:16.877Z",
            "complete_at": "2025-10-10T01:48:23.986Z",
            "state": "succeeded"
        }
    ]
}

可以看到这时候我们就得到了根据提示词生成图像的内容。

字段说明如下：

  • success：生成是否成功，如果成功则为 true，否则为 false
  • data：是一个列表，包含了生成的视频的详细信息。
    • video_url：生成的视频链接

创建角色生成视频功能 ​

如果想对自己上传的视频进行创建角色生成视频的话，我们需要先在Role接口上传视频链接得到name，下面是创建角色的参数，其中video_url表示视频链接，不能超过3s，还有name是唯一的，建议取长一点。如下所示：

  • name：角色名称，是唯一的，在后续生成视频时需要使用。
  • video_url：角色视频的链接，最长3s。
  • description：角色视频的描述，选填。
  • instruction_text：角色视频的指导文字，选填。
  • safety_instruction_text：角色视频的安全指导文字，选填。

填写样例如下：

点击发送，可以发现会得到一个结果，如下：

json
{
    "success": true,
    "task_id": "730690da-1eb4-4922-b57c-ec678c497edf",
    "data": {
        "name": "123fgdsadasd",
        "state": "succeeded"
    }
}

可以看出，结果内容里面的name就是我们需要的值，然后我们使用该值在生成接口来生成视频，具体的如下所示：

填写样例如下：

注意：在prompt使用角色的时候一定要在前面加一个空格来区分它（如果在开头使用就只需要后面空格），比如：xxx @name xxx、@name xxxx。

点击发送，可以发现会得到一个结果，如下：

json
{
    "success": true,
    "task_id": "8e5a2dca-f961-4b29-920e-a41c46baf0d9",
    "trace_id": "117dbccf-c0f6-4082-8cd0-6cc5e6ac2a5f",
    "data": [
        {
            "id": "0d1a98d8-cb82-4471-82a5-5d20889e1650",
            "video_url": "https://cdn.sunohub.cn/suno/8e5a2dca-f961-4b29-920e-a41c46baf0d9.mp4",
            "edit_id": "s_6926593431a481918c9198fc2be35230",
            "created_at": "2025-11-26T01:31:42.982Z",
            "complete_at": "2025-11-26T01:34:53.094Z",
            "state": "succeeded"
        }
    ]
}

编辑视频生成视频功能 ​

如果想对生成后的视频进行编辑生成的话，可以根据基本视频结果的edit_id 来指定视频进行重新编辑生成。下面以一个edit_id:s_6926593431a481918c9198fc2be35230例子进行测试，如下所示：

填写样例如下：

点击发送，可以发现会得到一个结果，如下：

json
{
    "success": true,
    "task_id": "e7714da3-0178-4107-8fb5-08674564dbf5",
    "trace_id": "3b4633e9-5775-4891-af07-e65980d365a7",
    "data": [
        {
            "id": "68a9f09f-1f72-4053-a98a-97d9064f4a19",
            "video_url": "https://cdn.sunohub.cn/suno/e7714da3-0178-4107-8fb5-08674564dbf5.mp4",
            "edit_id": "s_69265c85c9108191954e1239f11561fc",
            "created_at": "2025-11-26T01:45:43.349Z",
            "complete_at": "2025-11-26T01:49:13.485Z",
            "state": "succeeded"
        }
    ]
}

可以看出，结果内容里面的name就是我们需要的值，

异步回调 ​

由于 Sora Videos 生成视频的时间相对较长，大约需要 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/03e60575-3d96-4132-b681-b713d78116e2。

接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入 prompt，如图所示：

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

{
  "task_id": "446344aa-b990-44bf-a136-366ba7937496"
}

稍等片刻，我们可以在 https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2 上观察到生成歌曲的结果，如图所示：

内容如下：

json
{
    "success": true,
    "task_id": "3ad94e1d-0a6c-4d35-a188-a32787fc1f93",
    "trace_id": "3680afb7-7b79-4388-98b8-3e24bb3a4ddd",
    "data": [
        {
            "id": "7edb9e9d-e294-4afa-9a1c-2f36075cafa7",
            "video_url": "https://cdn.sunohub.cn/suno/3ad94e1d-0a6c-4d35-a188-a32787fc1f93.mp4",
            "created_at": "2025-10-10T01:44:16.877Z",
            "complete_at": "2025-10-10T01:48:23.986Z",
            "state": "succeeded"
        }
    ]
}

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