이 가이드에서 다루는 내용
이 가이드는 OpenAI 플랫폼 계정을 만들거나 로그인하고, 결제를 설정하고, 시크릿 API 키를 만들고, 첫 요청을 보내고, 사용량을 확인하며, 흔한 키 오류를 해결하는 과정을 단계별로 안내합니다. 자신의 스크립트나 앱에서 OpenAI API를 호출하려는 사람을 위한 가이드입니다. ChatGPT 구독은 별도로 청구되는 제품이므로 이 가이드의 범위에 포함되지 않습니다.
사전 준비
- 계정: 직접 관리하고 복구할 수 있는 OpenAI 로그인 수단.
- 결제: 거주 지역에서 OpenAI가 제공하는 결제 수단 또는 선불 옵션. 이용 가능한 옵션은 지역마다 다르며, 전체 목록은 확인하지 못했습니다(UNKNOWN).
- 기본적인 코드 이해: 터미널을 열고, 환경 변수를 설정하고, 짧은 스크립트를 실행할 수 있어야 합니다. 예시는
curl과 Node.js를 사용하는 JavaScript를 사용합니다.
1단계: OpenAI 플랫폼 계정 만들기 또는 로그인하기
API 키 페이지를 엽니다. 안내에 따라 로그인하거나 계정을 만드세요. 본인이 소유한 계정을 사용하세요.
소속 조직에 이미 API 계정이 있다면 키를 공유하지 말고 조직 소유자에게 초대를 요청하세요. OpenAI의 멤버 관리 가이드에 관련 내용이 있습니다.
2단계: 결제를 추가하고 사용량 기반 요금 이해하기
OpenAI 오류 참조 문서에서 연결하는 결제 설정 페이지를 엽니다. 페이지에 나온 대로 결제 수단이나 크레딧을 추가하세요.
API 사용은 사용량에 따라 과금됩니다. OpenAI API 요금 페이지와 개발자 요금 참조에 요금이 나와 있습니다. 참조 문서에 따르면, 별도 표시가 없는 한 가격은 100만 토큰당으로 표시되며, 일부 내장 도구는 따로 나열되어 있습니다. 시작하기 전에 사용할 모델의 요금을 확인하세요. 요금은 바뀔 수 있고 모델마다 다르므로 이 가이드에서는 구체적인 금액을 적지 않습니다.
선불 잔액이 떨어지면 요청이 credit_balance_exhausted 오류로 실패할 수 있습니다. 아래 문제 해결 섹션을 참조하세요.
3단계: 시크릿 키를 만들고 한 번만 복사하기
- API 키 페이지를 엽니다.
- 새 시크릿 키를 만들고, 이를 사용할 앱이나 스크립트에 맞는 이름을 붙이세요.
- 키를 즉시 복사해 비밀번호 관리자에 저장하세요. OpenAI의 API 키 도움말 문서에 따르면 전체 시크릿 키는 생성할 때만 표시됩니다. 잃어버리면 새 키를 만들고 애플리케이션을 업데이트하세요. 삭제된 키는 사용할 수 없습니다.
- 키를 채팅, 스크린샷, 소스 코드에 붙여넣지 마세요.
API 키 페이지의 텍스트를 읽지 못했기 때문에 버튼 이름은 이 단계와 다를 수 있습니다.
4단계: 첫 번째 API 호출하기
코드에 키가 들어가지 않도록 환경 변수에 저장하세요. macOS나 Linux에서는 터미널에서 아래 명령을 실행하고, 플레이스홀더를 자신의 키로 바꾸세요.
export OPENAI_API_KEY="your_api_key_here"
Windows PowerShell에서는 아래 명령을 사용한 다음 새 터미널 창을 여세요.
setx OPENAI_API_KEY "your_api_key_here"
curl로 테스트합니다. MODEL_ID는 계정에서 사용할 수 있는 모델로 바꾸세요.
curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "MODEL_ID",
"input": "Say hello in one short sentence."
}'
JavaScript라면 npm install openai로 공식 SDK를 설치하고, 아래 내용을 hello.mjs로 저장하세요.
import OpenAI from "openai";
// The SDK reads OPENAI_API_KEY from the environment.
const client = new OpenAI();
const response = await client.responses.create({
model: "MODEL_ID",
input: "Say hello in one short sentence.",
});
console.log(response.output_text);
node hello.mjs로 실행합니다. 개발자 퀵스타트도 같은 방식을 사용합니다. 오류가 나면 문제 해결 섹션으로 가세요.
5단계: 사용량 확인하기
호출이 성공하면 플랫폼 계정의 사용량 대시보드를 열고 요청이 표시되는지 확인하세요. OpenAI의 사용량 내보내기 문서는 API Usage Dashboard를 설명합니다. 거기서 월별 사용량을 보고, 달력 월 전체 또는 월초부터 현재까지의 사용량이나 비용 데이터를 CSV로 내보낼 수 있습니다. 요청이 아직 보이지 않으면 나중에 다시 확인하세요. 반영까지 걸리는 시간은 확인하지 못했습니다(UNKNOWN).
API를 무료로 사용할 수 있나요?
OpenAI 요금 페이지는 사용량 기반 요금을 보여줍니다. 신규 계정에 무료 크레딧이 주어지는지, 또는 어떤 모델에든 무료 등급이 있는지는 공식 페이지에서 확인하지 못했습니다(UNKNOWN). 요금 참조 문서에는 무료로 표시되거나 무료 할당량이 포함된 항목도 있습니다. 예를 들어 일부 파일 저장소는 1 GB까지 무료이며, 무료 콘텐츠 모더레이션 모델도 나열되어 있습니다. 어떤 호출이든 무료라고 가정하기 전에, 사용하는 모델과 도구에 대한 현재 요금 페이지를 확인하세요.
키를 안전하게 보관하려면 어떻게 해야 하나요?
OpenAI의 API 키 안전 모범 사례를 따르세요. 실제로는 다음과 같습니다.
- 키를 git에 커밋하지 마세요. 키는 환경 변수나 로컬 시크릿 저장소에 보관하고,
.env파일은.gitignore에 추가하세요. 푸시하기 전에 스테이징된 변경 사항을 매번 검토하세요. - 노출되면 교체하세요. 키가 저장소, 로그, 스크린샷, 채팅에 나타나면 API 키 페이지에서 삭제하고, 새 키를 만든 다음, 애플리케이션을 업데이트하세요. 삭제된 키는 더 이상 작동하지 않습니다.
- 프로젝트마다 키를 하나씩 쓰세요. 앱, 스크립트, 팀원마다 별도의 키를 주세요. OpenAI는 API 키 공유가 이용 약관에 어긋난다고 밝혔으므로, 팀원은 각자의 계정으로 초대하세요.
- 만료일을 설정하세요. 프로젝트 키는 특정 날짜에 만료되도록 설정할 수 있습니다. 만료 전에 대체 키를 만들고, 새 키가 작동하는 것을 확인한 뒤 이전 키를 폐기하세요.
- 지원 요청에 키를 포함하지 마세요. 어떤 지원 채널에도 키를 보낼 필요가 없습니다.
키가 작동하지 않는 이유는 무엇인가요?
상태 코드와 오류 메시지를 읽은 다음, OpenAI 오류 참조 문서와 대조하세요.
| 상태 코드 및 메시지 | 가능한 원인 | 해결 방법 |
|---|---|---|
401 Incorrect API key provided | 키가 잘못되었거나, 삭제되었거나, 다른 계정의 키임 | API 키 페이지에서 키를 확인하세요. 코드 전체에서 같은 키를 쓰고 있는지 확인하세요. Incorrect API key provided를 참조하세요. |
401 You must be a member of an organization | 계정이 키를 소유한 조직에 속해 있지 않음 | 조직 관리자에게 초대를 요청하세요. |
401 IP not authorized | 요청 IP 주소가 허용 목록에 없음 | 허용된 IP에서 요청을 보내거나 허용 목록을 업데이트하세요. |
429 Rate limit reached for requests | 짧은 시간에 요청이나 토큰이 너무 많음 | 요청 속도를 늦추고, Retry-After 헤더가 있으면 그 안내를 따르세요. 속도 제한 가이드와 429 문제 해결 문서를 참조하세요. |
429 credit_balance_exhausted | 선불 크레딧을 모두 사용함 | 결제 설정에서 크레딧을 추가하세요. 재시도만으로는 해결되지 않습니다. |
429이며 오류 유형이 insufficient_quota | 결제 관련 한도에 도달함 | 결제와 사용 한도를 확인한 다음 429 문제 해결 문서를 따르세요. |
403 Country, region, or territory not supported | 지원되지 않는 국가 또는 지역에서 API에 접근함 | 오류 참조 문서가 연결하는 지원 국가 및 지역 목록을 확인하세요. |
여기에 없는 메시지는 오류 참조 문서에서 정확한 문구로 검색하세요. 모든 403 메시지의 의미는 확인하지 못했습니다(UNKNOWN).
Cue에 내 OpenAI API 키가 필요한가요?
UNKNOWN입니다. Cue의 공개 페이지(heycue.io, 가격, FAQ)를 확인했습니다. 모델은 나열되어 있었지만, 제가 읽은 내용에서는 Cue 자체 기능에 사용자의 OpenAI API 키가 필요한지 설명하지 않았습니다. 어느 쪽에든 의존하기 전에 Cue 설정과 요금제 설명을 확인하세요. API 키는 절대 Cue 지원팀에 보내지 마세요.
확인하지 못했거나 사용할 수 없었던 항목
platform.openai.com/docs/quickstart는 출처가 다른 리디렉션이 발생해 따라가지 않았습니다. 대신developers.openai.com/api/docs/quickstart의 Markdown 버전을 사용했습니다.platform.openai.com/api-keys는 읽을 수 있는 페이지 텍스트를 반환하지 않았습니다. 키 단계는 OpenAI 도움말 문서에 근거했고, 버튼 이름은 확인하지 못했습니다.openai.com/api/pricing/은 제 가져오기에서 잘렸습니다. 요금은 개발자 요금 참조 문서에서 가져왔습니다. 이 문서에는 구체적인 금액을 적지 않았습니다.- 신규 계정의 무료 크레딧 또는 무료 등급: UNKNOWN.
- 모든 403 메시지의 의미: 국가 또는 지역 사례 외에는 UNKNOWN.
- Cue에 사용자의 OpenAI API 키가 필요한지 여부: UNKNOWN.
Cue는 Sophon LLC가 개발한 독립 데스크톱 AI 어시스턴트입니다. Cue를 사용해 승인된 문서, 메모, 작업을 처리할 수 있으며, Claude와 GPT 모델 옵션을 선택할 수 있습니다. 계정에 포함된 내용과 사용 가능한 모델은 Cue 요금제 설명에서 확인하세요. OpenAI 계정의 API 키, 결제, 사용량은 계속 OpenAI가 관리합니다.