For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

코드 인터프리터

모델이 Python 코드를 작성하고 실행해 문제를 해결하도록 하세요.

코드 인터프리터를 사용하면 모델이 샌드박스 환경에서 Python 코드를 작성하고 실행해 데이터 분석, 코딩, 수학 등 여러 분야의 복잡한 문제를 해결할 수 있습니다. 다음과 같은 작업에 활용하세요.

  • 다양한 데이터와 서식이 포함된 파일 처리
  • 데이터와 그래프 이미지가 담긴 파일 생성
  • 코드를 반복해서 작성하고 실행하며 문제 해결. 예를 들어 모델이 작성한 코드가 실행에 실패하면 성공할 때까지 코드를 수정하고 다시 실행할 수 있습니다.
  • gpt-6-astra 모델로 이미지 분석. 코드 인터프리터는 Python으로 이미지를 자르거나 확대하거나 회전할 수 있으며, 개별 픽셀의 값도 읽을 수 있습니다.

다음은 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")을 전달한 다음, Response 객체의 도구 설정에서 생성된 컨테이너의 id를 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(기본값), 4g, 16g, 64g 중에서 선택할 수 있습니다. 상위 등급을 선택하면 세션에서 사용할 수 있는 RAM이 늘어나며, 코드 인터프리터의 기본 제공 도구 요금이 적용됩니다. 컨테이너를 자동으로 생성했든 컨테이너 API로 생성했든 선택한 memory_limit은 해당 컨테이너의 수명 전체에 적용됩니다.

자동 모드에서 생성한 컨테이너에도 /v1/containers 엔드포인트로 접근할 수 있습니다.

만료

컨테이너는 임시 환경으로 취급하고, 이 도구 사용과 관련된 모든 데이터는 자체 시스템에 저장할 것을 강력히 권장합니다. 컨테이너 만료와 관련해 다음 사항에 유의하세요.

  • 컨테이너를 20분 동안 사용하지 않으면 만료됩니다. 이후 v1/responses에서 해당 컨테이너를 사용하려고 하면 요청이 실패합니다. 만료 시점의 컨테이너 메타데이터 스냅샷은 계속 확인할 수 있지만, 컨테이너와 관련된 모든 데이터는 OpenAI 시스템에서 삭제되며 복구할 수 없습니다. 나중에 필요할 수 있는 파일은 컨테이너가 활성 상태일 때 다운로드하세요.
  • 만료된 컨테이너는 다시 활성화할 수 없습니다. 새 컨테이너를 만들고 파일을 다시 업로드하세요. Python 객체 등 기존 컨테이너의 메모리에 있던 상태는 모두 사라집니다.
  • 컨테이너 조회, 파일 추가 또는 삭제 등 컨테이너에서 작업을 수행할 때마다 해당 컨테이너의 last_active_at 값이 자동으로 갱신됩니다.

파일 작업

코드 인터프리터를 실행하면 모델이 직접 파일을 만들 수 있습니다. 예를 들어 그래프를 그리거나 CSV를 만들어 달라고 요청하면 모델이 그래프 이미지나 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_id, file_id, filename을 포함합니다. 이 주석을 파싱해 다운로드 링크를 표시하거나 파일을 다른 방식으로 처리할 수 있습니다.

지원되는 파일 형식

파일 형식 MIME 유형
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv text/csv
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.tex text/x-tex
.txt text/plain
.css text/css
.js text/javascript
.sh application/x-sh
.ts application/typescript
.csv application/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif image/gif
.pkl application/octet-stream
.png image/png
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml or "text/xml"
.zip application/zip

사용 시 참고 사항

API 지원 여부요청 한도참고 사항
조직당 분당 요청 100회

요금
ZDR 및 데이터 레지던시