파일 입력
파일 입력
OpenAI 모델은 input_file 항목으로 파일을 받을 수 있어요. Responses API에서 파일을 Base64 인코딩 데이터, Files API(/v1/files)가 반환한 파일 ID, 또는 외부 URL로 보낼 수 있습니다. 파일이 어떤 형태로든 모델 컨텍스트에 들어갈 수 있는 셈이죠.
출처: 공식문서
동작 방식
input_file 처리는 파일 유형에 따라 달라져요.
- PDF 파일:
gpt-4o이후 모델처럼 비전 능력이 있는 모델에서는 API가 텍스트와 페이지 이미지를 모두 추출해 모델로 보냅니다. - PDF가 아닌 문서·텍스트 파일(예:
.docx,.pptx,.txt, 코드 파일): API가 텍스트만 추출해요. - 스프레드시트 파일(예:
.xlsx,.csv,.tsv): API가 스프레드시트 특화 증강(augmentation) 흐름을 실행합니다(아래에서 설명).
작업과 더 잘 맞는 도구가 따로 있을 때는 그걸 쓰는 게 좋아요.
- 대용량 파일을 검색해야 한다면
input_file로 직접 넘기는 대신 File Search를 쓰세요. - 집계·조인·차트·커스텀 계산 같은 상세 분석이 필요한 스프레드시트 중심 작업이라면 Hosted Shell을 쓰는 게 낫습니다.
비-PDF 이미지·차트 제한
PDF가 아닌 파일에서는 API가 포함된 이미지나 차트를 모델 컨텍스트로 추출하지 않아요. 차트·다이어그램 충실도를 지키려면 파일을 먼저 PDF로 변환한 뒤 그 PDF를 input_file로 보내면 됩니다.
스프레드시트 증강 동작 방식
.xlsx, .xls, .csv, .tsv, .iif 같은 스프레드시트 계열 파일에서 input_file은 스프레드시트 특화 증강 과정을 사용해요. 시트 전체를 모델에 넘기는 대신, API가 시트당 처음 1,000행까지 파싱하고 모델 생성 요약·헤더 메타데이터를 더해서, 모델이 데이터의 더 작고 구조화된 뷰로 작업할 수 있게 해 줍니다.
PDF 디테일 수준
Responses API의 PDF 입력에서는 input_file 항목의 선택적 detail 필드를 auto, low, high로 설정해 페이지 이미지 처리 방식을 제어할 수 있어요. 생략하면 기본값은 auto이고, GPT-5.6 이후 모델에서는 auto가 high를, 이전 모델에서는 low를 사용합니다. 입력 토큰을 줄이고 싶으면 low를, 빽빽한 차트·작은 글씨·다이어그램처럼 시각적 디테일이 필요하면 high를 쓰세요.
detail 설정은 PDF 페이지 이미지 처리에만 영향을 주고, PDF에서 추출한 텍스트는 항상 포함돼요. Chat Completions의 파일 입력은 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."
}
]
}
]
}
허용되는 파일 유형
input_file에서 허용하는 대표적인 파일 유형은 아래와 같아요. 확장자·MIME 타입의 전체 목록은 이 페이지 하단에 나옵니다.
| 카테고리 | 대표 확장자 |
|---|---|
| PDF 파일 | .pdf |
| 텍스트·코드 | .txt, .md, .json, .html, .xml, 코드 파일 |
| 리치 문서 | .doc, .docx, .rtf, .odt |
| 프레젠테이션 | .ppt, .pptx |
| 스프레드시트 | .csv, .xls, .xlsx |
파일 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)
import OpenAI from "openai";
const client = new OpenAI();
const response = await 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",
},
],
},
],
});
console.log(response.output_text);
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"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"
}
]
}
]
}'
파일 업로드
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)
curl https://api.openai.com/v1/files \
-H "Authorization: Bearer ***" \
-F purpose="user_data" \
-F file="@draconomicon.pdf"
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"model": "gpt-6-astra",
"input": [
{
"role": "user",
"content": [
{
"type": "input_file",
"file_id": "file-6F2ksmvXxt4VdoqmHRw6kL"
},
{
"type": "input_text",
"text": "What is the first dragon in the book?"
}
]
}
]
}'
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)
import fs from "fs";
import OpenAI from "openai";
const client = new OpenAI();
const data = fs.readFileSync("fixtures/draconomicon.pdf");
const base64String = data.toString("base64");
const response = await client.responses.create({
model: "gpt-6-astra",
input: [
{
role: "user",
content: [
{
type: "input_file",
filename: "draconomicon.pdf",
file_data: `data:application/pdf;base64,${base64String}`,
},
{
type: "input_text",
text: "What is the first dragon in the book?",
},
],
},
],
});
console.log(response.output_text);
사용 시 유의사항
파일 입력을 쓸 때는 이런 제약을 염두에 두세요.
- 토큰 사용량: PDF 파싱은 추출한 텍스트와 페이지 이미지를 모두 컨텍스트에 담아 토큰 사용량이 늘어날 수 있어요. Responses API에서
detail을auto(기본값),low,high로 설정해 PDF 페이지 이미지의 시각적 디테일 양을 제어할 수 있죠. 대규모 배포 전에 가격과 토큰 영향을 검토하세요. - 파일 크기 한도: 단일 요청에 파일을 여러 개 넣을 수 있지만 각 파일은 50MB 미만이어야 해요. 요청의 모든 파일을 합친 한도도 50MB입니다.
- 지원 모델: 텍스트와 페이지 이미지를 모두 포함하는 PDF 파싱은
gpt-4o이후 모델처럼 비전 능력이 있는 모델이 필요해요. - 파일 업로드 목적: 어떤 지원되는 purpose로든 파일을 업로드할 수 있지만, 모델 입력으로 넘길 파일에는
user_data를 쓰세요.
허용되는 파일 유형 전체 목록
각 카테고리별 확장자와 MIME 타입의 전체 목록은 공식 문서 원문의 표를 참고하세요. 주요 카테고리는 PDF, 스프레드시트(Excel 및 CSV/TSV/IIF·Google Sheets), 리치 문서(Word/ODT/RTF·Pages·Google Docs), 프레젠테이션(PowerPoint·Keynote·Google Slides), 텍스트·코드(다양한 언어 형식)로 나뉩니다.
다음 단계
파일 입력을 더 실험하고 싶다면 다음 리소스를 살펴보는 걸 추천해요.
- Playground에서 실험하기: 파일 입력으로 프롬프트를 개발하고 반복할 수 있어요.
- 전체 API 레퍼런스: 더 많은 옵션을 확인하세요.
- 대용량 코퍼스에는 File Search: 전체 파일을 단일 컨텍스트 창에 보내는 대신, 확장 가능한 검색이 필요할 때 덩어리 파일에 대한 검색을 사용하세요.
- 심층 스프레드시트 분석에는 Hosted Shell: 조인·집계·차트 같은 고급 스프레드시트 워크플로에 적합해요.
더 알아보기 (Learn more)
- Responses API 레퍼런스: 파일 입력 옵션 상세
- Files API 레퍼런스: 파일 업로드 방법
- File Search 가이드: 큰 파일 검색