오픈AI API를 처음 붙이면 대부분 세 곳에서 멈춘다. 키를 어디에 넣는지, 어떤 모델 이름을 써야 하는지, 그리고 첫 호출에서 401이나 429가 터질 때 뭘 고쳐야 하는지다. 이 글은 파이썬에서 responses.create로 답을 받는 데까지만 짧게 안내하고, 요금 표와 에러 표를 같이 붙여 둔다.
공식 문서는 2026년 11월 기준 developers.openai.com으로 옮겨졌다. 예전 platform.openai.com/docs 링크를 눌러도 새 주소로 넘어가니, 검색해서 나온 옛 예제와 지금 문서가 달라 보이는 건 정상이다.
30초 요약
| 항목 | 내용 |
|---|---|
| 준비물 | 오픈AI 계정, 결제 수단 등록, API 키 1개 |
| 설치 | pip install openai |
| 키 설정 | 환경변수 OPENAI_API_KEY (SDK가 자동으로 읽는다) |
| 첫 호출 | client.responses.create(model=..., input=...) → response.output_text |
| 모델 | gpt-6.2-astra(플래그십) / gpt-6.2-sol(균형) / gpt-6-luna(저비용) |
| 요금 감각 | astra 입력 1M 토큰 $8, 출력 $40 (공식 가격표) |
| 자주 나는 에러 | 401(키 문제), 429(한도·크레딧), 503(모델 과부하) |

그림 1. 키를 넣고 모델을 고르면 호출 한 줄로 끝난다. 모델별 단가는 공식 가격표 기준.
목차
- OpenAI API 시작 전에 확인할 것
- OpenAI Python SDK 설치와 API 키 설정
- 첫 호출 — responses.create로 답 받기
- 모델 선택 — gpt-6.2-astra·sol·luna 차이
- 요금 — 1M 토큰당 가격과 배치 할인
- 대화 이어가기와 스트리밍
- 자주 나는 에러 401·429 해결법
- 내가 막혔던 곳
OpenAI API 시작 전에 확인할 것
API는 챗GPT 유료 구독과 별개로 과금된다. 구독 요금제를 쓰고 있어도 API 호출은 따로 크레딧이 빠져나가므로, 대시보드에서 결제 수단을 먼저 등록해야 한다. 이 구조를 모르고 "플러스 결제했는데 왜 429가 뜨지"로 한 시간을 날리는 경우가 많다.
키는 대시보드의 API keys 메뉴에서 만든다. 만든 직후 한 번만 전체 문자열이 보이고, 이후에는 앞부분만 보인다. 잃어버리면 새로 발급하는 게 빠르다.
키를 코드에 직접 쓰지 않는 이유는 하나다. 커밋 한 번에 키가 깃허브로 나가고, 그 키로 과금이 발생한 사례가 흔하다. 환경변수나 .env 파일에 두고 .gitignore에 넣는 습관을 처음부터 들이는 편이 낫다.
OpenAI Python SDK 설치와 API 키 설정
설치는 한 줄이다. 공식 문서 기준 파이썬 SDK는 pip로 받는다 (Quickstart).
pip install openai
가상환경을 쓰고 있다면 그 안에서 설치한다. 전역 파이썬에 깔면 프로젝트마다 버전이 엉키는 일이 생긴다. 가상환경 만드는 법은 Python 가상환경 venv 만들기에 정리해 뒀다.
키는 터미널 환경변수로 넣는다. macOS나 리눅스는 export, 윈도우 파워셸은 setx를 쓴다.
export OPENAI_API_KEY="sk-..."
setx OPENAI_API_KEY "sk-..."
SDK는 이 환경변수를 자동으로 읽는다. 그래서 코드에 OpenAI()처럼 괄호만 열어 두면 키를 따로 넘기지 않아도 된다. .env 파일로 관리하고 싶으면 python-dotenv를 같이 쓰고, 스크립트 맨 위에서 load_dotenv()를 호출하면 된다.
첫 호출 — responses.create로 답 받기
지금 문서의 기본 예제는 Responses API다. 모델 이름과 입력을 넘기고, 응답 본문은 output_text에서 꺼낸다.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6.2-astra",
input="파이썬에서 리스트와 튜플의 차이를 한 문단으로 설명해줘.",
)
print(response.output_text)
print(response)로 객체 전체를 찍어 보면 이벤트와 메타데이터가 잔뜩 나온다. 처음엔 이걸 보며 겁먹기 쉬운데, 실제로 필요한 건 output_text 한 줄인 경우가 대부분이다.
역할을 나눠 보내고 싶으면 input에 메시지 리스트를 넣는다. 시스템 지시문은 instructions로 따로 넘길 수도 있다.
response = client.responses.create(
model="gpt-6.2-sol",
instructions="너는 파이썬 강사다. 초보자에게 반말로 짧게 답한다.",
input=[
{"role": "user", "content": "딕셔너리 컴프리헨션 예시 하나만 보여줘."},
],
)
토큰이 무엇이고 왜 요금과 연결되는지는 토큰(token)이란에 따로 적어 두었다. 프롬프트 문장을 다듬는 쪽이 궁금하면 프롬프트 작성법을 같이 보면 된다.
모델 선택 — gpt-6.2-astra·sol·luna 차이
문서는 용도별로 세 갈래를 권한다. 복잡한 추론과 코딩은 gpt-6.2-astra, 지능과 비용의 균형은 gpt-6.2-sol, 대량·저비용 작업은 gpt-6-luna다 (Models). 세 모델 모두 텍스트와 이미지 입력, 텍스트 출력, 다국어를 지원한다.
| 모델 | 문서상 위치 | 입력 1M 토큰 | 출력 1M 토큰 | 캐시 입력 1M 토큰 |
|---|---|---|---|---|
| gpt-6.2-astra | 플래그십, 복잡한 추론·코딩 | $8.00 | $40.00 | $0.40 |
| gpt-6.2-sol | 지능·비용 균형 | $2.00 | $10.00 | $0.10 |
| gpt-6-luna | 저비용·대량 처리 | $0.10 | $0.50 | $0.01 |

