AI & ML

OpenAI API Python 챗봇 가이드 — Responses API 기준

junetapa 2026. 10. 30 업데이트 16 min read

OpenAI API를 Python으로 불러 챗봇을 만드는 방법을 2026년 10월 기준으로 정리했다. 지금 OpenAI 문서가 새 프로젝트에 권하는 것은 Responses API이고, Python SDK는 openai 3.41.0이다. 설치와 키 관리, 첫 호출, 모델 고르기, 대화 상태 잇기, 스트리밍, 함수 호출, 임베딩, 오류·재시도까지 순서대로 따라가며 마지막에 바로 돌려 볼 수 있는 챗봇 코드를 붙였다. 모델·가격·SDK 동작은 2026년 10월 29~30일 developers.openai.com·PyPI·SDK 저장소에서 다시 확인했다.

2026년 10월 다시 씀

예전 판은 GPT-5.6(Sol·Terra·Luna)을 주력으로, Chat Completions를 기본 예제로 적었다. 지금 OpenAI 모델 문서의 대표 모델 칸은 GPT-6 Astra·GPT-6.1 Sol·GPT-6.1 Terra·GPT-6 Luna이고, «2026년 내 종료 예정»이라 적었던 Assistants API는 2026년 8월 26일 종료됐다. 예제를 Responses API 기준으로 바꾸고, 예전 모델 단가표와 단가 그림, «비용 90% 이상 절감»·«수분 내로 악용» 같은 근거를 다시 확인할 수 없는 문장, «직접 만들어본 기록» 같은 표현은 뺐다.

왜 API로 직접 만드나

채팅 화면에서 묻고 답을 복사하는 방식으로는 내 서비스 안에 AI를 넣을 수 없다. API를 쓰면 지시문(instructions)으로 답하는 방식을 정하고, 응답을 JSON 모양으로 받고, 내 코드의 함수를 모델이 부르게 할 수 있다. 사내 메신저 봇, 문의 분류기, 문서 요약 파이프라인처럼 «사람이 창을 열지 않아도 도는 것»은 API로만 만든다.

  • 서비스 통합 — 웹앱·앱 안에서 사용자가 바로 대화한다.
  • 형식 통제 — 구조화 출력과 함수 호출로 응답을 코드가 다루기 쉬운 모양으로 받는다.
  • 비용 통제 — 쓴 토큰만큼 내고, 일마다 다른 모델을 고를 수 있다. 같은 회사 모델 사이에서도 출력 단가가 100배 차이 난다(아래 표).

설치와 API 키 관리

SDK 설치

공식 Python 라이브러리는 PyPI의 openai이고, 2026년 10월 29일 기준 최신 판은 3.41.0, Python 3.10 이상이 필요하다. 옛 자료의 openai.ChatCompletion.create()는 0.x 시절 문법이라 지금은 동작하지 않는다. from openai import OpenAI로 클라이언트를 만들어 쓴다.

터미널
# 가상환경 (권장)
python -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install openai python-dotenv
python -c "import openai; print(openai.__version__)"

API 키는 환경 변수로

SDK는 OPENAI_API_KEY 환경 변수를 자동으로 읽는다. SDK README도 키를 코드에 적지 말고 .env 같은 곳에서 읽으라고 권한다. .env는 반드시 .gitignore에 넣고, 키가 저장소에 올라갔다면 바로 폐기하고 새로 만든다.

Python
# .env (프로젝트 루트 · 저장소에 올리지 않음)
OPENAI_API_KEY=sk-proj-...

# main.py
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()          # .env 를 환경 변수로 읽음
client = OpenAI()      # OPENAI_API_KEY 를 자동으로 사용

첫 호출 — Responses API와 Chat Completions

OpenAI 마이그레이션 문서는 «Chat Completions는 계속 지원되지만 새 프로젝트에는 Responses를 권한다»고 적는다. SDK README도 Responses를 기본(primary) API로, Chat Completions를 무기한 지원되는 이전 표준으로 소개한다. 같은 질문을 두 방식으로 보내 보면 차이가 바로 보인다.

Python — Responses API
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.1-terra",
    instructions="한국어로 짧고 정확하게 답하는 파이썬 도우미다.",
    input="리스트에서 중복을 없애면서 순서를 지키는 방법은?",
)

