OpenAI API - 완벽 가이드
버전: 프로덕션 준비 완료 ✅ 패키지: [email protected] 마지막 업데이트: 2025-11-26
상태
✅ 프로덕션 준비 완료:
- ✅ Chat Completions API (GPT-5, GPT-4o, GPT-4 Turbo)
- ✅ Embeddings API (text-embedding-3-small, text-embedding-3-large)
- ✅ Images API (DALL-E 3 생성 + GPT-Image-1 편집)
- ✅ Audio API (Whisper 전사 + 11개 음성 TTS)
- ✅ Moderation API (11개 안전 범주)
- ✅ 스트리밍 패턴 (SSE)
- ✅ 함수 호출 / 도구
- ✅ 구조화된 출력 (JSON 스키마)
- ✅ 비전 (GPT-4o)
- ✅ Node.js SDK 및 fetch 접근법 모두 지원
목차
- 빠른 시작
- Chat Completions API
- GPT-5 시리즈 모델
- 스트리밍 패턴
- 함수 호출
- 구조화된 출력
- 비전 (GPT-4o)
- Embeddings API
- Images API
- Audio API
- Moderation API
- 오류 처리
- 속도 제한
- 프로덕션 베스트 프랙티스
- openai-responses와의 관계
빠른 시작
설치
npm install [email protected]
환경 설정
export OPENAI_API_KEY="sk-..."
또는 .env 파일 생성:
OPENAI_API_KEY=sk-...
첫 번째 Chat Completion (Node.js SDK)
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
const completion = await openai.chat.completions.create({
model: 'gpt-5',
messages: [
{ role: 'user', content: '로봇 공학의 세 가지 법칙은 무엇인가요?' }
],
});
console.log(completion.choices[0].message.content);
첫 번째 Chat Completion (Fetch - Cloudflare Workers)
const response = await fetch('https://api.openai.com/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gpt-5',
messages: [
{ role: 'user', content: '로봇 공학의 세 가지 법칙은 무엇인가요?' }
],
}),
});
const data = await response.json();
console.log(data.choices[0].message.content);
Chat Completions API
엔드포인트: POST /v1/chat/completions
Chat Completions API는 OpenAI의 언어 모델과 상호 작용하기 위한 핵심 인터페이스입니다. 대화형 AI, 텍스트 생성, 함수 호출, 구조화된 출력 및 비전 기능을 지원합니다.
지원 모델
GPT-5 시리즈 (2025년 8월 출시)
- gpt-5: 고급 기능을 갖춘 완전한 기능의 추론 모델
- gpt-5-mini: 우수한 성능의 비용 효율적인 대안
- gpt-5-nano: 간단한 작업을 위한 가장 작고 빠른 변형
GPT-4o 시리즈
- gpt-4o: 비전 기능을 갖춘 멀티모달 모델
- gpt-4-turbo: 빠른 GPT-4 변형
GPT-4 시리즈
- gpt-4: 원본 GPT-4 모델
기본 요청 구조
{
model: string, // 사용할 모델 (예: "gpt-5")
messages: Message[], // 대화 기록
reasoning_effort?: string, // GPT-5 전용: "minimal" | "low" | "medium" | "high"
verbosity?: string, // GPT-5 전용: "low" | "medium" | "high"
temperature?: number, // GPT-5에서는 지원되지 않음
max_tokens?: number, // 생성할 최대 토큰 수
stream?: boolean, // 스트리밍 활성화
tools?: Tool[], // 함수 호출 도구
}
응답 구조
{
id: string, // 고유 완료 ID
object: "chat.completion",
created: number, // Unix 타임스탬프
model: string, // 사용된 모델
choices: [{
index: number,
message: {
role: "assistant",
content: string, // 생성된 텍스트
tool_calls?: ToolCall[] // 함수 호출인 경우
},
finish_reason: string // "stop" | "length" | "tool_calls"
}],
usage: {
prompt_tokens: number,
completion_tokens: number,
total_tokens: number
}
}
메시지 역할 & 다중 턴 대화
세 가지 역할: system (동작), user (입력), assistant (모델 응답).
중요: API는 stateless입니다. 각 요청마다 전체 대화 기록을 보내야 합니다. 상태 저장 대화는 openai-responses 스킬을 사용하세요.
GPT-5 시리즈 모델
GPT-5 모델(2025년 8월 출시)은 추론 및 세부 정도 제어 기능을 도입했습니다:
GPT-5.1 (2025년 11월 13일 출시)
주요 개선 사항이 포함된 최신 모델:
- gpt-5.1: 생각 시간을 동적으로 변화시키는 적응형 추론
- 24시간 확장 프롬프트 캐싱: 더 빠른 후속 쿼리, 저렴한 비용
- 새로운 개발자 도구: apply_patch (코드 편집), shell (명령 실행)
BREAKING CHANGE: GPT-5.1은 reasoning_effort: 'none'을 기본값으로 합니다(GPT-5의 기본값 'medium'과 다름). 마이그레이션 시 코드를 업데이트하세요!
reasoning_effort 매개변수
사고 깊이를 제어합니다(GPT-5 및 GPT-5.1에서 사용 가능):
- "none": 추론 없음 (가장 빠름, 가장 낮은 지연 시간) - GPT-5.1 기본값
- "minimal": 빠른 응답, 최소한의 사고
- "low": 기본 추론
- "medium": 균형 잡힌 추론 - GPT-5 기본값
- "high": 복잡한 문제를 위한 깊은 추론
// 추론 없는 GPT-5.1 (빠름)
const completion = await openai.chat.completions.create({
model: 'gpt-5.1',
messages: [{ role: 'user', content: '간단한 질문' }],
// reasoning_effort: 'none'은 GPT-5.1의 암시적 기본값
});
// 높은 추론의 GPT-5.1 (복잡한 작업)
const completion = await openai.chat.completions.create({
model: 'gpt-5.1',
messages: [{ role: 'user', content: '이 복잡한 수학 문제를 푸세요...' }],
reasoning_effort: 'high',
});
verbosity 매개변수
출력 세부 정도 제어 (GPT-5/GPT-5.1):
- "low": 간결
- "medium": 균형 (기본값)
- "high": 상세
GPT-5 제한 사항
지원되지 않음:
- ❌
temperature,top_p,logprobs매개변수 - ❌ 턴 간 상태 저장 Chain of Thought
대안: temperature/top_p는 GPT-4o를 사용하거나 상태 저장 추론은 openai-responses 스킬을 사용하세요.
스트리밍 패턴
토큰별 전달을 위해 stream: true를 활성화합니다.
Node.js SDK
const stream = await openai.chat.completions.create({
model: 'gpt-5.1',
messages: [{ role: 'user', content: '시를 써 줘' }],
stream: true,
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || '';
process.stdout.write(content);
}
Fetch (Cloudflare Workers)
const response = await fetch('https://api.openai.com/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gpt-5.1',
messages: [{ role: 'user', content: '시를 써 줘' }],
stream: true,
}),
});
const reader = response.body?.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader!.read();
if (done) break;
const chunk = decoder.decode(value);
const lines = chunk.split('\n').filter(line => line.trim() !== '');
for (const line of lines) {
if (line.startsWith('data: ')) {
const data = line.slice(6);
if (data === '[DONE]') break;
try {
const json = JSON.parse(data);
const content = json.choices[0]?.delta?.content || '';
console.log(content);
} catch (e) {
// 유효하지 않은 JSON 건너뛰기
}
}
}
}
Server-Sent Events (SSE) 형식:
data: {"id":"chatcmpl-xyz","choices":[{"delta":{"content":"Hello"}}]}
data: [DONE]
핵심 사항: 불완전한 청크, [DONE] 신호, 유효하지 않은 JSON을 적절히 처리하세요.
함수 호출
JSON 스키마로 도구를 정의하면 모델이 컨텍스트에 따라 이를 호출합니다.
도구 정의 및 요청
const tools = [{
type: 'function',
function: {
name: 'get_weather',
description: 'Get current weather for a location',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: '도시 이름' },
unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
},
required: ['location']
}
}
}];
const completion = await openai.chat.completions.create({
model: 'gpt-5.1',
messages: [{ role: 'user', content: '서울의 날씨는 어때?' }],
tools: tools,
});
도구 호출 처리
const message = completion.choices[0].message;
if (message.tool_calls) {
for (const toolCall of message.tool_calls) {
const args = JSON.parse(toolCall.function.arguments);
const result = await executeFunction(toolCall.function.name, args);
// 결과를 모델로 다시 전송
await openai.chat.completions.create({
model: 'gpt-5.1',
messages: [
...messages,
message,
{
role: 'tool',
tool_call_id: toolCall.id,
content: JSON.stringify(result)
}
],
tools: tools,
});
}
}
루프 패턴: 응답에 tool_calls가 없을 때까지 API 호출을 계속합니다.
구조화된 출력
구조화된 출력을 사용하면 모델 응답에 JSON 스키마 유효성 검사를 강제할 수 있습니다.
JSON 스키마 사용
const completion = await openai.chat.completions.create({
model: 'gpt-4o', // 참고: 구조화된 출력은 GPT-4o에서 가장 잘 지원됨
messages: [
{ role: 'user', content: '사람 프로필을 생성하세요' }
],
response_format: {
type: 'json_schema',
json_schema: {
name: 'person_profile',
strict: true,
schema: {
type: 'object',
properties: {
name: { type: 'string' },
age: { type: 'number' },
skills: {
type: 'array',
items: { type: 'string' }
}
},
required: ['name', 'age', 'skills'],
additionalProperties: false
}
}
}
});
const person = JSON.parse(completion.choices[0].message.content);
// { name: "Alice", age: 28, skills: ["TypeScript", "React"] }
JSON 모드 (간단)
엄격한 스키마 검증이 필요하지 않은 간단한 사용 사례:
const completion = await openai.chat.completions.create({
model: 'gpt-5',
messages: [
{ role: 'user', content: 'JSON 형식으로 프로그래밍 언어 3개를 나열하세요' }
],
response_format: { type: 'json_object' }
});
const data = JSON.parse(completion.choices[0].message.content);
중요: response_format을 사용할 때는 프롬프트에 "JSON"을 포함시켜 모델을 안내하세요.
비전 (GPT-4o)
GPT-4o는 텍스트와 함께 이미지 이해를 지원합니다.
URL을 통한 이미지
const completion = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: [
{ type: 'text', text: '이 이미지에는 무엇이 있나요?' },
{
type: 'image_url',
image_url: {
url: 'https://example.com/image.jpg'
}
}
]
}
]
});
Base64를 통한 이미지
import fs from 'fs';
const imageBuffer = fs.readFileSync('./image.jpg');
const base64Image = imageBuffer.toString('base64');
const completion = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: [
{ type: 'text', text: '이 이미지를 자세히 설명하세요' },
{
type: 'image_url',
image_url: {
url: `data:image/jpeg;base64,${base64Image}`
}
}
]
}
]
});
여러 이미지
const completion = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: [
{ type: 'text', text: '이 두 이미지를 비교하세요' },
{ type: 'image_url', image_url: { url: 'https://example.com/image1.jpg' } },
{ type: 'image_url', image_url: { url: 'https://example.com/image2.jpg' } }
]
}
]
});
Embeddings API
엔드포인트: POST /v1/embeddings
의미 검색 및 RAG를 위해 텍스트를 벡터로 변환합니다.
모델
- text-embedding-3-large: 3072 차원 (사용자 정의: 256-3072), 최고 품질
- text-embedding-3-small: 1536 차원 (사용자 정의: 256-1536), 비용 효율적, 권장
기본 요청
const embedding = await openai.embeddings.create({
model: 'text-embedding-3-small',
input: '음식이 맛있었어요.',
});
// 반환: { data: [{ embedding: [0.002, -0.009, ...] }] }
사용자 정의 차원 (OpenAI 고유)
const embedding = await openai.embeddings.create({
model: 'text-embedding-3-small',
input: '샘플 텍스트',
dimensions: 256, // 기본 1536에서 축소
});
이점: 4배-12배 스토리지 절약, 더 빠른 검색, 최소한의 품질 손실.
배치 처리
const embeddings = await openai.embeddings.create({
model: 'text-embedding-3-small',
input: ['첫 번째 문서', '두 번째 문서', '세 번째 문서'],
});
제한 사항: 입력당 8192 토큰, 배치 전체 300k 토큰, 최대 배열 크기 2048.
핵심 사항: 효율성을 위해 사용자 정의 차원을 사용하고, 최대 2048개 문서까지 배치 처리하며, 임베딩을 캐싱하세요(결정론적).
Images API
이미지 생성 (DALL-E 3)
엔드포인트: POST /v1/images/generations
const image = await openai.images.generate({
model: 'dall-e-3',
prompt: '눈에 띄는 파란 눈을 가진 흰색 샴 고양이',
size: '1024x1024', // 또한: 1024x1536, 1536x1024, 1024x1792, 1792x1024
quality: 'standard', // 또는 'hd'
style: 'vivid', // 또는 'natural'
});
console.log(image.data[0].url);
console.log(image.data[0].revised_prompt); // DALL-E 3는 안전을 위해 프롬프트를 수정할 수 있음
DALL-E 3 세부 사항:
n: 1만 지원(요청당 하나의 이미지)- 안전/품질을 위해 프롬프트를 수정할 수 있음(
revised_prompt확인) - URL은 1시간 후 만료됨(영구 저장을 위해
response_format: 'b64_json'사용) - 영구 저장을 위한
response_format: 'b64_json'
Audio API
음성 전사 (Whisper)
엔드포인트: POST /v1/audio/transcriptions
import fs from 'fs';
const transcription = await openai.audio.transcriptions.create({
model: 'whisper-1',
file: fs.createReadStream('audio.mp3'),
language: 'en',
});
console.log(transcription.text);
음성 합성 (TTS)
엔드포인트: POST /v1/audio/speech
const speech = await openai.audio.speech.create({
model: 'tts-1',
voice: 'alloy', // alloy, echo, fable, onyx, nova, shimmer, sage, ash, ballad, coral, verse
input: '안녕하세요, OpenAI TTS입니다!',
});
const buffer = Buffer.from(await speech.arrayBuffer());
await fs.promises.writeFile('speech.mp3', buffer);
Moderation API
엔드포인트: POST /v1/moderations
const moderation = await openai.moderations.create({
model: 'omni-moderation-latest',
input: '악의적인 텍스트 예시입니다.',
});
if (moderation.results[0].flagged) {
console.log('콘텐츠가 검열되었습니다!');
console.log(moderation.results[0].categories); // true로 표시된 범주
}
오류 처리
일반 오류
| 오류 유형 | HTTP 상태 | 설명 |
|---|---|---|
InvalidRequestError | 400 | 잘못된 요청 (누락된 매개변수 등) |
AuthenticationError | 401 | 유효하지 않은 API 키 |
PermissionDeniedError | 403 | 엔드포인트에 접근 권한 없음 |
NotFoundError | 404 | 리소스를 찾을 수 없음 |
RateLimitError | 429 | 속도 제한 초과 |
InternalServerError | 500 | OpenAI 서버 오류 |
재시도 로직
import OpenAI from 'openai';
const openai = new OpenAI({
maxRetries: 3, // 429 및 500 오류에 대한 기본 재시도
timeout: 60000, // 60초 타임아웃
});
// npm ls openai로 패키지 버전 확인
속도 제한
처리 방법
- 재시도: SDK의
maxRetries사용 (권장: 3) - 백오프: 지수적 백오프로
Retry-After헤더 확인 - 모니터링:
x-ratelimit-remaining-requests및x-ratelimit-remaining-tokens헤더
import OpenAI from 'openai';
const openai = new OpenAI({ maxRetries: 3 });
const start = Date.now();
let retries = 0;
async function makeRequest() {
retries++;
try {
return await openai.chat.completions.create({
…
});
} catch (error: any) {
if (error.status === 429 && retries <= 3) {
const delay = Math.pow(2, retries) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
return makeRequest(); // 재시도
}
throw error;
}
}
프로덕션 베스트 프랙티스
- 오류 처리: 모든 API 호출에 try/catch 구현
- 재시도: 지수 백오프로 429 및 500 재시도
- 타임아웃: SDK 타임아웃 설정 (기본 10분,
timeout옵션 사용 가능) - 스트리밍: 긴 응답은 최상의 UX를 위해 스트리밍 사용
- 모니터링: OpenAI 대시보드에서 사용량 및 비용 추적
- 프롬프트 캐싱: 반복되는 프롬프트에 대해 GPT-5.1의 24시간 캐싱 활용
- 임베딩: 저장 공간과 검색 속도를 위해
dimensions매개변수 사용 - 속도 제한: 속도 제한을 사전에 처리하기 위해 헤더 모니터링
- 키 순환: 프로덕션 환경에서 API 키 정기적으로 교체
- 의존성 관리:
npm ls openai로 패키지 버전 확인
openai-responses와의 관계
이 스킬은 stateless Chat Completions API를 위한 것입니다. 상태 저장 대화 및 지속적인 추론이 필요한 경우 다음을 사용하세요:
- openai-responses 스킬: 상태 저장 대화, 지속적인 Chain of Thought, 컨텍스트 관리용