文档中心

Appearance

文件管理 ​

使用必读 ​

  1. 普通文件先获取上传地址，通过sign_url上传文件；大文件或需要分片重试时可使用分片上传
  2. 文件上传成功后存在短暂延迟，目前最长延迟为1分钟
  3. 超过30日的文件会被自动删除
  4. 普通文件上传地址在15分钟内有效；分片上传任务和分片上传地址在6小时内有效

获取文件上传地址 ​

请求地址 ​

http
GET /open/v1/common/create_upload_url
http
access_token: {{access_token}}

请求参数 Query Params ​

Key示例说明
servicecustomised_person文件使用目的。
定制数字人：customised_person
口音转换音色素材：prompt_audio
嘴形驱动音频：make_video_audio
视频合成-背景素材：make_video_background
对口型视频：lip_sync_video
对口型音频：lip_sync_audio
Ai创作：ai_creation
name1.mp4原始文件名称，需要包含拓展名

请求示例 ​

text
https://open-api.chanjing.cc/open/v1/common/create_upload_url?service=customised_person&name=1.mp4

响应JOSN ​

json
{
    "trace_id": "5a31046b0df853c6eb972e24ef5fe6f2",
    "code": 0,
    "msg": "success",
    "data": {
        "sign_url": "https://res.chanjing.cc/chanjing%2Fres%2F37%2Fperson%2Ftrainedcustomised_person_1753239619_ea65d88474ba4501b8f72903cdf5d3af.mp4?Expires=1753243219&OSSAccessKeyId=LTAI5tQkfve4AYTyfmBR8pwV&Signature=CQWN%2F7cEDsbRc%2BB14jvqBUqUcEI%3D",
        "full_path": "https://res.chanjing.cc/chanjing/res/37/person/trainedcustomised_person_1753239619_ea65d88474ba4501b8f72903cdf5d3af.mp4",
        "key": "chanjing/res/37/person/trainedcustomised_person_1753239619_ea65d88474ba4501b8f72903cdf5d3af.mp4",
        "mime_type": "video/mp4",
        "file_id": "e284db4d95de4220afe78132158156b5"
    }
}

响应参数 ​

字段层级说明
trace_id1日志id
code1响应状态码
msg1响应消息
data1文件上传信息
sign_url2http put方法上传文件的地址（请勿使用该地址进行定制数字人功能）
full_path2上传成功后可直接访问的地址（上传成功有可能存在短暂数据同步延迟，最长延迟为1分钟）
key2文件相对路径
mime_type2文件类型
file_id2文件id

响应状态码说明 ​

code说明
0响应成功
400参数错误
10400获取文件上传地址错误

CURL ​

bash
curl --location --request GET 'https://open-api.chanjing.cc/open/v1/common/create_upload_url?service=customised_person&name=1.mp4' \
--header 'access_token: XXXXXXXXXXXXXXX' \
--header 'Accept: */*' \
--header 'Connection: keep-alive'

上传文件 ​

说明 ​

先获取文件上传地址，使用sign_url用PUT方法上传

python 请求示例 ​

python
import requests

# sign_url
upload_url = "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/chanjing%2Fres%2F34172%2Fperson%2Ftrainedcustomised_person_1770089398_b3d597e58447447089c2aa1c8cec36d9.mp4?Expires=1770092998&OSSAccessKeyId=LTAI5tGyFJym5J8RRTPerXcz&Signature=tCh6CZ%2FSe3oibPcbh%2B9uGMO5GFw%3D"
# 请使用 获取文件上传地址接口 返回的mime_type字段
content_type = "video/mp4" 
file_path = "/path/to/your/file.mp4"

with open(file_path, 'rb') as file:
    headers = {
        "Content-Type": content_type
    }
    response = requests.put(upload_url, headers=headers, data=file)
    print(f"状态码: {response.status_code}")

分片上传 ​

分片上传适用于大文件或需要逐片重试的场景。文件由客户端直接上传到阿里云 OSS，不经过开放平台服务器。

完整流程如下：

  1. 调用“创建分片上传任务”，提交文件名和文件总字节数。
  2. 按响应中 parts 的顺序切分文件，将每一片通过对应的 sign_url 上传到 OSS。
  3. 所有分片上传成功后，调用“完成分片上传任务”。
  4. 使用返回的 file_id 查询文件详情，等待文件状态从 0 变为 1 后再用于后续业务。

注意

  • 分片大小由服务端确定，当前为固定 10 MiB（10485760 字节），最后一片可以小于 10 MiB。
  • 单个上传任务最多包含 1000 个分片，文件总大小同时受对应 service 的限制。
  • 每个分片实际上传的字节数必须与 parts[].size 完全一致。
  • PUT 分片时必须携带响应 headers 中的请求头，不要向 OSS 发送 access_token。
  • upload_url 是合并后的文件地址；上传分片必须使用各自的 parts[].sign_url。

创建分片上传任务 ​