print(response.output_text)          # 텍스트만 한 번에
print(response.usage)                # 토큰 사용량
Python — Chat Completions (기존 코드)
completion = client.chat.completions.create(
    model="gpt-6.1-terra",
    messages=[
        {"role": "developer", "content": "한국어로 짧고 정확하게 답하는 파이썬 도우미다."},
        {"role": "user", "content": "리스트에서 중복을 없애면서 순서를 지키는 방법은?"},
    ],
)

print(completion.choices[0].message.content)
Chat CompletionsResponses API메모
system·developer 메시지instructions이전 대화를 이어도 instructions는 따라오지 않아 요청마다 넣는다
messages[]input(문자열 또는 항목 배열)user 메시지는 role: "user" 항목으로
choices[0].message.contentoutput_text응답은 output 항목 배열로 오고, 텍스트만 모은 것이 output_text
response_formattext.format구조화 출력 설정 위치가 바뀜
n(여러 답)없음답이 여러 개 필요하면 요청을 나눠 보냄
함수 정의(바깥 태그)함수 정의(안쪽 태그), 기본 strict 시도호출과 결과가 function_call·function_call_output 항목으로 분리
시스템과 유저, 어시스턴트 세 가지 메시지 역할의 쓰임을 정리한 도해
역할 구분은 그대로다. Responses에서는 시스템 몫이 instructions로 올라간다.

모델 고르기 — Astra·Sol·Terra·Luna

2026년 10월 30일 OpenAI 모델 문서의 대표 모델 칸은 아래 넷이다. 가격은 100만 토큰당 달러이고, 넷 다 컨텍스트 105만 토큰, 최대 출력 12만 8천 토큰이다. 결제 전에는 공식 가격 페이지를 다시 확인하자.

모델 ID입력출력문서가 권하는 쓰임
gpt-6-astra$10$50복잡한 추론·코딩용 대표 모델(시작점으로 권함)
gpt-6.1-sol$2$10성능과 비용의 균형
gpt-6.1-terra$1$5더 가벼운 일반 작업
gpt-6-luna$0.10$0.50비용에 민감한 대량 처리

이 글의 예제는 일반 대화용으로 gpt-6.1-terra를 쓴다. 답의 질이 모자라면 Sol, 분류·태그 붙이기처럼 대량으로 돌리는 일은 Luna로 내려 본다. 예전 판의 gpt-5.6-sol·terra·luna는 지금 모델 문서의 대표 칸에 없으니, 새 코드에서는 위 ID로 바꿔 시험한다. 같은 일을 Claude로 만든다면 Claude API Python 가이드와 나란히 보면 구조가 거의 같다는 것을 알 수 있다. 로컬 모델을 같은 코드로 부르고 싶다면 OpenAI 호환 주소를 주는 Ollama 설치·활용 가이드를 참고한다.

모델 등급과 히스토리 길이, 스트리밍, 캐시 등 토큰 비용을 줄이는 방법을 정리한 도해
가장 큰 절감은 코드가 아니라 «어느 모델을 쓰는가»에서 나온다.

대화 상태 잇기 — 세 가지 방법

API 요청 하나하나는 서로를 모른다. «방금 그거 고쳐 줘»가 통하려면 앞 대화를 어떤 식으로든 다시 넘겨야 한다. Responses API 문서가 소개하는 방법은 세 가지다.

방법어떻게알아 둘 것
previous_response_id직전 응답 id를 넘기면 OpenAI가 앞 맥락을 이어 줌instructions는 매번 다시 · 앞 토큰은 입력으로 과금 · 응답은 기본 저장(store)
직접 관리앞 응답의 output 항목을 다음 input에 붙임오래된 부분을 잘라 내는 일을 내가 정함 · store: false와 함께 씀
Conversations API대화 객체를 만들어 계속 씀여러 기기·세션에서 같은 대화를 이어야 할 때
Python — previous_response_id
INSTR = "한국어로 답하는 파이썬 튜터다. 예시 코드는 짧게."

first = client.responses.create(
    model="gpt-6.1-terra",
    instructions=INSTR,
    input="리스트 컴프리헨션이 뭐야?",
)
print(first.output_text)

