Sora-2 API 技术文档：创建角色接口

接口概述

创建角色接口允许开发者通过视频素材或已完成的任务来生成新的AI角色。该接口支持从视频中提取特定时间段的角色信息，或基于已有任务结果创建角色。

接口详情

基本信息

• 状态: 开发中
• 请求方法: POST
• 接口路径 : https://n.lconai.com/sora/v1/characters

请求参数

1. 认证参数

位置	参数名	类型	必需	描述
Header	Authorization	string	是	Bearer Token认证

格式示例：

Authorization: Bearer ********************

2. Query参数

参数名	类型	必需	描述	示例
url	string	否	视频URL地址	https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4
timestamps	string	否	角色出现的时间范围	1,3

3. Header参数

参数名	类型	必需	默认值	描述
Content-Type	string	否	application/json	请求内容类型
Authorization	string	是	{``{Authorization}}	认证令牌

4. Body参数（JSON格式）

参数名	类型	必需	描述	约束
url	string	否	视频URL，包含需要创建的角色	-
timestamps	string	否	角色出现的时间范围	单位：秒 格式：开始时间,结束时间 范围差值：最小1秒，最大3秒
from_task	string	否	已完成的任务ID	基于已有任务结果创建角色

Body示例：

{
    "url": " https://image-plus.oss-cn-beijing.aliyuncs.com/sora/0007dfc9-1a5d-4492-b8bd-42498617880f.mp4 ",
    "timestamps": "1,3"
}

请求示例

cURL示例

curl -X POST \
  ' https://n.lconai.com/sora/v1/characters?url=https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4&timestamps=1,3' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": " https://image-plus.oss-cn-beijing.aliyuncs.com/sora/0007dfc9-1a5d-4492-b8bd-42498617880f.mp4 ",
    "timestamps": "1,3"
  }'

PHP示例

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => ' https://n.lconai.com/sora/v1/characters?url=https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4&timestamps=1,3',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "url": " https://image-plus.oss-cn-beijing.aliyuncs.com/sora/0007dfc9-1a5d-4492-b8bd-42498617880f.mp4 ",
        "timestamps": "1,3"
    }',
    CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer <token>',
        'Content-Type: application/json'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

响应

成功响应（HTTP 200）

Content-Type : application/json

响应体结构：

{
    "id": "string",
    "username": "string",
    "permalink": "string",
    "profile_picture_url": "string"
}

字段说明：

字段名	类型	必需	描述
id	string	是	角色唯一标识符
username	string	是	角色名称，用于在提示词中引用（格式：@{username}）
permalink	string	是	角色主页URL，可跳转到OpenAI角色主页
profile_picture_url	string	是	角色头像图片URL

使用说明

1. 参数选择策略

• 视频创建模式 ：同时提供url和timestamps参数，从视频指定时间段提取角色
• 任务继承模式 ：仅提供from_task参数，基于已有任务结果创建角色
• 混合模式：可同时提供视频参数和任务ID，系统会优先使用任务结果

2. 时间范围约束

• 时间格式：开始时间,结束时间（单位：秒）
• 最小时间差：1秒
• 最大时间差：3秒
• 示例 ："1,3"表示视频第1秒到第3秒出现的角色

3. 认证要求

所有请求必须包含有效的Bearer Token，通过Authorization头传递。