Python으로 시작하는 OpenAI 개발 입문 1편 — 처음 API를 붙일 때, 제일 먼저 이해해야 하는 것들

Python으로 시작하는 OpenAI 개발 입문 1편 — 처음 API를 붙일 때, 제일 먼저 이해해야 하는 것들

OpenAI로 뭔가를 만들어보고 싶다는 생각, 저도 처음엔 되게 막연했습니다.
“챗봇 하나 붙이면 되는 거 아냐?” 싶었는데, 막상 들어가 보니까 모델, 토큰, API 키, SDK, Responses API, 스트리밍,(GitHub)게, 처음부터 너무 거창하게 공부할 필요는 없습니다.
주니어 개발자 기준으로는 딱 3가지만 먼저 이해하면 꽤 빠르게 손에 익어요.

첫째, OpenAI는 결국 HTTP API다.
둘째, Python에서는 공식 SDK로 훨씬 편하게 쓸 수 있다.
셋째, 지금 기준으로는 Responses API 중심으로 익히는 게 가장 자연스럽다. OpenAI 공식 Python 라이브러리 README도 현재 기본 사용 흐름으로 client.responses.create(...)를 먼저 보여주고 있고, Python 라이브러리는 Python 3.9+ 환경에서 사용할 수 있습니다. 또 예전 방식인 Chat Completions도 계속 지원되지만, “이전 표준(previous standard)”로 안내되고 있습니다. (GitHub)

이 시리즈의 첫 글에서는 욕심 안 부리고 여기까지 갑니다.

• OpenAI가 정확히 뭐인지
• Python에서 왜 쓰기 좋은지
• 개발 전에 머릿속에 넣어야 할 최소 개념
• 진짜로 실행 가능한 첫 코드
• 초보자가 처음부터 피해야 할 실수

오늘 글을 제대로 이해하면, 다음 글부터는
프롬프트 설계 → JSON 구조화 출력 → Flask/FastAPI/NestJS 백엔드 연동 → 문서 요약기 → 챗봇 → 사내 도구 자동화 → 실무형 프로젝트까지 쭉 이어갈 수 있습니다.

---

1. OpenAI를 공부할 때 먼저 버려야 하는 착각

처음 배우는 분들이 제일 많이 하는 착각이 있습니다.

“AI는 뭔가 특별한 프로그램이고, 기존 백엔드 개발이랑은 다르다.”

반은 맞고 반은 틀립니다.

실제로 서비스 개발 관점에서 보면 OpenAI도 결국 이 구조예요.

1. 내 프로그램이 사용자 입력을 받는다.
2. 그 입력을 OpenAI API로 보낸다.
3. 모델이 결과를 돌려준다.
4. 그 결과를 가공해서 화면에 보여주거나 DB에 저장한다.

즉, 본질은 익숙한 백엔드 흐름입니다.
요청(Request) → 응답(Response) 구조라는 점에서 REST API를 다뤄본 경험이 있다면 생각보다 낯설지 않습니다.

OpenAI 공식 문서도 API 키 기반 인증과 HTTP Bearer 인증 방식을 안내하고 있고, 서버에서 안전하게 키를 관리하라고 강조합니다. 이 부분이 중요한 이유는, OpenAI 연동이 “프론트 장난감”이 아니라 서버 애플리케이션의 일부로 들어가야 한다는 뜻이기 때문입니다. (OpenAI Platform)2. 왜 하필 Python으로 시작하냐

이건 제가 꽤 확신 있게 말할 수 있습니다.
OpenAI 입문은 Python이 제일 편합니다.

이유는 단순해요.

2-1. 예제가 많습니다

공식 SDK 자체가 잘 정리되어 있고, Python 예제가 정말 많습니다. 공식 Python 라이브러리는 동기/비동기 클라이언트를 모두 제공하고, 타입 정의도 포함하고 있습니다. (GitHub) 실험 속도가 빠릅니다
주니어 개발자 시절엔 “빠르게 한 번 돌려보는 경험”이 중요합니다.
Python은 가상환경 만들고, 패키지 설치하고, 한 파일로 호출해보는 흐름이 매우 빠릅니다.

