OpenAI API의 기본 구조

API Key는 코드가 아니라 환경변수에 둔다

OpenAI API를 호출하려면 먼저 API Key가 필요합니다. API Key는 "이 요청이 누구의 계정에서 온 것인지" 확인하는 인증 정보입니다. 비밀번호와 같으므로 코드에 직접 쓰면 안 됩니다.

로컬 개발에서는 보통 .env 파일에 저장합니다.

OPENAI_API_KEY="sk-..."

Node.js에서 OpenAI SDK를 사용할 때는 클라이언트를 만들며 키를 직접 넘기지 않아도 됩니다. 기본적으로 OPENAI_API_KEY 환경변수를 읽어 초기화할 수 있습니다.

import OpenAI from "openai";

const client = new OpenAI();

배포 환경에서는 .env 파일을 서버에 올리는 대신 Vercel, AWS, Railway 같은 배포 서비스의 환경변수 설정에 같은 이름으로 등록합니다. 핵심은 단순합니다. 개발 환경과 배포 환경은 분리하되, 코드에서는 같은 환경변수 이름을 사용한다는 것입니다.

AI 생성 이미지

요청은 모델, 입력, 옵션으로 구성된다

OpenAI API 호출은 크게 세 부분으로 볼 수 있습니다.

• model: 어떤 모델을 사용할지 정합니다.

• input 또는 messages: 모델에게 전달할 내용입니다.

• 옵션: 출력 길이, 응답 형식, 스트리밍 여부 등을 정합니다.

Responses API를 기준으로 보면 구조는 다음과 같습니다.

const response = await client.responses.create({
  model: "gpt-4.1-mini",
  input: "블로그 글 제목을 5개 추천해 줘.",
  max_output_tokens: 300,
});

console.log(response.output_text);
console.log(response.usage);

여기서 실제 생성된 텍스트는 response.output_text에서 꺼낼 수 있습니다. 비용 추적이나 로그가 필요하다면 response.usage 같은 사용량 정보도 함께 확인합니다. 예전 Chat Completions 방식에서는 messages 배열을 보내고, 결과를 choices[0].message.content에서 꺼내는 형태가 많이 쓰였습니다.¹

시스템 메시지와 사용자 메시지를 나눈다

AI 기능을 만들 때는 프롬프트를 한 문장으로 길게 합치기보다 역할을 나누는 편이 좋습니다.

시스템 메시지에는 서비스가 정한 기본 규칙을 둡니다.

너는 초보 개발자를 돕는 한국어 튜터다.
답변은 짧고 명확하게 작성한다.
모르는 내용은 추측하지 않는다.

사용자 메시지에는 매번 달라지는 실제 요청과 입력 데이터를 넣습니다.

다음 문장을 초보자가 이해하기 쉽게 설명해 줘.
문장: "토큰은 모델이 처리하는 텍스트 단위입니다."

이렇게 나누면 장점이 있습니다. 말투, 금지 규칙, 출력 형식 같은 서비스 정책은 재사용할 수 있고, 사용자가 입력한 값만 안전하게 바꿔 넣을 수 있습니다. 나중에 문제가 생겨도 "기본 지시가 문제인지, 사용자 입력이 문제인지" 추적하기 쉽습니다.

모델은 기능의 목적에 맞게 고른다

좋은 모델 선택은 "가장 강한 모델을 쓰는 것"이 아닙니다. 기능에 맞는 모델을 고르는 것입니다.

빠른 자동완성, 짧은 문장 다듬기, 태그 생성처럼 사용자가 즉시 반응을 기대하는 기능은 빠르고 저렴한 모델이 적합합니다. 반대로 복잡한 기획서 분석, 긴 문서 요약, 코드 리뷰처럼 정확도와 추론 품질이 중요한 작업은 더 강한 모델을 선택해야 합니다.

긴 문서를 다루는 기능에서는 컨텍스트 길이도 봐야 합니다. 컨텍스트는 모델이 한 번에 읽을 수 있는 입력 범위입니다. 문서가 길면 단순히 좋은 모델보다 긴 입력을 안정적으로 처리할 수 있는 모델이 필요합니다.

실무에서는 처음부터 하나의 모델만 고정하지 않습니다. 대량 처리에는 저비용 모델을 쓰고, 실패하거나 품질이 부족한 요청만 고품질 모델로 넘기는 방식도 사용할 수 있습니다.

토큰은 비용과 속도를 결정한다

API 비용은 보통 입력 토큰과 출력 토큰을 기준으로 계산됩니다. 토큰은 모델이 텍스트를 처리하는 단위입니다. 한국어 한 글자와 정확히 일치하지는 않지만, 문장이 길수록 토큰도 늘어난다고 이해하면 충분합니다.

예를 들어 사용자가 3,000토큰짜리 문서를 보내고 모델이 1,000토큰 답변을 생성한다면, 총 4,000토큰 규모의 요청이 됩니다. 같은 요청이 하루 1,000번 실행되면 하루 처리량은 약 400만 토큰입니다. 여기에 재시도, 실패 응답, 로그 분석용 추가 호출까지 더해지면 비용은 더 커집니다.

그래서 입력과 출력을 모두 제한해야 합니다. 불필요한 예시는 프롬프트에서 제거하고, 긴 문서는 필요한 부분만 보내며, max_output_tokens로 최대 출력 길이를 정합니다. "자세히 설명해 줘"보다 "5문장 이내로 요약해 줘"가 비용과 속도 모두 예측하기 쉽습니다.

OpenAI API의 기본 구조는 복잡하지 않습니다. 안전하게 키를 관리하고, 요청의 구성 요소를 이해하고, 메시지를 분리하고, 모델과 토큰을 의식하면 됩니다. 다음 단계는 이 구조를 실제 Node.js 코드로 호출해 보는 것입니다.

참고

¹OpenAI Python SDK 공식 저장소