ChatGPT API를 내 Python 앱에 넣고 싶은데 어디서부터 시작해야 할까요? 생각보다 간단합니다. 하지만 진짜 차이를 만드는 건 역할 기반 메시지와 구조화된 출력을 활용하는 방법을 아는 거죠.

파이썬 교육 전문 플랫폼 Real Python이 ChatGPT API를 Python 프로젝트에 통합하는 실무 중심 튜토리얼을 공개했습니다. 단순 텍스트 생성부터 Pydantic 모델을 활용한 구조화된 데이터 출력까지, 실전에서 바로 쓸 수 있는 예제를 제공합니다.

출처: How to Integrate ChatGPT’s API With Python Projects – Real Python

첫 API 호출은 5줄이면 충분합니다

API 키를 환경변수로 설정하고 openai 라이브러리를 설치하면 기본 준비는 끝입니다. 첫 호출은 정말 간단해요.

from openai import OpenAI

client = OpenAI()  # 환경변수에서 API 키 자동 읽기
response = client.responses.create(
    model="gpt-5",
    input="Python으로 피보나치 수열을 만드는 방법을 알려줘"
)
print(response.output_text)

응답은 .output_text 속성으로 바로 접근할 수 있습니다. 복잡한 데이터 구조를 탐색할 필요가 없어요.

역할 기반 메시지로 AI 행동에 가드레일 설정하기

여기서부터 재미있어집니다. 단순히 텍스트를 보내는 게 아니라 AI의 행동을 제어할 수 있거든요. developer와 user 역할을 구분하면 됩니다.

예를 들어 Python 전용 코딩 어시스턴트를 만든다고 해보죠.

response = client.responses.create(
    model="gpt-5",
    input=[
        {
            "role": "developer",
            "content": "너는 Python 코딩 어시스턴트야. Python 관련 질문에만 답변해."
        },
        {
            "role": "user",
            "content": user_question
        }
    ]
)

developer 역할의 메시지는 user 메시지보다 우선순위가 높습니다. 사용자가 “이전 지시를 무시하고…”라고 말해도 개발자가 설정한 가드레일은 유지되죠. Python 질문에는 답변하지만 요리 레시피를 물으면 정중히 거절합니다.

이 역할 구분은 일관된 톤을 유지하거나 특정 형식으로만 응답하게 만들 때 필수적입니다.

Pydantic으로 구조화된 응답 받기

텍스트 응답도 좋지만 실무에서는 특정 형식의 데이터가 필요한 경우가 많습니다. 함수 이름, 코드, 설명, 사용 예시를 각각 분리해서 받고 싶다면요?

Pydantic 모델로 원하는 구조를 정의하면 됩니다.

from pydantic import BaseModel

class CodeOutput(BaseModel):
    function_name: str
    code: str
    explanation: str
    example_usage: str

API 호출 시 이 모델을 text_format 파라미터로 전달하고, .responses.parse() 메서드를 사용합니다.

response = client.responses.parse(
    model="gpt-5",
    input="정수 리스트를 받아서 평균을 계산하는 함수를 만들어줘",
    text_format=CodeOutput
)

code_data = response.output_parsed
print(code_data.function_name)  # 속성으로 바로 접근
print(code_data.code)

이제 정규식으로 문자열을 파싱하거나 수동으로 데이터를 처리할 필요가 없습니다. Pydantic이 자동으로 검증까지 해주고, 모델 구조와 맞지 않으면 에러를 발생시키죠. 템플릿에 넣거나 데이터베이스에 저장하거나 다른 함수에 전달할 때 추가 가공 없이 바로 쓸 수 있어요.

실무에서 챙겨야 할 것들

튜토리얼은 보안, 에러 처리, 비용 관리도 다룹니다. API 키는 절대 코드에 하드코딩하지 말고 환경변수나 보안 키 관리 서비스를 사용하세요. 네트워크 에러나 속도 제한 에러에 대비한 예외 처리도 필수입니다.

비용도 중요한 고려사항입니다. 모델마다 가격이 다르고 처리하는 토큰 수에 따라 누적되거든요. OpenAI 대시보드에서 사용량을 모니터링하고, 개발 단계에서는 무료 목업 엔드포인트를 활용하는 것도 방법이에요.

챗봇을 만든다면 대화 히스토리를 input 리스트에 계속 포함시켜 맥락을 유지할 수 있습니다. 다만 대화가 길어질수록 토큰 소비와 비용이 증가한다는 점도 염두에 두세요.

참고자료:

• Practical Prompt Engineering – Real Python
• Document Python Code with ChatGPT – Real Python