그림 2. 설치·첫 호출 순서와 1M 토큰 단가표. 출력 단가가 입력의 5배다.
가격은 모두 공식 가격표의 Standard, 짧은 컨텍스트 기준이다. 표를 보면 출력 단가가 입력 단가의 다섯 배라는 점이 눈에 들어온다. 같은 질문이라도 답을 길게 늘어놓게 만들면 비용이 훨씬 빨리 오른다.
처음 붙이는 단계라면 gpt-6.2-sol로 시작해서 품질이 부족할 때 astra로 올리는 편이 안전하다. 반대로 분류, 요약, 태깅처럼 정답이 뻔한 작업을 하루 수만 건 돌린다면 luna 쪽이 맞다.
요금 — 1M 토큰당 가격과 배치 할인
요금은 토큰 단위로 매겨지고, 입력과 출력이 따로 계산된다. 1M 토큰은 한글 기준으로 책 한두 권 분량이니, 짧은 챗봇 하나를 돌리는 정도로는 몇 달러 안에서 끝나는 경우가 많다.
비용을 줄이는 방법은 크게 두 가지다. 프롬프트 앞부분을 고정해 캐시 입력 단가(입력가의 5%)를 적용받는 것, 그리고 급하지 않은 작업을 Batch로 돌리는 것이다. Batch 가격은 Standard의 절반이다. astra 기준 입력 $4.00, 출력 $20.00이고, luna는 입력 $0.05, 출력 $0.25다 (가격표).
| 모델 | Standard 입력 | Batch 입력 | Standard 출력 | Batch 출력 |
|---|---|---|---|---|
| gpt-6.2-astra | $8.00 | $4.00 | $40.00 | $20.00 |
| gpt-6.2-sol | $2.00 | $1.00 | $10.00 | $5.00 |
| gpt-6-luna | $0.10 | $0.05 | $0.50 | $0.25 |
실제 지출은 대시보드 Usage 화면에서 확인한다. 호출마다 남는 사용량을 앱 안에서 직접 집계하지 않고, 대시보드 숫자를 기준으로 삼는 편이 계산 실수가 적다.
대화 이어가기와 스트리밍
챗봇처럼 앞 대화를 기억해야 한다면 두 방식이 있다. 대화 전체를 매번 input에 다시 넣는 방법과, 이전 응답 ID를 넘기는 방법이다. 후자는 previous_response_id를 쓰고, 저장을 원하면 store를 켠다 (Conversation state).
first = client.responses.create(
model="gpt-6.2-sol",
input="파이썬에서 예외 처리를 왜 쓰는지 한 줄로 알려줘.",
store=True,
)
second = client.responses.create(
model="gpt-6.2-sol",
previous_response_id=first.id,
input=[{"role": "user", "content": "방금 답을 초등학생에게 설명하듯 바꿔줘."}],
)
print(second.output_text)
답이 길어서 기다리기 답답하면 stream=True를 준다. 이벤트가 하나씩 도착하므로 화면에 타이핑되듯 출력할 수 있다 (Streaming).
stream = client.responses.create(
model="gpt-6.2-sol",
input="터미널에서 자주 쓰는 단축키 다섯 개만 알려줘.",
stream=True,
)
for event in stream:
print(event)
처음엔 이벤트 종류가 많아 보이지만, 텍스트 조각만 받고 싶으면 이벤트 안의 타입을 확인해 델타만 골라 출력하면 된다. 스트리밍은 체감 속도를 바꾸는 기능이지, 토큰 요금을 깎아 주는 기능은 아니다.
자주 나는 에러 401·429 해결법
에러 코드별 원인과 조치는 공식 Error codes 문서에 정리돼 있다. 실제로 가장 자주 만나는 네 가지를 표로 줄였다.
| 코드 | 메시지 | 원인 | 조치 |
|---|---|---|---|
| 401 | Incorrect API key provided | 키 오타, 폐기된 키, 다른 조직 키 | 키 재발급 후 환경변수 다시 설정 |
| 401 | You must be a member of an organization | 조직에 속하지 않은 계정 | 조직 초대 수락 또는 관리자에게 요청 |
| 429 | Rate limit reached for requests | 짧은 시간에 요청 과다 | Retry-After 헤더만큼 대기 후 재시도 |
| 429 | Credit balance exhausted | 선불 크레딧 소진 | 대시보드에서 크레딧 충전 |
| 503 | Model temporarily overloaded | 해당 모델 일시 과부하 | Retry-After 확인 후 재시도 |
429는 두 종류를 구분해야 한다. 크레딧이 없어서 나는 429는 몇 번을 재시도해도 그대로다. 반면 요청 속도 때문에 나는 429는 잠깐 기다리면 풀린다. 에러 본문의 code 값을 보면 credit_balance_exhausted인지 rate_limit_error인지 구분된다.
재시도를 코드로 넣을 때는 지수 백오프를 같이 쓰는 게 좋다. 1초, 2초, 4초처럼 간격을 늘리면서 최대 세 번 정도만 시도하고, 그래도 안 되면 로그를 남기고 멈추는 편이 안전하다.
내가 막혔던 곳
처음 API를 붙일 때 검색으로 나온 예제가 전부 client.chat.completions.create 기준이었다. 그대로 붙여 넣으면 모델 이름이 맞지 않는다는 에러부터 시작해서, 응답에서 텍스트를 꺼내는 위치도 지금 문서와 달라 헷갈렸다. 지금 문서의 기본 경로는 responses.create이고 본문은 output_text 하나로 끝난다.
두 번째로 막힌 곳은 환경변수였다. 터미널에서 export한 키가 IDE 안에서는 안 잡혔다. 에디터를 완전히 종료했다가 다시 열어야 환경변수를 새로 읽는 경우가 있다. 이걸 모르고 코드를 계속 고치며 401을 반복했다.
세 번째는 결제 등록이었다. 키는 멀쩡한데 429가 떠서 코드를 의심했는데, 원인은 크레딧이 0이었던 것이다. 429를 보면 코드보다 대시보드 Billing을 먼저 여는 습관이 생겼다.
이 세 가지를 겪고 나니, 새 프로젝트를 시작할 때 확인 순서가 고정됐다. 결제 등록 → 키 발급 → 환경변수 확인 → responses.create 한 번 호출. 이 순서만 지키면 초반 삽질이 거의 사라진다.
참고 자료
같이 보면 좋은 글: Claude API 사용법 (Python) · RAG가 뭐야 (검색증강생성)
'IT' 카테고리의 다른 글
| 어사이드 vs 에고 라이트 vs 핸들러스 — 내 브라우저를 AI에게 맡기는 3가지 방법 (0) | 2026.11.20 |
|---|---|
| 에고 라이트(ego lite) 사용법 — 클로드코드가 내 로그인 브라우저를 쓴다 (0) | 2026.11.20 |
| 핸들러스(Handlus) MCP 사용법 — 클로드코드가 내 브라우저를 직접 조작한다 (0) | 2026.11.20 |
| Claude MCP 설정 방법 — claude mcp add로 서버 붙이고 /mcp로 확인하기 (0) | 2026.11.19 |
| npm 설치 오류 해결 — command not found·EACCES 증상별 원인 (0) | 2026.11.18 |


















