简创AIGC官方文档

主题切换

UPLOAD_FILE API 接口文档 ​

🌐 语言切换 ​

中文版 | English

接口信息 ​

POST /openapi/capcut-mate/v1/upload_file
Content-Type: multipart/form-data

功能描述 ​

上传文件到对象存储（服务端中转）。客户端把文件字节提交到本服务，服务端转发上传到对象存储， 上传成功后按文件实际体积计费（0.0005 元/MB），并返回带签名的下载 URL。 对象存储密钥全程留在服务端，不会下发给客户端。

请求参数 ​

以 multipart/form-data 提交：文件放在 file 字段，密钥放在 apiKey 字段。

bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/upload_file \
  -F "file=@demo.mp4" \
  -F "apiKey=123e8567-e89b-12d3-a856-826618178000"

参数说明 ​

参数名类型必填默认值说明
filefile✅-待上传文件，单文件最大 500MB
apiKeystring按服务端配置-合法的 UUID；ENABLE_APIKEY=true 时必填，可登录 https://jcaigc.cn 获取

参数详解 ​

file ​

  • 类型: 文件（multipart/form-data）
  • 说明: 支持常见音视频/图片格式：mp4、mov、m4v、avi、mkv、flv、webm、wmv、mp3、wav、m4a、aac、flac、ogg、jpg、jpeg、png、gif、webp、bmp
  • 限制: 单文件最大 500MB，空文件会被拒绝

apiKey ​

  • 类型: string
  • 说明: 必须是合法的 UUID 格式；服务端开启 apiKey 校验时必填，且账户余额需大于 1 才可上传

响应格式 ​

成功响应 (200) ​

json
{
  "code": 0,
  "message": "success",
  "url": "https://bucket.oss-cn-hangzhou.aliyuncs.com/jianchuang/2026-10-06/8f3a1c2d5e6b7a90_demo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx",
  "key": "jianchuang/2026-10-06/8f3a1c2d5e6b7a90_demo.mp4",
  "size": 10485760,
  "size_mb": 10.0,
  "cost": 0.005,
  "url_expire_days": 7
}

响应字段说明 ​

字段名类型说明
urlstring对象存储带签名的临时下载地址，可直接传给 add_videos / add_images / add_audios 等接口
keystring对象存储 object key
sizeint文件实际字节数
size_mbfloat文件体积（MB，保留 3 位小数）
costfloat本次上传费用（元）；未启用计费时为 0
url_expire_daysinturl 有效期（天），取 VIDEO_GEN_RETENTION_DAYS（默认 7 天）

错误响应 ​

json
{
  "code": 2050,
  "message": "不支持的文件类型，请上传受支持格式的文件"
}

使用示例 ​

cURL 示例 ​

bash
curl -X POST https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/upload_file \
  -F "file=@demo.mp4" \
  -F "apiKey=123e4567-e89b-12d3-a456-426614174000"

Python 示例 ​

python
import requests

with open("demo.mp4", "rb") as f:
    resp = requests.post(
        "https://capcut-mate.jcaigc.cn/openapi/capcut-mate/v1/upload_file",
        files={"file": ("demo.mp4", f, "video/mp4")},
        data={"apiKey": "123e4567-e89b-12d3-a456-426614174000"},
        timeout=600,
    )

result = resp.json()
video_url = result["url"]  # 可直接传给 add_videos / add_images / add_audios
print("体积:", result["size_mb"], "MB", "费用:", result["cost"], "元")

错误码说明 ​

错误码错误信息说明解决方案
1001参数校验失败缺少 file 字段、apiKey 不是合法 UUID，或上传了空文件检查请求参数
2004文件大小超出限制文件超过 500MB压缩或切分文件后重试
2035账户余额不足账户积分需大于 1 才可继续使用服务完成充值后重试
2036无效的 apiKeyENABLE_APIKEY=true 且 apiKey 缺失或非法登录 https://jcaigc.cn 获取 apiKey
2049无效的文件名文件名为空或清洗后没有可用字符提供合法的文件名
2050不支持的文件类型扩展名不在内置白名单内改用受支持的格式
9998系统内部错误未配置任何对象存储或上传失败检查服务端对象存储配置

注意事项 ​

  1. 服务端中转：文件先上传到本服务，再由服务端上传到对象存储；对象存储密钥不会下发给客户端
  2. 计费规则：0.0005 元/MB，按文件实际字节数计算（保留 6 位小数），仅在对象存储上传成功后才扣费
  3. 大小限制：单文件最大 500MB；若部署在 nginx 之后，需同时放开 client_max_body_size（默认 1MB 会直接返回 413）
  4. 有效期：返回的 url 为带签名的临时地址，有效期由 VIDEO_GEN_RETENTION_DAYS 控制（默认 7 天）
  5. 上传完成即可用：url 可直接传给 add_videos / add_images / add_audios 等接口使用

工作流程 ​

  1. 校验 apiKey（ENABLE_APIKEY=true 时）与账户余额（需大于 1）
  2. 清洗文件名并校验扩展名白名单
  3. 流式落盘并统计文件体积（超过 500MB 或为空则拒绝）
  4. 上传文件到对象存储（COS / OSS / TOS）
  5. 上传成功后按体积扣费
  6. 返回带签名的下载 URL

相关接口 ​

版权所有 © 2025 简创AIGC