Skip to main content

Apply for Upload Lease

First step of the three-step file upload process; returns an OSS presigned URL and a lease 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
}
File upload consists of three steps:
  1. Apply for a lease (this API) — Obtain an OSS presigned URL and leaseId
  2. PUT upload to OSS — Upload the file’s binary content via HTTP PUT using the returned param.url and param.headers
  3. Register the file (addFile) — Register the file in the data center using the leaseId
  • sizeBytes must be passed as a string (e.g., "1048576"), not as a number.
  • contentMd5 is the Base64-encoded MD5 hash of the file content and must exactly match the actual uploaded file; otherwise, OSS validation will fail.
  • The field name is category (not categoryId).

Complete Upload Example

import os, hashlib, base64, requests

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

# 2. Apply for lease
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 upload to OSS
param = lease_resp["data"]["param"]
requests.put(param["url"], data=content, headers=param["headers"])

# 4. Register file (see /api/file/add-file)
After obtaining the leaseId and successfully completing the PUT upload, call Register File to complete the upload.

Authorizations

​
string
header
required

DashScope API Key，在控制台 API Key 页面 获取。

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。

​
string

错误或提示信息，成功时为空字符串。

​
string

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

​
object
​
integer

业务状态码。成功为 200，参数错误等失败场景为 400。注意失败时 HTTP 状态码仍为 200，需根据本字段与 code 判断结果。