上传和下载文件

注意：如果要使用 sandbox.downloadUrl() 和 sandbox.uploadUrl() 返回的 URL 上传和下载文件，确保在创建 Sandbox 时显式设置了 secure=false。否则，通过 URL 上传和下载文件仍需要请求方携带 X-Access-Token。

Python 示例：

sandbox = Sandbox.create(..., secure=False)

TypeScript 示例：

const sandbox = await Sandbox.create("code-interpreter-v1", {
  ...,
  secure: false,
});

生成下载地址

当 Sandbox 内已经生成文件时，可以通过 sandbox.downloadUrl(path) 获取下载地址，再由业务侧把文件交给用户或后续系统处理。

Python 示例：

sandbox.files.write("/tmp/result.txt", "analysis result\n")

download_url = sandbox.download_url("/tmp/result.txt")
print(download_url)

TypeScript 示例：

await sandbox.files.write("/tmp/result.txt", "analysis result\n");

const downloadUrl = await sandbox.downloadUrl("/tmp/result.txt");
console.log(downloadUrl);

生成上传地址

需要从浏览器等未持有 SDK 鉴权信息的环境把文件上传到 Sandbox 时，可以先通过 sandbox.uploadUrl(path) 获取上传地址，再从业务侧以 multipart/form-data POST 到该地址。

Python 示例：

upload_url = sandbox.upload_url("/tmp/input.csv")
print(upload_url)

TypeScript 示例：

const uploadUrl = await sandbox.uploadUrl("/tmp/input.csv");
console.log(uploadUrl);

浏览器或第三方系统拿到上传地址后，需要用 multipart/form-data 提交文件：

Python 示例：

import requests

with open("input.csv", "rb") as f:
    requests.post(upload_url, files={"file": f}).raise_for_status()

TypeScript 示例：

const form = new FormData();
form.append("file", file);

await fetch(uploadUrl, {
  method: "POST",
  body: form,
});

上传完成后，可以在 Sandbox 内直接读取或处理该文件：

Python 示例：

result = sandbox.commands.run(
    "python3 - <<'PY'\nfrom pathlib import Path\nprint(Path('/tmp/input.csv').exists())\nPY"
)
print(result.stdout.strip())

TypeScript 示例：

const result = await sandbox.commands.run("python3 - <<'PY'\nfrom pathlib import Path\nprint(Path('/tmp/input.csv').exists())\nPY");
console.log(result.stdout.trim());

注意事项

• 将 downloadUrl(path) 和 uploadUrl(path) 返回的地址交给未持有 SDK 鉴权信息的环境直接访问时，需要使用 secure=false 的 Sandbox。

• secure=false 会降低 Sandbox 暴露端点的访问保护强度。请控制 Sandbox 生命周期、文件路径和数据敏感性。

• downloadUrl(path) 和 uploadUrl(path) 生成的是指定路径的访问地址，使用前要确认路径符合业务预期。

• 不要把包含敏感数据的上传、下载地址写入日志或暴露给无关用户。

• 大文件上传后建议通过 sandbox.files.exists() 或命令检查文件是否可读。

• 文件只在当前 Sandbox 生命周期内可用。需要长期保存时，应写入外部存储。

选择建议

• 小文件、文本文件、二进制内容、流式内容和 Agent 生成代码：使用 sandbox.files.write() 和 sandbox.files.read()。

• 浏览器直传、下载结果文件或把文件交给未持有 SDK 鉴权信息的环境：使用 sandbox.uploadUrl() 和 sandbox.downloadUrl()，并在创建 Sandbox 时设置 secure=false。

• 目录遍历、重命名或删除：使用 Filesystem API。