2-3. 나중에 확장이 쉽습니다

처음엔 단순 호출만 하다가도, 나중엔 아래로 자연스럽게 확장됩니다.

• FastAPI로 API 서버 만들기
• LangChain/LlamaIndex 같은 오케스트레이션 도구 붙이기
• pandas로 데이터 후처리하기
• RAG, 벡터DB, 배치 처리로 확장하기

즉, 입문과 심화의 연결이 좋습니다.

---

3. 지금 기준으로 꼭 알아야 할 OpenAI Python 사용 흐름

예전 블로그 글을 보면 openai.ChatCompletion.create(...) 같은 코드가 많이 나옵니다.
근데 지금 주니어 입문자에게 그 방식부터 주입하면 조금 위험합니다.

왜냐하면 OpenAI 공식 Python 라이브러리 README는 현재 주요 인터페이스로 Responses API를 먼저 안내하고 있고, 예전 Chat Completions API는 여전히 지원되지만 “이전 표준”이라고 설명하고 있기 때문입니다. (GitHub) 이렇게 이해하면 됩니다.

현재 권장 흐름

• from openai import OpenAI
• client = OpenAI()
• client.responses.create(...)

알아만 두면 좋은 이전 흐름

• client.chat.completions.create(...)

이 차이를 아는 것만으로도,
구글링하다가 오래된 예제에 끌려가서 헤매는 시간을 꽤 줄일 수 있습니다. (GitHub)(GitHub)-

4. 개발 전에 알아야 할 최소 개념 5가지

이 부분은 진짜 중요합니다.
코드보다 먼저 머리에 들어가야 해요.

4-1. 모델

OpenAI API는 “모델”을 지정해서 호출합니다.
공식 모델 비교 문서에는 각 모델의 가격, 컨텍스트 윈도우, 지원 기능, 엔드포인트 지원 여부가 정리되어 있습니다. 예를 들어 GPT-5.4는 v1/responses와 v1/chat/completions 등을 지원하며, 컨텍스트 윈도우와 가격 정보도 공개되어 있습니다. (OpenAI Platform) 모든 모델을 외울 필요 없습니다.
처음엔 그냥 “모델마다 성능/속도/비용이 다르다” 정도만 이해하면 충분합니다.

4-2. 입력과 출력

모델은 입력을 받고, 출력을 생성합니다.
입력은 단순 문자열일 수도 있고, 텍스트+이미지 조합일 수도 있습니다. 공식 Python SDK README에도 텍스트 입력 예제와 이미지 입력 예제가 모두 나와 있습니다. (GitHub) API 키
API 키는 절대 프론트엔드에 넣으면 안 됩니다.
공식 문서도 API 키를 비밀로 유지하고, 브라우저나 앱 클라이언트에 노출하지 말라고 명시합니다. 서버 환경변수나 키 관리 시스템으로 다루는 게 기본입니다. (OpenAI Platform) 토큰과 비용
OpenAI API는 대체로 사용량 기반 과금 구조라서,
길고 복잡한 요청과 긴 응답은 비용에 영향을 줍니다. 모델 비교 페이지는 1M tokens 기준 가격을 제공합니다. (OpenAI Platform) SDK는 API를 더 쉽게 쓰게 해주는 도구
결국 본체는 API이고, Python SDK는 그걸 편하게 감싸주는 라이브러리입니다.
그래서 SDK를 익히되, **“나는 HTTP API를 다루고 있다”**는 감각은 잃지 않는 게 좋습니다.

---

5. 개발 환경 준비

이제 진짜로 시작해봅시다.

5-1. 가상환경 생성

맥/리눅스 기준입니다.

