For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Code Interpreter

Permita que os modelos escrevam e executem código Python para resolver problemas.

A ferramenta Code Interpreter permite que os modelos escrevam e executem código Python em um ambiente isolado para resolver problemas complexos em áreas como análise de dados, programação e matemática. Use-a para:

  • Processar arquivos com dados e formatações variados
  • Gerar arquivos com dados e imagens de gráficos
  • Escrever e executar código de forma iterativa para resolver problemas. Por exemplo, um modelo que escreve código que falha ao executar pode continuar reescrevendo e executando esse código até que funcione
  • Aprimorar a inteligência visual dos nossos modelos de raciocínio mais recentes (como o3 e o4-mini). O modelo pode usar esta ferramenta para recortar, aplicar zoom, girar e processar e transformar imagens de outras formas.

Veja um exemplo de chamada à Responses API com uma chamada à ferramenta Code Interpreter:

Use a Responses API com o Code Interpreter
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?"
  }'

Embora chamemos esta ferramenta de Code Interpreter, o modelo a conhece como "ferramenta python". Os modelos geralmente entendem prompts que se referem à ferramenta Code Interpreter, mas a maneira mais explícita de invocá-la é pedir "a ferramenta python" nos seus prompts.

Contêineres

A ferramenta Code Interpreter requer um objeto de contêiner. Um contêiner é uma máquina virtual totalmente isolada na qual o modelo pode executar código Python. Esse contêiner pode conter arquivos que você envia ou que o modelo gera.

Há duas maneiras de criar contêineres:

  1. Modo automático: como no exemplo acima, você pode passar a propriedade "container": { "type": "auto", "memory_limit": "4g", "file_ids": ["file-1", "file-2"] } na configuração da ferramenta ao criar um novo objeto Response. Isso cria automaticamente um novo contêiner ou reutiliza um contêiner ativo que foi usado por um item code_interpreter_call anterior no contexto do modelo. Omitir memory_limit mantém o nível padrão de 1 GB para o contêiner. Procure o item code_interpreter_call na saída dessa solicitação à API para encontrar o container_id que foi gerado ou usado.
  2. Modo explícito: neste modo, você cria um contêiner explicitamente usando o endpoint v1/containers, incluindo o memory_limit necessário (por exemplo, "memory_limit": "4g"), e atribui o id desse contêiner como valor de container na configuração da ferramenta no objeto Response. Por exemplo:
Use a criação explícita de contêineres
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"
  }'

Você pode escolher entre 1g (padrão), 4g, 16g ou 64g. Os níveis superiores oferecem mais RAM para a sessão e são cobrados de acordo com as tarifas de ferramentas integradas do Code Interpreter. O memory_limit selecionado se aplica durante toda a vida útil desse contêiner, independentemente de ele ter sido criado automaticamente ou pela API de contêineres.

Os contêineres criados no modo automático também podem ser acessados pelo endpoint /v1/containers.

Expiração

Recomendamos fortemente que você trate os contêineres como efêmeros e armazene todos os dados relacionados ao uso desta ferramenta nos seus próprios sistemas. Detalhes sobre a expiração:

  • Um contêiner expira se não for usado por 20 minutos. Quando isso acontece, tentar usar o contêiner em v1/responses resultará em falha. Você ainda poderá ver um retrato dos metadados do contêiner no momento da expiração, mas todos os dados associados a ele serão descartados dos nossos sistemas e não poderão ser recuperados. Baixe todos os arquivos de que possa precisar enquanto o contêiner estiver ativo.
  • Não é possível reativar um contêiner expirado. Crie um novo contêiner e envie os arquivos novamente. Todo estado armazenado na memória do contêiner antigo (como objetos Python) será perdido.
  • Qualquer operação no contêiner, como consultá-lo ou adicionar ou excluir arquivos, atualizará automaticamente o horário last_active_at do contêiner.

Trabalhar com arquivos

Ao executar o Code Interpreter, o modelo pode criar seus próprios arquivos. Por exemplo, se você pedir que ele faça um gráfico ou crie um CSV, ele criará essas imagens diretamente no seu contêiner. Ao fazer isso, ele cita esses arquivos em annotations na mensagem seguinte. Veja um exemplo:

{
  "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"
}

Você pode baixar esses arquivos gerados chamando o método obter conteúdo de arquivo do contêiner.

Todos os arquivos na entrada do modelo são enviados automaticamente para o contêiner. Você não precisa enviá-los explicitamente para ele.

Enviar e baixar arquivos

Adicione novos arquivos ao seu contêiner usando Criar arquivo no contêiner. Esse endpoint aceita um upload multipart ou um corpo JSON com um file_id. Liste os arquivos existentes no contêiner com Listar arquivos do contêiner e baixe os bytes usando Recuperar conteúdo de arquivo do contêiner.

Lidar com citações

Os arquivos e as imagens gerados pelo modelo são retornados como anotações na mensagem do assistente. As anotações container_file_citation apontam para arquivos criados no contêiner. Elas incluem container_id, file_id e filename. Você pode interpretar essas anotações para exibir links de download ou processar os arquivos de outras formas.

Arquivos compatíveis

Formato do arquivoTipo 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

Observações de uso

Disponibilidade da API Limites de taxa Observações
100 RPM por organização

Preços
ZDR e residência de dados