请求地址 ​

http
POST /open/v1/common/create_multipart_upload

Header ​

http
access_token: {{access_token}}
Content-Type: application/json

请求参数 Body ​

参数名称类型是否必传示例说明
servicestring是customised_person文件使用目的，与普通文件上传的 service 取值一致
namestring是training.mp4原始文件名称，需要包含扩展名
file_sizeinteger是26214400文件总大小，单位为字节，必须大于0且不能超过该 service 的文件大小限制

请求示例 ​

bash
curl --location 'https://open-api.chanjing.cc/open/v1/common/create_multipart_upload' \
--header 'access_token: XXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
  "service": "customised_person",
  "name": "training.mp4",
  "file_size": 26214400
}'

响应 JSON ​

json
{
  "trace_id": "5a31046b0df853c6eb972e24ef5fe6f2",
  "code": 0,
  "msg": "success",
  "data": {
    "file_id": "e284db4d95de4220afe78132158156b5",
    "upload_id": "0002-4F6B3A4B8A7D",
    "upload_url": "https://res.chanjing.cc/chanjing/res/37/person/trained/customised_person_example.mp4",
    "mime_type": "video/mp4",
    "headers": {
      "Content-Type": "video/mp4"
    },
    "part_size": 10485760,
    "part_count": 3,
    "expires_at": 1784196000,
    "parts": [
      {
        "part_number": 1,
        "size": 10485760,
        "sign_url": "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/example.mp4?partNumber=1&uploadId=..."
      },
      {
        "part_number": 2,
        "size": 10485760,
        "sign_url": "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/example.mp4?partNumber=2&uploadId=..."
      },
      {
        "part_number": 3,
        "size": 5242880,
        "sign_url": "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/example.mp4?partNumber=3&uploadId=..."
      }
    ]
  }
}

响应参数 ​

字段层级说明
trace_id1日志id
code1响应状态码
msg1响应消息
data1分片上传任务信息
file_id2文件id，完成上传后用于文件详情及后续业务
upload_id2分片上传任务id，完成上传时必须原样传回
upload_url2所有分片合并后的文件地址，不能用于上传分片
mime_type2文件 MIME 类型
headers2PUT 每个分片时必须携带的请求头
part_size2标准分片大小，单位为字节
part_count2分片总数
expires_at2分片上传任务过期时间，Unix 秒级时间戳
parts2分片上传信息列表
part_number3分片序号，从1开始
size3该分片必须上传的字节数
sign_url3该分片的 OSS PUT 预签名地址

响应状态码说明 ​

code说明
0响应成功
400参数错误，文件大小必须大于0
50003文件大小超过对应 service 的限制
120002创建上传任务失败，请重试

上传各个分片 ​

按 part_number 顺序读取文件，每次读取 size 指定的字节数，并 PUT 到对应的 sign_url。单个分片失败时，只需要重试该分片。

Python 请求示例 ​

python
import requests

# 创建分片上传任务接口返回的 data
upload_task = {
    "headers": {"Content-Type": "video/mp4"},
    "parts": [
        {"part_number": 1, "size": 10485760, "sign_url": "https://example.com/part-1"},
        {"part_number": 2, "size": 10485760, "sign_url": "https://example.com/part-2"},
        {"part_number": 3, "size": 5242880, "sign_url": "https://example.com/part-3"},
    ],
}

with open("/path/to/training.mp4", "rb") as file:
    for part in upload_task["parts"]:
        chunk = file.read(part["size"])
        if len(chunk) != part["size"]:
            raise ValueError(f"分片 {part['part_number']} 大小不匹配")

        response = requests.put(
            part["sign_url"],
            headers=upload_task["headers"],
            data=chunk,
        )
        response.raise_for_status()

完成分片上传任务 ​

所有分片 PUT 成功后调用该接口。服务端会从 OSS 查询并校验每个分片的编号和大小，校验通过后完成文件合并。

请求地址 ​

http
POST /open/v1/common/complete_multipart_upload

Header ​

http
access_token: {{access_token}}
Content-Type: application/json

请求参数 Body ​

参数名称类型是否必传示例说明
upload_idstring是0002-4F6B3A4B8A7D创建分片上传任务时返回的任务id

请求示例 ​

bash
curl --location 'https://open-api.chanjing.cc/open/v1/common/complete_multipart_upload' \
--header 'access_token: XXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{"upload_id":"0002-4F6B3A4B8A7D"}'

响应 JSON ​

json
{
  "trace_id": "df71e8a5189bc2908497c5ef2b0ba254",
  "code": 0,
  "msg": "success",
  "data": {
    "file_id": "e284db4d95de4220afe78132158156b5",
    "file_path": "https://res.chanjing.cc/chanjing/res/37/person/trained/customised_person_example.mp4",
    "status": 0
  }
}

响应参数 ​

