For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

代码解释器

让模型通过编写和运行 Python 来解决问题。

代码解释器工具让模型能够在沙盒环境中编写和运行 Python 代码,解决数据分析、编程和数学等领域的复杂问题。您可以用它来:

  • 处理包含多种数据和格式的文件
  • 生成包含数据和图表图像的文件
  • 通过反复编写和运行代码来解决问题。例如,如果模型编写的代码运行失败,它可以不断修改并运行代码,直到成功
  • 提升我们最新推理模型(如 o3o4-mini)的视觉智能。模型可以使用此工具裁剪、缩放、旋转图像,以及对图像进行其他处理和变换。

以下示例展示了如何调用 Responses API 并使用代码解释器工具:

在 Responses API 中使用代码解释器
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [{
      "type": "code_interpreter",
      "container": { "type": "auto", "memory_limit": "4g" }
    }],
    "instructions": "You are a personal math tutor. When asked a math question, write and run code using the python tool to answer the question.",
    "input": "I need to solve the equation 3x + 11 = 14. Can you help me?"
  }'

我们将此工具称为代码解释器,但模型将其识别为“python tool”。模型通常能够理解提及代码解释器工具的提示,不过,最明确的调用方式是在提示中要求使用“the python tool”。

容器

代码解释器工具需要一个容器对象。容器是完全由沙盒隔离的虚拟机,模型可以在其中运行 Python 代码。容器可以存放您上传的文件或模型生成的文件。

创建容器有两种方式:

  1. 自动模式:如上例所示,您可以在创建新的 Response 对象时,在工具配置中传入 "container": { "type": "auto", "memory_limit": "4g", "file_ids": ["file-1", "file-2"] } 属性。系统会自动创建新容器,或复用模型上下文中先前的 code_interpreter_call 项所使用的活跃容器。如果省略 memory_limit,容器将使用默认的 1 GB 档位。您可以在此 API 请求的输出中查找 code_interpreter_call 项,找到生成或使用的 container_id
  2. 显式模式:您通过 v1/containers 端点显式创建容器,指定所需的 memory_limit(例如 "memory_limit": "4g"),然后将容器的 id 设为 Response 对象中工具配置的 container 值。例如:
显式创建容器
curl https://api.openai.com/v1/containers \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "My Container",
        "memory_limit": "4g"
      }'

# Use the returned container id in the next call:
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [{
      "type": "code_interpreter",
      "container": "cntr_abc123"
    }],
    "tool_choice": "required",
    "input": "use the python tool to calculate what is 4 * 3.82. and then find its square root and then find the square root of that result"
  }'

您可以选择 1g(默认)、4g16g64g。更高档位为会话提供更多内存,并按照代码解释器的内置工具费率计费。无论容器是自动创建的,还是通过容器 API 创建的,所选的 memory_limit 都适用于该容器的整个生命周期。

请注意,自动模式下创建的容器也可以通过 /v1/containers 端点访问。

过期

我们强烈建议您将容器视为临时资源,并将使用此工具时涉及的所有数据存储在您自己的系统中。过期规则如下:

  • 容器如果连续 20 分钟未被使用,就会过期。此后,在 v1/responses 中使用该容器将会失败。您仍然可以查看容器过期时的元数据快照,但与容器关联的所有数据都会从我们的系统中删除,且无法恢复。您应在容器仍处于活跃状态时,下载任何可能需要的文件。
  • 您无法将已过期的容器恢复为活跃状态,而是需要创建新容器并重新上传文件。请注意,旧容器内存中的所有状态(如 Python 对象)都会丢失。
  • 任何容器操作,例如获取容器信息,或在容器中添加或删除文件,都会自动更新容器的 last_active_at 时间。

处理文件

运行代码解释器时,模型可以自行创建文件。例如,如果您要求它绘制图表或创建 CSV,它会直接在您的容器中创建这些图像。随后,模型会在下一条消息的 annotations 中引用这些文件。以下是一个示例:

{
  "id": "msg_682d514e268c8191a89c38ea318446200f2610a7ec781a4f",
  "content": [
    {
      "annotations": [
        {
          "file_id": "cfile_682d514b2e00819184b9b07e13557f82",
          "index": null,
          "type": "container_file_citation",
          "container_id": "cntr_682d513bb0c48191b10bd4f8b0b3312200e64562acc2e0af",
          "end_index": 0,
          "filename": "cfile_682d514b2e00819184b9b07e13557f82.png",
          "start_index": 0
        }
      ],
      "text": "Here is the histogram of the RGB channels for the uploaded image. Each curve represents the distribution of pixel intensities for the red, green, and blue channels. Peaks toward the high end of the intensity scale (right-hand side) suggest a lot of brightness and strong warm tones, matching the orange and light background in the image. If you want a different style of histogram (e.g., overall intensity, or quantized color groups), let me know!",
      "type": "output_text",
      "logprobs": []
    }
  ],
  "role": "assistant",
  "status": "completed",
  "type": "message"
}

您可以调用获取容器文件内容方法,下载这些生成的文件。

模型输入中的所有文件都会自动上传到容器,您无需显式上传。

上传和下载文件

使用创建容器文件向容器中添加新文件。此端点支持 multipart 上传,也接受包含 file_id 的 JSON 请求体。 使用列出容器文件查看容器中的现有文件,并通过获取容器文件内容下载文件的字节数据。

处理引用

模型生成的文件和图像会以助手消息中的注解形式返回。container_file_citation 注解指向容器中创建的文件,其中包含 container_idfile_idfilename。您可以解析这些注解以显示下载链接,或以其他方式处理文件。

支持的文件

文件格式MIME 类型
.ctext/x-c
.cstext/x-csharp
.cpptext/x-c++
.csvtext/csv
.docapplication/msword
.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
.htmltext/html
.javatext/x-java
.jsonapplication/json
.mdtext/markdown
.pdfapplication/pdf
.phptext/x-php
.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation
.pytext/x-python
.pytext/x-script.python
.rbtext/x-ruby
.textext/x-tex
.txttext/plain
.csstext/css
.jstext/javascript
.shapplication/x-sh
.tsapplication/typescript
.csvapplication/csv
.jpegimage/jpeg
.jpgimage/jpeg
.gifimage/gif
.pklapplication/octet-stream
.pngimage/png
.tarapplication/x-tar
.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xmlapplication/xml or "text/xml"
.zipapplication/zip

使用说明

API 可用性 速率限制 说明
每个组织 100 RPM

定价
ZDR 和数据驻留