second = client.responses.create(
    model="gpt-6.1-terra",
    instructions=INSTR,                 # 이어지지 않으므로 다시 넣음
    previous_response_id=first.id,      # 앞 대화 잇기
    input="방금 설명한 걸로 짝수만 고르는 예를 보여 줘",
)
print(second.output_text)

대화가 길어질수록 앞 토큰이 매번 입력으로 다시 계산된다. 상담 봇처럼 대화가 길게 이어지는 서비스라면 일정 길이를 넘을 때 앞부분을 요약해 새 대화로 시작하거나, 직접 관리 방식으로 오래된 항목을 덜어 내는 규칙을 처음부터 넣어 두자.

스트리밍 — 이벤트로 받기

긴 답을 다 만들 때까지 기다리면 화면이 한동안 비어 있다. stream=True로 보내면 응답이 이벤트로 나뉘어 온다. 공식 스트리밍 문서가 짚는 핵심 이벤트는 response.created, 글자가 생길 때마다 오는 response.output_text.delta, 끝을 알리는 response.completed, 그리고 error다.

Python
stream = client.responses.create(
    model="gpt-6.1-terra",
    input="파이썬 가상환경을 쓰는 이유를 세 줄로",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)     # 조각을 바로 출력
    elif event.type == "response.completed":
        print()                                      # 끝
    elif event.type == "error":
        print("\n[오류]", event)

웹 서비스에서는 delta 조각을 Server-Sent Events로 브라우저에 흘려 보내는 구성이 흔하다. 공식 문서는 부분 출력은 내용 검토(모더레이션)가 더 어렵다고 짚는다. 사용자에게 공개되는 봇이라면 완성된 답을 한 번 더 검사하는 단계를 따로 두는 편이 안전하다.

함수 호출과 임베딩

함수 호출 — 다섯 단계 고리

모델이 «날씨를 알아봐야겠다»고 판단하면 내 함수를 불러 달라는 항목을 돌려준다. 공식 문서의 순서는 ① tools와 함께 요청 → ② function_call 항목 받기 → ③ 내 코드 실행 → ④ function_call_output 항목으로 결과 돌려주기 → ⑤ 모델이 또 부르면 반복, 아니면 최종 답이다. 호출과 결과는 call_id로 짝을 맞춘다.

Python
import json

tools = [{
    "type": "function",
    "name": "get_order_status",
    "description": "주문 번호로 배송 상태를 조회한다.",
    "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
        "additionalProperties": False,   # strict 모드 조건
    },
    "strict": True,
}]

def get_order_status(order_id: str) -> dict:
    return {"order_id": order_id, "status": "배송 중"}   # 실제로는 DB 조회

items = [{"role": "user", "content": "주문 A-1024 어디쯤 왔어?"}]
resp = client.responses.create(model="gpt-6.1-terra", input=items, tools=tools)

items += resp.output                              # 모델 출력 항목을 먼저 넣고
for it in resp.output:
    if it.type == "function_call":
        result = get_order_status(**json.loads(it.arguments))
        items.append({"type": "function_call_output",
                      "call_id": it.call_id,
                      "output": json.dumps(result, ensure_ascii=False)})

final = client.responses.create(model="gpt-6.1-terra", input=items, tools=tools)
print(final.output_text)

strict 모드를 쓰려면 parameters 안의 모든 객체에 additionalProperties: false를 두고, properties의 모든 필드를 required에 적어야 한다. 빠져도 되는 값은 타입에 null을 더해 표시한다. Responses API는 strict를 빼면 strict 모드를 먼저 시도하고, 스키마가 맞지 않으면 일반 모드로 돌아간다.

임베딩 — 의미로 찾기

문서 검색형 챗봇(RAG)을 만들 때는 문장을 숫자 벡터로 바꾸는 임베딩이 필요하다. 임베딩 문서의 현재 모델은 text-embedding-3-small(기본 1,536차원)과 text-embedding-3-large(기본 3,072차원)이고, 둘 다 입력 최대 8,192토큰이다. dimensions로 벡터를 짧게 받을 수 있어 저장 공간이 빠듯한 벡터 DB에 맞추기 좋다.

