OpenAI 文件与产物

文件与已发布产物

文件位于智能体执行环境中。产物（artifact）是从 OpenAI 托管环境发布的文件副本，环境过期后仍可下载。

上传文件

OpenAI 托管环境在创建会话时，通过 environment.files 提供输入文件，并为每个文件选择 /workspace 下的目标位置。

可使用 type: "file_id" 引用 Files API返回的 file_id，或使用 type: "inline" 提供 Base64 编码 data；两种方式都必须有 path。

环境连接后补充文件，使用环境 Files API。

处理上传错误

创建会话或附加文件时，文件检查可能返回 HTTP 429，错误码为 files_api_rate_limit_exceeded。响应与恢复方法见 Files API 速率限制。

HTTP 400 使用 error.param 和 error.message 定位需修正的输入。例如目标不在 /workspace 下时：

来源示例 1（json）：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "path must be an absolute POSIX path inside /workspace",
    "param": "path"
  }
}

参数路径与请求结构一致。下表的 i 为文件索引，首个文件从 0 开始：

使用有效 Base64、文件 ID 和 /workspace 下的绝对路径，并检查文件限制。路径经过符号链接、目标已存在或路径组件过长，都可能返回 HTTP 400。

安装文件时遇到意外错误会返回 HTTP 500。重试前，先检查目标是否已经创建，再遵循暂时性失败重试指南。

取回文件

从自有环境取回

让智能体把输出写入已知路径。轮次结束后通过提供商或自己的基础设施取回文件，在环境过期或删除前存入应用存储。

自托管环境的文件不会通过 Artifacts API 发布，包括 /workspace/outputs 下的文件。提供商专属访问方式见沙箱提供商。

从 OpenAI 托管环境取回

让智能体把文件保存到 /workspace/outputs，例如 /workspace/outputs/report.pdf。轮次完成时，OpenAI 把输出发布为不可变产物。

向以下函数传入 API 客户端、会话 ID、已完成轮次 ID、产物路径和本地目标路径。函数先列出产物，再下载轮次与路径均匹配的文件：

来源示例 2（python）：

## [中文] 示例 2：从 OpenAI 托管环境取回。
## [中文] 逐页查找 turn_id 和 path 同时匹配的产物，通过 SDK 流式写入目标文件；本片段未显式检查本地目标是否已存在，应用需按需处理覆盖。
## Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")

请求与响应字段见列出产物、读取元数据和下载内容。

下载多个文件

每个请求只下载一个产物，没有批量下载端点。下载多个文件时，先列出产物，再逐一请求 content。希望只下载一次，可以让智能体在 /workspace/outputs 下将结果打成 ZIP，再把压缩包作为单个产物下载。

文件生命周期

已发布产物在环境过期后仍存在。删除会话前，下载需要长期保存的内容。

此 API 不能上传或编辑产物。要发布新版本，让智能体修改环境内文件并完成另一个轮次，以轮次 ID 和路径区分版本。

不再需要发布副本时可删除产物，这不会删除环境内的原文件。

文件限制