ChatGPT API 사용법 초보 가이드를 검색하게 된 지금, 결제까지 완료하고 발급받은 API 키를 복사해 넣었는데도 '401 Unauthorized' 오류 메시지만 뜨고, JSON 형식의 파라미터를 어떻게 구성해야 할지 몰라 코드 작성조차 시작하지 못한 상황일 것입니다. 이런 오류는 대개 인증 헤더를 잘못 설정했거나, OpenAI 라이브러리가 업데이트되면서 변경된 요청 형식을 반영하지 못해 발생합니다. 본 ChatGPT API 사용법 초보 가이드에서는 인증 오류를 해결하는 환경 변수 설정부터, 최신 문서에 맞는 정확한 파라미터 구성과 첫 호출 코드까지 단계별로 구체적으로 해결책을 제시합니다.
- API 키 노출 방지를 위한 환경 변수(.env) 설정법
- OpenAI Python 라이브러리 v1.0 이상에서의 올바른 인증 및 요청 방식
- 답변의 창의성과 길이를 제어하는 핵심 파라미터 적용 가이드
ChatGPT API를 처음 설정하고 호출하는 과정을 초보자도 따라 할 수 있도록 5단계로 간단히 정리했습니다.
인증 오류가 발생하는 정확한 원인과 환경 점검
가장 먼저 겪는 '401 Unauthorized' 오류는 서버가 사용자의 신원을 확인하지 못했다는 뜻입니다. 초보자가 가장 많이 하는 실수는 코드에 API 키를 직접 문자열로 입력하거나, 요청 헤더에 Authorization 값을 빠뜨리는 것입니다. 특히 최신 OpenAI 라이브러리는 기본적으로 환경 변수에서 키를 찾도록 설계되어 있어, 이를 무시하고 코드에 키를 하드코딩하면 보안 위험뿐만 아니라 버전 업데이트 시 코드가 깨지기 쉽습니다.
또 다른 원인은 잘못된 엔드포인트 사용입니다. 과거 모델은 v1/engines를 사용했지만, 현재 표준인 채팅 완성 모델은 v1/chat/completions 엔드포인트를 사용해야 합니다. OpenAI 공식 문서의 API Reference 페이지에 명시된 바와 같이, 이전 엔드포인트를 사용하면 인증은 성공하더라도 404 Not Found 오류가 발생하거나 모델을 찾을 수 없다는 메시지를 마주하게 됩니다.
API 키를 절대로 깃허브(GitHub)나 공개된 저장소에 업로드하지 마십시오. 한 개인의 경험에 따르면, 실수로 공개 레포지토리에 키를 올린 지 5분 만에 자동화된 봇이 이를 감지하여 무단으로 크레딧을 탕감해버린 사례가 있습니다. 키가 유출되었다면 즉시 OpenAI 대시보드에서 'Revoke key' 버튼을 눌러 기존 키를 폐기하고 새로 발급받아야 합니다.
Photo by Sanket Mishra on Pexels
API 키 유출을 막는 환경 변수 설정 및 불러오기
인증 오류를 근본적으로 해결하고 보안을 유지하려면 API 키를 코드가 아닌 운영체제의 환경 변수로 관리해야 합니다. 이 방식은 키가 소스 코드와 분리되므로 프로젝트를 공유하거나 버전 관리 시 실수로 노출될 위험을 원천 차단합니다. 윈도우 사용자는 시스템 환경 변수 설정 화면에서 OPENAI_API_KEY를 추가하고, macOS나 리눅스 사용자는 터미널의 셸 설정 파일인 .zshrc나 .bash_profile에 키를 등록합니다.
더욱 효율적인 방법은 프로젝트 폴더 내에 .env 파일을 생성하는 것입니다. 이 파일은 파이썬의 python-dotenv 라이브러리를 통해 쉽게 불러올 수 있습니다. 예를 들어, .env 파일 안에 OPENAI_API_KEY=sk-proj-... 형식으로 키를 적어두고, 파이썬 코드에서 load_dotenv() 함수를 호출하면 됩니다. 이후 os.environ.get("OPENAI_API_KEY")를 통해 키 값을 안전하게 가져와 API 클라이언트를 초기화할 수 있습니다.
.env 파일 생성
프로젝트 루트 디렉터리에 .env 파일을 만들고 OPENAI_API_KEY=sk-실제키값을 입력합니다.
라이브러리 설치
터미널에서 pip install python-dotenv 명령어를 입력해 의존성을 추가합니다.
코드에서 로드
파이썬 스크립트 상단에서 from dotenv import load_dotenv를 임포트하고, 실행 코드 맨 앞부분에 load_dotenv()를 호출하여 환경 변수를 메모리에 올립니다.
ChatGPT API 사용법 초보 가이드: 요청 본문과 파라미터 구성
동영상으로 보는 ChatGPT API 사용법 초보 가이드
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
API 호출의 핵심은 올바른 JSON 형식으로 요청 본문(Request Body)을 구성하는 것입니다. OpenAI API는 대화형 모델이기 때문에 messages라는 리스트 형태의 파라미터를 필수로 요구합니다. 이 리스트는 딕셔너리의 집합이며, 각 딕셔너리는 최소한 role(역할)과 content(내용) 키를 포함해야 합니다.
- model: 사용할 모델의 ID입니다. (예:
gpt-4o,gpt-3.5-turbo) - messages: 대화 기록을 나타내는 객체 배열입니다.
system: AI에게 페르소나나 행동 지침을 부여합니다. (예: "너는 유머러스한 어시스턴트야.")user: 사용자의 질문이나 지시를 입력합니다.assistant: 이전 대화에서 AI의 답변을 기록할 때 사용합니다(맥락 유지용).
파이썬 라이브러리 설치 및 첫 번째 코드 실행하기
ChatGPT API 설정 체크리스트
이제 모든 준비가 되었으니 실제 코드를 작성해 보겠습니다. 과거에는 openai.ChatCompletion.create() 메서드를 사용했지만, v1.0.0 이상 버전에서는 클라이언트 인스턴스를 생성한 후 client.chat.completions.create()를 사용하는 방식으로 변경되었습니다. 아래 코드를 복사하여 실행해 보세요.
from openai import OpenAI
import os
from dotenv import load_dotenv# 1. 환경 변수 로드
load_dotenv()# 2. 클라이언트 초기화 (API 키는 자동으로 환경 변수에서 참조)
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))# 3. API 요청 전송
response = client.chat.completions.create(
model="gpt-3.5-turbo", # 또는 gpt-4o
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "ChatGPT API 사용법을 알려주세요."}
]
)# 4. 결과 출력
자주 묻는 질문
Q. ChatGPT API 키는 어디서 발급받나요?
A. OpenAI 웹사이트에 로그인한 뒤 ‘API’ 섹션으로 이동하면 ‘Create new secret key’ 버튼을 통해 발급받을 수 있습니다. 발급된 키는 절대 외부에 노출되지 않도록 환경 변수 등에 안전하게 보관하세요.
Q. API 호출 시 꼭 필요한 파라미터는 무엇인가요?
A. 가장 기본적인 파라미터는 `model`, `messages`, 그리고 `max_tokens` 입니다. `model`은 사용할 모델 이름(e.g., gpt-4o), `messages`는 대화 형식의 입력, `max_tokens`는 응답 길이를 제한합니다.
Q. 요청 제한(rate limit)이나 비용은 어떻게 확인하나요?
A. OpenAI 대시보드의 ‘Usage’ 탭에서 현재 사용량과 비용을 실시간으로 확인할 수 있습니다. 또한 공식 문서에 명시된 초당 요청 수 제한을 초과하지 않도록 코드를 설계해야 합니다.
Q. 에러가 발생했을 때 어떻게 디버깅하나요?
A. 응답 본문에 포함된 `error` 객체를 확인하면 에러 코드와 메시지를 알 수 있습니다. 흔한 원인은 인증 토큰 오류, 파라미터 형식 오류, 혹은 사용량 초과이니 각각에 맞게 수정하면 됩니다.
MMebys Blog맥OS · 크롬 · 자동화 · AI 도구 가이드