Python
emb = client.embeddings.create(
    model="text-embedding-3-small",
    input=["환불은 수령 후 7일 안에 신청", "배송은 영업일 기준 2~3일"],
    dimensions=512,          # 필요하면 짧게 (직접 자르면 다시 정규화해야 함)
)
vectors = [d.embedding for d in emb.data]

음성을 글로 바꿔 챗봇 입력으로 쓰려면 Whisper API 활용법에 받아쓰기 모델 전환 일정과 함께 정리해 두었다.

돌려 보는 챗봇 코드

터미널에서 바로 대화해 볼 수 있는 최소 챗봇이다. previous_response_id로 대화를 잇고, 스트리밍으로 출력하며, 대화가 길어지면 새로 시작하는 장치를 넣었다.

Python — chatbot.py
from dotenv import load_dotenv
from openai import OpenAI, APIError

load_dotenv()
client = OpenAI(timeout=60.0, max_retries=2)

MODEL = "gpt-6.1-terra"
INSTR = "한국어로 답하는 친절한 개발 도우미다. 모르면 모른다고 말한다."
MAX_TURNS = 20          # 이만큼 이어지면 새 대화로

def ask(text, prev_id):
    stream = client.responses.create(
        model=MODEL, instructions=INSTR, input=text,
        previous_response_id=prev_id, stream=True,
    )
    new_id = None
    for ev in stream:
        if ev.type == "response.output_text.delta":
            print(ev.delta, end="", flush=True)
        elif ev.type == "response.completed":
            new_id = ev.response.id
    print()
    return new_id

def main():
    prev_id, turns = None, 0
    print("대화를 시작합니다. 끝내려면 quit, 새로 시작하려면 reset")
    while True:
        text = input("\n나: ").strip()
        if not text:
            continue
        if text == "quit":
            break
        if text == "reset" or turns >= MAX_TURNS:
            prev_id, turns = None, 0
            print("(새 대화)")
            if text == "reset":
                continue
        try:
            print("봇: ", end="")
            prev_id = ask(text, prev_id) or prev_id
            turns += 1
        except APIError as e:
            print(f"\n[API 오류] {e}")

if __name__ == "__main__":
    main()

오류·재시도·타임아웃

운영에서 문제를 일으키는 것은 대개 모델보다 네트워크·한도·시간이다. openai Python SDK README가 정리한 기본 동작은 이렇다.

상황SDK 동작·예외할 일
연결 실패APIConnectionError 계열기본 재시도에 맡기고, 반복되면 사용자에게 다시 시도 안내
속도 제한(429)RateLimitError기본 2번 재시도 · 계속되면 요청량을 줄이거나 큐로 분산
그 밖의 오류 상태 코드APIStatusError(status_code·response 포함)4xx는 요청을 고치고, 5xx는 재시도 뒤 기록
시간 초과APITimeoutError · 기본 타임아웃 10분 · 기본 2번 재시도챗봇은 timeout을 짧게(예: 60초)
모든 오류의 부모APIError마지막 안전망으로 한 번에 잡기

재시도 대상은 연결 오류와 408·409·429·500 이상 응답이고, 요청 본문을 안전하게 다시 보낼 수 있을 때만 재시도한다. 횟수는 클라이언트나 요청 단위의 max_retries로 바꾸고, 0이면 끈다. 요청 하나만 설정을 바꾸려면 client.with_options(timeout=20.0).responses.create(...)처럼 쓴다. 웹 서버 안에서 쓴다면 AsyncOpenAI를 쓰고 호출마다 await를 붙인다.

재시도와 타임아웃, 사용량 제한, 키 보안 등 운영 체크리스트를 정리한 도해
프로덕션에서 터지는 것은 대개 모델이 아니라 이 네 가지다.

운영 체크리스트

  • 키 — 환경 변수로만, 저장소·클라이언트 코드에 넣지 않기. 프런트에서 직접 부르지 말고 내 서버를 거치게 한다.
  • 타임아웃 — 기본 10분을 그대로 두지 않는다.
  • 대화 길이 — 턴 수나 토큰 수 상한을 정하고 넘으면 요약·새 대화.
  • 모델 ID — 설정 파일 한 곳에 두고, 모델 문서가 바뀌면 거기만 고친다.
  • 공개 봇 — 완성된 답을 한 번 더 검사하는 단계를 둔다.

