下载文件内容-阿里云帮助中心

获取文件的下载地址。服务端返回一个带有时效性的预签名 URL，客户端可通过该 URL 直接下载文件内容。

仅 purpose 为 tool_output 或 skill_output 的文件支持内容下载。其他用途的文件会返回 403 错误。

请求头

头部	必选	说明
`Authorization`	是	`Bearer`

路径参数

参数	类型	必选	说明
`file_id`	string	是	文件唯一标识（`file_` 前缀）

示例请求

# 获取下载 URL（不跟随重定向）
curl -X GET "https://api.qoder.com.cn/api/v1/cloud/files/file_019e3bb9b0c2752688aeb5fdacf00565/content" \
  -H "Authorization: Bearer $QODER_PAT"

# 跟随重定向直接下载文件内容
curl -L -o output.txt \
  -X GET "https://api.qoder.com.cn/api/v1/cloud/files/file_019e3bb9b0c2752688aeb5fdacf00565/content" \
  -H "Authorization: Bearer $QODER_PAT"

示例响应

HTTP 302 Found

服务端返回 HTTP 302 重定向，响应体包含预签名 URL 信息：

{
  "expires_at": "2026-05-18T16:34:52Z",
  "url": "https://qoder-cloud-agents-storage-test.oss-ap-southeast-1-internal.aliyuncs.com/files/..."
}

响应头中 Location 字段也包含该下载 URL。

响应字段

字段	类型	说明
`url`	string	预签名下载 URL
`expires_at`	string	URL 过期时间（ISO 8601），通常为请求后约 1 小时

下载 URL 说明

预签名 URL 具有时效性，过期后需要重新请求
URL 中包含 response-content-disposition 参数，浏览器访问时会触发下载并使用原始文件名
使用 curl -L 可自动跟随重定向下载文件

错误码

HTTP	type	触发条件
401	`authentication_error`	缺少或无效的认证令牌
403	`permission_error`	文件用途不允许下载（仅 `tool_output` 和 `skill_output` 可下载）
404	`not_found_error`	指定 ID 的文件不存在

错误响应示例：

403 — 文件用途受限

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Only files with purpose 'tool_output' or 'skill_output' can be downloaded."
  }
}

404 — 文件不存在

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File 'file_nonexistent123' was not found."
  }
}

完整错误信封说明详见错误参考。