申请上传租约 - Agent Studio

上传文件三步流程的第一步，返回 OSS 预签名 URL 和租约 ID

POST

/api/v1/connector/dash/applyFileUploadLease

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/connector/dash/applyFileUploadLease" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "cate_abc123",
    "fileName": "product-guide.pdf",
    "sizeBytes": "1048576",
    "contentMd5": "d41d8cd98f00b204e9800998ecf8427e"
  }'

{
  "code": "Success",
  "message": "",
  "messageUnmodified": false,
  "requestId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": {
    "type": "OSS.PreSignedUrl",
    "param": {
      "url": "https://oss-example.aliyuncs.com/...",
      "method": "PUT",
      "headers": {
        "x-bailian-extra": "MTkxMDA3MzE0NjA0NDgzNA==",
        "Content-Type": "text/plain"
      }
    },
    "leaseId": "82845f78ab0343ada293c9595ed93dbf.1782191906659"
  },
  "status": 200
}

文件上传分为三步：

申请租约（本接口）— 获取 OSS 预签名 URL 和 leaseId
PUT 上传到 OSS — 使用返回的 param.url 和 param.headers 通过 HTTP PUT 上传文件二进制内容
注册文件（addFile）— 使用 leaseId 将文件注册到数据中心

sizeBytes 必须以字符串格式传入（如 "1048576"），不能传数字。
contentMd5 为文件内容 MD5 的 Base64 编码，必须与实际上传文件一致，否则 OSS 校验失败。
category 字段名为 category（不是 categoryId）。

完整上传示例

import os, hashlib, base64, requests

# 1. 计算 MD5
with open("product-guide.pdf", "rb") as f:
    content = f.read()
content_md5 = base64.b64encode(hashlib.md5(content).digest()).decode()

# 2. 申请租约
lease_resp = requests.post(
    "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/connector/dash/applyFileUploadLease",
    headers={"Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}", "Content-Type": "application/json"},
    json={"category": "cate_abc123", "fileName": "product-guide.pdf",
          "sizeBytes": str(len(content)), "contentMd5": content_md5},
).json()

# 3. PUT 上传到 OSS
param = lease_resp["data"]["param"]
requests.put(param["url"], data=content, headers=param["headers"])

# 4. 注册文件（见 /api/file/add-file）

拿到 leaseId 并 PUT 成功后，调用注册文件完成上传。

Authorizations

string

header

required

DashScope API Key，在控制台 API Key 页面（https://agent.console.aliyun.com/settings/apikey）获取。

Body

application/json

string

required

类目 ID（注意：此字段名为 category，不是 categoryId），通过 listCategory 获取。

string

required

文件名称，包含扩展名。

string

required

文件大小（字节），以字符串格式传入。

Required range:x >= 1

string

required

文件内容的 MD5 值（Base64 编码）。

Required range:length: 1–64

enum<string>

default"UNSTRUCTURED"

类目类型，默认 UNSTRUCTURED。UNSTRUCTURED：类目，用于构建知识库；SESSION_FILE：用于智能体应用会话交互的文件。使用 SESSION_FILE 时，addFile 的 categoryType 也须传 SESSION_FILE；此类文件仅当前会话有效，关闭会话后过期（最长 7 天），不支持长期保存。

Available options:UNSTRUCTURED,SESSION_FILE

boolean

defaultfalse

是否使用安全存储空间的内网 Endpoint 上传，默认 false。

Response

200-application/json

string

响应码，成功时为 Success。

integer

HTTP 状态码。

string

请求唯一标识，排查问题时请提供此 ID。

object

Show child attributes

string

上传类型，固定为 OSS.PreSignedUrl。

string

上传租约 ID，在注册文件时使用。

object

OSS 上传参数。

Show child attributes

string

OSS 预签名上传 URL。

string

HTTP 方法，固定为 PUT。

object

上传时需要携带的请求头。

Show child attributes

string

百炼平台附加信息。

string

内容类型。

​完整上传示例

Authorizations

Body

Response

完整上传示例