자주 묻는 것

Chat Completions와 Responses API 중 무엇으로 시작하나요?

새 프로젝트라면 Responses API입니다. OpenAI 마이그레이션 문서는 Chat Completions가 계속 지원되지만 새 프로젝트에는 Responses를 권한다고 적고, Python SDK README도 Responses를 기본 API로, Chat Completions를 무기한 지원되는 이전 표준으로 소개합니다. 이미 Chat Completions로 돌아가는 코드는 급하게 옮길 필요가 없습니다.

대화 기록을 매번 전부 다시 보내야 하나요?

Responses API에서는 previous_response_id로 직전 응답을 이어 붙이면 OpenAI가 앞 맥락을 관리합니다. 다만 instructions는 이어지지 않아 요청마다 다시 넣어야 하고, 앞 대화의 토큰은 여전히 입력 토큰으로 과금됩니다. 오래 남길 대화는 Conversations API를, 저장을 원치 않으면 store를 false로 두고 직접 이력을 관리합니다.

Assistants API로 만든 챗봇은 어떻게 되나요?

OpenAI 문서에 따르면 Assistants API는 2026년 8월 26일 공식 종료돼 더 이상 쓸 수 없습니다. 같은 기능은 Responses API와 Conversations API로 옮겨야 하며, 마이그레이션 문서에 옮기는 방법이 정리돼 있습니다.

429 속도 제한 오류가 나면 SDK가 알아서 다시 시도하나요?

그렇습니다. openai Python SDK는 연결 오류와 408, 409, 429, 500 이상 응답을 기본 2번, 짧은 지수 백오프로 다시 시도합니다. 횟수는 max_retries로 바꾸고 0이면 끕니다. 기본 타임아웃은 10분이라 챗봇처럼 빨리 답해야 하는 곳에서는 timeout을 짧게 잡는 편이 낫습니다.

정리

2026년 10월 기준 OpenAI API Python 챗봇은 openai 3.41 SDK와 Responses API로 시작하는 것이 공식 문서의 권장이다. 지시문은 instructions로, 대화는 previous_response_id나 Conversations API로 잇고, 스트리밍은 response.output_text.delta 이벤트로 받는다. 모델은 일반 대화에 Terra, 질이 더 필요하면 Sol, 대량 처리는 Luna처럼 일마다 나누고, 타임아웃·재시도·대화 길이 상한을 처음부터 넣어 두면 운영에서 당황할 일이 크게 준다.

OpenAI API Python 챗봇 가이드 대표 그림
OpenAI API Python 챗봇 가이드 — Responses API 기준.

참고 자료

  1. OpenAI API Docs. Models — 대표 모델 gpt-6-astra·gpt-6.1-sol·gpt-6.1-terra·gpt-6-luna 가격·컨텍스트·최대 출력(2026-10-30 확인). developers.openai.com
  2. OpenAI API Docs. Migrate to the Responses API — Chat Completions 계속 지원·새 프로젝트 권장, Assistants API 2026-08-26 종료, 대화 상태, response_format→text.format(2026-10-30 확인). developers.openai.com
  3. OpenAI API Docs. Streaming API responses — 핵심 이벤트와 모더레이션 주의(2026-10-30 확인). developers.openai.com
  4. OpenAI API Docs. Function calling — function_call·function_call_output·call_id, strict 모드 조건(2026-10-30 확인). developers.openai.com
  5. OpenAI API Docs. Embeddings — text-embedding-3-small·large 차원과 dimensions(2026-10-30 확인). developers.openai.com
  6. openai/openai-python README — 기본 API, 재시도 2회·대상 상태 코드, 기본 타임아웃 10분, 예외 이름, AsyncOpenAI(2026-10-30 확인). github.com
  7. PyPI. openai — 3.41.0, Python 3.10 이상(2026-10-30 확인). pypi.org
OpenAI API Python Responses API 챗봇 개발 함수 호출 스트리밍 임베딩
junetapa(박준철)
개발자가 아니라 쓰는 사람. IT 현장 27년의 기준으로 AI 도구를 고르고 기록한다.
Twitter Facebook URL 복사