字段层级说明
trace_id1日志id
code1响应状态码
msg1响应消息
data1合并后的文件信息
file_id2文件id
file_path2合并后的文件地址
status2文件状态。完成合并后为 0，需要等待异步内容审核；状态变为 1 后文件可用

响应状态码说明 ​

code说明
0响应成功
400参数错误
50005同一任务正在完成合并，请勿重复操作
120002OSS 操作失败，请重试
120004上传任务不存在、不属于当前应用或已过期
120005分片缺失、编号不连续或分片大小不匹配

文件列表 ​

请求地址 ​

http
POST /open/v1/common/file_list

Header ​

http
access_token: {{access_token}}

请求参数Body ​

参数名称类型是否必传示例说明
servicestring是customised_person上传文件时登记的使用目的
orderstring否create_time_desc排序规则，目前支持create_time_desc与create_time_asc，分别是按创建上传链接时间的倒序与正序
pagenumber否1页数，默认为0
page_sizenumber否20页码，默认为20
idstring否39e8c8afce144faa82f758a57ba10554文件id

请求示例 ​

bash
curl --location --request POST 'https://open-api.chanjing.cc/open/v1/common/file_list' \
--header 'access_token: XXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive' \
--data-raw '{"service":"customised_person", "order":"create_time_desc", "page":1, "page_size":10}'

响应JOSN ​

json
{
    "trace_id": "df71e8a5189bc2908497c5ef2b0ba254",
    "code": 0,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": "e284db4d95de4220afe78132158156b5",
                "service": "customised_person",
                "bytes": 0,
                "create_time": 1753239619,
                "file_path": "https://www.chanjing.cc/chanjing/res/37/person/trainedcustomised_person_1753239619_ea65d88474ba4501b8f72903cdf5d3af.mp4",
                "status": 1,
                "msg":""
            }
        ],
        "page_info": {
            "page": 1,
            "size": 10,
            "total_count": 1,
            "total_page": 1
        }
    }
}

响应参数 ​

字段层级说明
trace_id1日志id
code1响应状态码
msg1响应消息
data1文件列表
list3文件列表
id4文件id
service4使用目的
bytes4文件大小 单位：字节
create_time4创建时间
file_path4文件地址
status4文件状态码, 0文件未同步 1文件可用 98内容安全检测失败 99文件标记为删除 100文件已被彻底清理
msg4文件不可用原因
page_info3分页信息
page4当前页码
size4每页数据数
total_count4总文件数
total_page4总页码

响应状态码说明 ​

code说明
0响应成功
400参数错误

删除文件 ​

请求地址 ​

http
POST /open/v1/common/delete_file

Header ​

http
access_token: {{access_token}}

请求参数Body ​

参数名称类型是否必传示例说明
idstring是e284db4d95de4220afe78132158156b5文件id

请求示例 ​

bash
curl --location --request POST 'https://open-api.chanjing.cc/open/v1/common/delete_file' \
--header 'access_token: XXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{"id":"39e8c8afce144faa82f758a57ba10554"}'

响应JOSN ​

json
{
    "trace_id": "746355542a2e96c1e8a56b8b91f561b6",
    "code": 0,
    "msg": "success",
    "data": "删除成功"
}

响应参数 ​

字段层级说明
trace_id1日志id
code1响应状态码
msg1响应消息
data1删除成功

响应状态码说明 ​

code说明
0响应成功
400参数错误

文件详情 ​

请求地址 ​

http
GET /open/v1/common/file_detail

Header ​

http
access_token: {{access_token}}

请求参数 Query Params ​

KeyValue说明
id09eacb8ead0a423e9dcd75065ae32d25文件id

请求示例 ​

bash
curl --location --request GET 'https://open-api.chanjing.cc/open/v1/common/file_detail?id=09eacb8ead0a423e9dcd75065ae32d25' \
--header 'access_token: XXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Connection: keep-alive'

响应JOSN ​

json
{
    "trace_id": "df71e8a5189bc2908497c5ef2b0ba254",
    "code": 0,
    "msg": "success",
    "data": {
        "id": "e284db4d95de4220afe78132158156b5",
        "service": "customised_person",
        "bytes": 0,
        "create_time": 1753239619,
        "file_path": "https://www.chanjing.cc/chanjing/res/37/person/trainedcustomised_person_1753239619_ea65d88474ba4501b8f72903cdf5d3af.mp4",
        "status": 1,
        "msg":""
    }
}

响应参数 ​

字段层级说明
trace_id1日志id
code1响应状态码
msg1响应消息
data1文件列表
list3文件列表
id4文件id
service4使用目的
bytes4文件大小 单位：字节
create_time4创建时间
file_path4文件地址
status4文件状态码, 0文件未同步 1文件可用 98内容安全检测失败 99文件标记为删除 100文件已被彻底清理
msg4文件不可用原因
page_info3分页信息
page4当前页码
size4每页数据数
total_count4总文件数
total_page4总页码

响应状态码说明 ​

code说明
0响应成功
400参数错误