python3 -m venv .venv
source .venv/bin/activate

윈도우 PowerShell이라면:

python -m venv .venv
.venv\Scripts\Activate.ps1

5-2. 패키지 설치

pip install openai python-dotenv

공식 Python 라이브러리는 PyPI에서 설치할 수 있고, Python 3.9+를 지원합니다. (GitHub) .env 파일 만들기

프로젝트 루트에 .env 파일을 생성합니다.

OPENAI_API_KEY=여기에_발급받은_API_KEY

공식 README도 API 키를 코드에 박지 말고 .env 등으로 관리하는 방식을 권장합니다. (GitHub)

---

6. 첫 번째 실행 코드

아래 코드는 이 글을 위해 문법까지 다시 점검한, 바로 실행 가능한 최소 예제입니다.

파일명: main.py

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise ValueError("OPENAI_API_KEY가 설정되지 않았습니다. .env 파일을 확인하세요.")

client = OpenAI(api_key=api_key)

def ask_openai(question: str) -> str:
    response = client.responses.create(
        model="gpt-5.2",
        instructions="당신은 주니어 개발자를 돕는 친절한 파이썬 멘토입니다.",
        input=question,
    )
    return response.output_text

if __name__ == "__main__":
    answer = ask_openai("REST API가 무엇인지 3문장으로 설명해줘.")
    print(answer)

실행:

python main.py

이 코드에서 핵심은 세 가지입니다.

1. .env에서 API 키를 읽는다.
2. OpenAI() 클라이언트를 만든다.
3. client.responses.create(...)로 질문을 보낸다.

이 흐름은 공식 Python SDK README의 기본 사용 예제와 같은 방향입니다. (GitHub)7. 코드 한 줄씩 해설

솔직히 처음엔 이런 코드가 그냥 마법처럼 보입니다.
근데 뜯어보면 별거 아닙니다.

load_dotenv()

.env 파일 안의 값을 환경변수처럼 읽어오게 해줍니다.

OpenAI(api_key=api_key)

OpenAI API를 호출하기 위한 클라이언트를 만듭니다.

client.responses.create(...)

여기서 실제 API 요청이 일어납니다.

• model: 어떤 모델을 쓸지
• instructions: 모델에게 주는 상위 지시
• input: 실제 사용자 질문

response.output_text

응답 객체에서 텍스트 결과를 꺼냅니다.

주니어가 처음엔 여기까지만 이해해도 됩니다.
나중에 스트리밍, 구조화 출력, tool calling 같은 건 천천히 붙이면 됩니다.

---

8. 초보자가 처음부터 자주 하는 실수

이건 제가 진짜 많이 본 부분입니다.

실수 1. API 키를 코드에 하드코딩한다

client = OpenAI(api_key="sk-...")

이렇게 하면 나중에 Git에 올라갈 확률이 높습니다.
공식 문서도 키를 클라이언트 코드에 노출하지 말라고 경고합니다. (OpenAI Platform). 오래된 예제를 그대로 복붙한다
검색하다 보면 몇 년 전 블로그 글이 많이 뜹니다.
지금은 Python 공식 SDK 기준으로 OpenAI() 클라이언트와 responses.create() 흐름부터 익히는 편이 안전합니다. (GitHub). 프롬프트만 바꾸면 다 해결된다고 믿는다
실무에서는 프롬프트보다 중요한 게 많습니다.

• 입력 검증
• 예외 처리
• 재시도
• 로그
• 비용 통제
• 응답 형식 고정
• 사용자별 권한 처리

AI 기능은 신기한데, 결국 서비스는 백엔드가 버텨줘야 합니다.

실수 4. 프론트에서 직접 API를 호출한다

학습용 데모는 가능해 보여도, 실제 서비스 구조로는 추천하기 어렵습니다.
API 키 관리 때문에라도 서버를 경유하는 설계가 기본입니다. (OpenAI Platform)9. 오늘 단계에서 꼭 해보면 좋은 실습 3가지

