文件 - 智谱AI开放文档

Files API 覆盖两类用法：输入（把材料送进会话给 Agent 读）和产物（把 Agent 写出来的结果拿回来）。底层都是同一个 File 对象，差别在来源、沙箱路径和能不能被编目下载。

	输入	产物
用途	给 Agent 读的材料：表格、文档、附件	Agent 做完要交给你的文件：报告、图表、导出结果
怎么来	你 POST /v1/files 上传，再挂到会话	Agent 写入 /mnt/session/outputs，平台自动编目
沙箱路径	/mnt/session/uploads，对 Agent 只读	/mnt/session/outputs，读写
怎么取回	你本来就持有源文件	GET /v1/files?scope_id=$SESSION_ID 列出，再下载 content

写在 /workspace 的中间文件不会被编目，会话结束后无法通过 Files API 取回。需要交给调用方的内容，应写到 outputs。

输入：上传并挂载

POST /v1/files，multipart 形式：

file=$(curl -sS "$BASE_URL/v1/files" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -F "file=@sales_data.csv;type=text/csv")

FILE_ID=$(jq -r '.id' <<< "$file")

{
  "type": "file",
  "id": "file_xxxxxxxxxxxx",
  "filename": "sales_data.csv",
  "mime_type": "text/csv",
  "size_bytes": 182044,
  "downloadable": true,
  "created_at": "2026-08-28T08:00:00.000Z"
}

约束：单文件默认上限 500 MB；文件名 1–255 字符，不得为 . 或 ..，不得含控制字符及小于号、大于号、冒号、双引号、竖线、问号、星号、斜杠、反斜杠；省略 MIME 类型时按 application/octet-stream 处理；组织总配额默认 500 GB。文件类型不限——任何格式都可以上传，是否能被处理取决于沙箱内的工具。创建会话时通过 resources 数组挂载。文件会出现在 /mnt/session/uploads 下，对 Agent 只读：

curl -sS "$BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "resources": [
    { "type": "file", "file_id": "$FILE_ID", "mount_path": "/data/sales_data.csv" }
  ]
}
EOF

挂载路径规则：

mount_path 可写相对形式（/data/sales_data.csv）或完整形式（/mnt/session/uploads/data/sales_data.csv），都归一化到 uploads 目录下。
省略或 null 时默认为 /mnt/session/uploads/<源 File 的 file_id>。
路径会折叠 . 段与多余斜杠、拒绝 .. 越界，结果 ≤1024 UTF-8 字节；多个 File Resource 的路径之间不得重叠。
实际生效路径以响应 resources[].mount_path 的返回值为准。

一个会话最多挂载 500 个 File Resource。挂载时服务端会把源 File 复制为会话范围（scope）的 File，因此响应中的 file_id 可能与你传入的不同。会话创建后也可以追加挂载：

curl -sS "$BASE_URL/v1/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d "{
    \"type\": \"file\",
    \"file_id\": \"$FILE_ID\",
    \"mount_path\": \"/data/extra.csv\"
  }"

配套接口：GET /v1/sessions/:id/resources（列出，limit 1–1000）、GET …/resources/:resourceId（详情）、DELETE …/resources/:resourceId（卸载）。File Resource 当前不支持更新（POST 返回 400）；已归档会话不可增删资源。常见输入：表格与原始数据、需要 Agent 阅读的文档、用户上传的附件。系统提示词里写清挂载路径，例如「输入数据在 /mnt/session/uploads/data/sales_data.csv」。

产物：列出并下载

Agent 把要交给你的文件写入 /mnt/session/outputs（读写）。平台会把该目录中的文件编目为会话范围的 File，之后即可列出并下载：

curl -sS "$BASE_URL/v1/files?scope_id=$SESSION_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

curl -sS -L "$BASE_URL/v1/files/$FILE_ID/content" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -o report.xlsx

会话范围的 File 在 list/get 响应中带 scope 字段（{"type": "session", "id": "sess_..."}）；组织级上传的 File 无 scope。列表分页用 before_id / after_id 游标（互斥），limit 默认 20、最大 1000。

在系统提示词或用户消息里写明产出路径，例如：「把最终报告保存到 /mnt/session/outputs/report.xlsx」。写在 /workspace 的中间文件不会被编目，下载不到。

常见产物：分析报告、导出表格、图表与文档。等到 session.status_idle 再列出 outputs，避免文件还在写入。

文件接口一览

接口	说明
POST /v1/files	上传文件（multipart），用作输入
GET /v1/files	列出文件；scope_id 过滤某个会话的产物
GET /v1/files/:fileId	获取文件元数据
GET /v1/files/:fileId/content	下载文件内容
DELETE /v1/files/:fileId	删除文件（返回 `{id, type: "file_deleted"}`）

下一步

创建会话

resources 数组的完整字段

预装沙箱环境

uploads / outputs / workspace 目录契约

最佳实践

数据分析场景里如何接输入与产物

本页对应 OpenAPI

File：上传、列出、下载

开始使用

定义 Agent

配置运行环境

运行会话

上下文与记忆

自动化

参考

文件

输入：上传并挂载

产物：列出并下载

文件接口一览

下一步

创建会话

预装沙箱环境

最佳实践

本页对应 OpenAPI

​输入：上传并挂载

​产物：列出并下载

​文件接口一览

​下一步

创建会话

预装沙箱环境

最佳实践

本页对应 OpenAPI

输入：上传并挂载

产物：列出并下载

文件接口一览

下一步