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。較高級別會為工作階段提供更多 RAM,並依程式碼解譯器的內建工具費率計費。不論容器是自動建立,還是透過容器 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"
}

你可以呼叫取得容器檔案內容方法,下載這些產生的檔案。

所有模型輸入中的檔案都會自動上傳至容器,你無須另外上傳。

上傳與下載檔案

使用建立容器檔案將新檔案加入容器。這個端點接受多部分上傳,或包含 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 與資料駐留