첫 글을 읽고 나면 그냥 넘어가지 말고, 아래 세 가지는 직접 바꿔보는 걸 추천합니다.

실습 1. 질문 바꿔보기

answer = ask_openai("파이썬의 리스트와 튜플 차이를 예제로 설명해줘.")

실습 2. instructions 바꿔보기

instructions="당신은 면접 코치입니다. 핵심만 간단히 설명하세요."

실습 3. 함수 여러 번 호출해보기

questions = [
    "HTTP와 HTTPS의 차이는?",
    "REST API와 GraphQL 차이는?",
    "JSON이 왜 많이 쓰이나요?"
]

for q in questions:
    print("=" * 50)
    print("질문:", q)
    print(ask_openai(q))

이 실습을 하면 “아, 진짜 그냥 함수 호출처럼 쓰는 거구나” 하는 감각이 옵니다.
이 감각이 생기면 그 다음부터 재미가 붙습니다.

---

10. 실무에서는 이게 어떻게 확장되나

첫 글인데 벌써 실무 얘기까지 하냐 싶겠지만,
저는 오히려 처음부터 끝 그림을 보는 게 중요하다고 생각합니다.

지금 만든 ask_openai()는 사실 앞으로 이렇게 발전합니다.

단계 1. CLI 도구

터미널에서 질문하고 답 받기

단계 2. 웹 백엔드 API

FastAPI/Flask/NestJS에서 /ai/ask 엔드포인트 만들기

단계 3. 응답 형식 고정

자유문장이 아니라 JSON으로 받기

단계 4. 문서/파일 기반 기능

회의록 요약, 공지문 정리, 코드 리뷰 보조

단계 5. 도메인 특화 서비스

고객상담 봇, 사내 검색 도구, 리포트 생성기, 개발 보조 에이전트

그리고 OpenAI 공식 문서 구조를 보면 텍스트 생성만 있는 게 아니라, 구조화 출력, 함수 호출, 파일 검색, 이미지/오디오, 에이전트 관련 개념까지 넓게 이어져 있습니다. 즉, 지금 배우는 첫 호출은 그냥 장난감 코드가 아니라 이후 확장의 출발점입니다. (OpenAI Platform)11. 오늘 글의 핵심 요약

오늘은 일부러 욕심을 줄였습니다.
처음부터 “AI SaaS 만들기”, “RAG 구축”, “Agent orchestration” 이런 데로 가면 멋있어 보이긴 하는데, 주니어 입장에선 오히려 발이 꼬입니다.

오늘 딱 기억할 건 이것뿐입니다.

OpenAI는 결국 API이고, Python에서는 공식 SDK로 쉽게 붙일 수 있으며, 지금 기준으로는 Responses API 흐름부터 익히는 게 좋다. (GitHub)(GitHub)잡히면 다음 글부터 훨씬 수월해집니다.

---

다음 편 예고

다음 글에서는 진짜 중요한 걸 다룰 겁니다.

“프롬프트를 어떻게 써야 결과가 흔들리지 않는가”
이 주제로,

• system / developer / user 역할 감각
• instructions 설계법
• 재현성 높이는 프롬프트 작성법
• 초보자가 자주 쓰는 애매한 프롬프트 고치는 법
• Python 코드로 프롬프트 비교 실험하기

까지 이어서 가보겠습니다.

---

출처

• OpenAI 공식 Python SDK README — Python 3.9+ 지원, OpenAI() 클라이언트, Responses API 기본 예제, Chat Completions 예제, async/streaming 예제 (GitHub)API Reference Overview — 인증 방식, API 키 보안 원칙, Responses API/도구/에이전트 관련 전체 문서 구조 (OpenAI Platform)Models Compare — 모델별 가격, 컨텍스트 윈도우, 지원 엔드포인트 및 기능 비교 (OpenAI Platform)추천 태그