파일 입력

파일 입력 (File inputs)

파일 입력 지원은 API 엔드포인트에 따라 달라요. Responses API는 아래 나열된 파일 유형을 input_file 항목으로 받아요. Chat Completions는 file 콘텐츠 파트로 PDF 파일만 받아요.

출처: 문서

본문

비-PDF 파일 입력에는 Responses API를 사용하세요. Chat Completions에서 파일 텍스트를 사용하려면 애플리케이션에서 파일을 읽고 그 내용을 text 콘텐츠 파트로 보내세요.

작동 방식

Responses API에서 input_file 처리는 파일 유형에 따라 달라요.

• PDF 파일: gpt-4o 이후 모델 같은 비전 기능이 있는 모델에서 API가 텍스트와 페이지 이미지를 모두 추출해 모델에 보내요.
• 비-PDF 문서·텍스트 파일(예: .docx, .pptx, .txt, 코드 파일): API가 텍스트만 추출해요.
• 스프레드시트 파일(예: .xlsx, .csv, .tsv): API가 스프레드시트 특정 증강 흐름(아래 설명)을 실행해요.

작업에 더 잘 맞는다면 관련 도구를 사용하세요.

• 큰 파일에 대한 검색은 직접 input_file로 넘기는 대신 File Search를 쓰세요.
• 집계, 조인, 차트, 사용자 지정 계산 같은 상세 분석이 필요한 스프레드시트 중심 작업은 Hosted Shell을 쓰세요.

비-PDF 이미지·차트 제한

비-PDF 파일은 Responses API가 포함된 이미지·차트를 모델 컨텍스트로 추출하지 않아요.

차트·다이어그램 충실도를 보존하려면 먼저 파일을 PDF로 변환한 뒤 그 PDF를 input_file로 보내세요.

스프레드시트 증강 작동 방식

.xlsx, .xls, .csv, .tsv, .iif 같은 스프레드시트류 파일에 대해 Responses API는 스프레드시트 특정 증강 과정을 사용해요.

전체 시트를 모델에 넘기는 대신, API가 시트당 최대 처음 1,000행을 파싱하고 모델 생성 요약·헤더 메타데이터를 추가해 모델이 더 작고 구조화된 데이터 뷰로 작업하게 해요.

PDF detail 수준

Responses API의 PDF 입력에서 input_file 항목의 선택적 detail 필드를 auto, low, high로 설정해 페이지 이미지 처리 방식을 제어할 수 있어요. 생략하면 detail이 auto로 기본 설정돼요. GPT-5.6 이후 모델은 auto가 high를, 이전 모델은 low를 사용해요. 입력 토큰을 줄이려면 low를, 밀집한 차트·작은 인쇄·다이어그램 같은 시각적 디테일이 더 필요하면 high를 쓰세요.

detail 설정은 PDF 페이지 이미지 처리에만 영향을 줘요. PDF에서 추출된 텍스트는 여전히 포함돼요. Chat Completions 파일 입력은 detail을 지원하지 않아요.

명시적 high detail의 최소 Responses API 요청 본문:

{
  "model": "gpt-4.1",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_file",
          "filename": "document.pdf",
          "file_data": "data:application/pdf;base64,...",
          "detail": "high"
        },
        {
          "type": "input_text",
          "text": "Summarize this document."
        }
      ]
    }
  ]
}

허용되는 파일 유형

다음 표는 Responses API가 input_file 항목으로 받는 흔한 파일 유형을 나열해요. 전체 확장자·MIME 유형 목록은 이 페이지 뒤에 있어요. Chat Completions는 file_data와 file_id 모두 .pdf(application/pdf)만 지원해요.

파일 URL

외부 URL을 연결해 파일 입력을 제공할 수 있어요.

외부 파일 URL 사용:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Analyze the letter and provide a summary of the key points.",
                },
                {
                    "type": "input_file",
                    "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf",
                },
            ],
        }
    ],
)

print(response.output_text)

(JavaScript, Go, Java, C#, Ruby, curl 예시도 input_file 항목에 file_url을 전달하는 같은 패턴입니다.)

파일 업로드

다음 예시는 Files API로 파일을 업로드한 뒤 그 파일 ID를 모델 요청에서 참조해요.

파일 업로드:

from openai import OpenAI

client = OpenAI()

file = client.files.create(file=open("draconomicon.pdf", "rb"), purpose="user_data")

response = client.responses.create(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_id": file.id,
                },
                {
                    "type": "input_text",
                    "text": "What is the first dragon in the book?",
                },
            ],
        }
    ],
)

print(response.output_text)

(JavaScript, Go, Java, C#, Ruby, curl 예시도 purpose: "user_data"로 파일을 업로드하고 file_id를 참조하는 같은 패턴입니다.)

Base64 인코딩 파일

파일 입력을 Base64 인코딩 파일 데이터로 보낼 수도 있어요.

Base64 인코딩 파일 전송:

import base64
from openai import OpenAI

client = OpenAI()

with open("draconomicon.pdf", "rb") as f:
    data = f.read()

base64_string = base64.b64encode(data).decode("utf-8")

response = client.responses.create(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "draconomicon.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}",
                },
                {
                    "type": "input_text",
                    "text": "What is the first dragon in the book?",
                },
            ],
        }
    ],
)

print(response.output_text)

(JavaScript, Go, Java, C#, Ruby, curl 예시도 file_data에 data:application/pdf;base64,... 형식을 쓰는 같은 패턴입니다.)

사용 고려 사항

파일 입력을 쓸 때 다음 제약을 염두에 두세요.

• 토큰 사용: PDF 파싱은 추출된 텍스트와 페이지 이미지를 모두 컨텍스트에 넣어 토큰 사용을 늘릴 수 있어요. Responses API에서 detail을 auto(기본값), low, high로 설정해 PDF 페이지 이미지의 시각적 디테일 양을 제어할 수 있어요. 대규모 배포 전에 가격과 토큰 영향을 검토하세요. 가격에 대해 더 보기.
• 파일 크기 제한: 단일 요청에 파일을 여러 개 포함할 수 있지만 각 파일은 50 MB 미만이어야 해요. 요청의 모든 파일을 합친 한도도 50 MB예요.
• 지원 모델: 텍스트와 페이지 이미지를 포함하는 PDF 파싱은 gpt-4o 이후 모델 같은 비전 기능이 있는 모델이 필요해요.
• 파일 업로드 목적: 어떤 지원 purpose로든 파일을 업로드할 수 있지만, 모델 입력으로 넘길 파일에는 user_data를 쓰세요.

허용되는 파일 유형 전체 목록

이 목록은 Responses API에 적용돼요. Chat Completions는 file_data와 file_id 모두 .pdf(application/pdf)만 지원해요.

다음 단계

다음을 탐구해 보세요.

• Playground에서 파일 입력 실험 — 파일 입력으로 프롬프트를 개발·반복.
• 전체 API 레퍼런스 — 더 많은 옵션 확인.
• 큰 말뭉치에 File Search 사용 — 전체 파일을 단일 컨텍스트 창에 보내는 대신 청크 파일에 걸친 확장 가능한 검색 필요 시.
• 심층 스프레드시트 분석에 Hosted Shell 사용 — 조인, 집계, 차트 같은 고급 스프레드시트 워크플로.

더 알아보기 (Learn more)

관련 문서: File Search, 이미지와 비전, Files API 레퍼런스를 함께 보면 좋아요.