OpenAI API 연동 가이드: 계정, 키, Base URL, 첫 호출 (2026)

OpenAI API 연동에 필요한 것은 네 가지입니다. 로그인할 수 있는 계정, 사용 가능한 API 키, 결제가 활성화된 프로젝트, 그리고 올바른 Base URL과 한 번의 성공적인 호출입니다. 간단해 보이지만 새 팀이 실제로 막히는 곳은 코드가 아니라 계정 체계, 결제 수단, 주소 조합입니다.

이 글은 실제 작업 순서를 따릅니다. 계정과 프로젝트, 키 생성, 충전, SDK 설치, Responses API로 첫 호출, 사용량 확인, 401과 429 점검, 마지막으로 Base URL을 OpenAI 호환 게이트웨이로 전환하는 방법을 다룹니다. 예제는 Responses API를 중심으로 하며, Chat Completions만 지원하는 구형 도구는 같은 방식으로 엔드포인트만 바꾸면 됩니다.

안내: OpenAI, ChatGPT, GPT는 OpenAI의 상표입니다. 이 글은 2026년 10월의 공개된 API 동작을 기준으로 하며, 모델 이름, 할당량, 가격은 모델 가격 페이지와 공식 문서를 기준으로 합니다.

1. 계정, 조직, 프로젝트는 각각 무엇인가

OpenAI 플랫폼에는 최소 세 층이 있고, 이를 섞으면 오류가 나기 쉽습니다.

계정: 로그인 자격 증명으로, 누가 콘솔에 들어올 수 있는지를 결정합니다.
조직: 결제와 사용량의 귀속 단위로, 팀 협업은 보통 조직 단위로 관리합니다.
프로젝트: 키, 사용량, 권한의 격리 단위로, 환경이나 업무별로 나누는 것이 좋습니다.

흔한 오해는 ChatGPT 구독을 API 잔액으로 생각하는 것입니다. 둘은 별개입니다. 구독은 채팅 제품 사용권이고, API는 실제 호출량에 따라 별도로 과금됩니다. 팀 도입 전에 누가 계정을 맡고, 누가 결제하며, 누가 관리자 권한을 갖는지 정해 두어야 나중에 담당자가 바뀌어도 키의 소유자를 찾을 수 있습니다.

2. API 키를 만드는 순서

아래 단계를 건너뛰지 말고 따르세요.

관리자 계정으로 API 콘솔에 로그인하고 현재 조직이 맞는지 확인합니다.
조직 아래에 새 프로젝트를 만들거나 기존 프로젝트를 선택합니다. 개발, 테스트, 운영은 분리합니다.
프로젝트의 API Keys 페이지에서 새 키를 만듭니다.
키에 용도를 알 수 있는 이름을 붙입니다. 예: "운영-고객지원 봇".
전체 키를 즉시 복사해 비밀번호 관리자나 배포 플랫폼의 시크릿 관리에 보관합니다.
필요에 따라 프로젝트 권한, 예산, 할당량 상한을 설정한 뒤 저장합니다.

전체 키는 보통 생성 시 한 번만 표시됩니다. 페이지에 앞뒤 몇 자리만 남는 것은 정상이며, 나중에 다시 복사할 수 있다고 기대하면 안 됩니다. 잃어버렸다면 새 키를 만들고 기존 키를 비활성화하세요. 복구를 시도하지 마세요.

3. 충전, 청구, 할당량

API가 선불인지 후불인지는 계정 유형과 지역에 따라 다르며, 콘솔에 표시되는 내용이 기준입니다. 개통 전에 세 가지를 확인하세요.

결제 수단이 보유한 카드나 채널을 지원하는가.
청구 주기와 인보이스는 어떻게 받는가.
프로젝트에 예산 알림과 하드 상한을 설정할 수 있는가.

결제 실패는 연동 단계에서 자주 발생합니다. 카드가 거절되면 청구지 주소, 카드 소유자 이름, 인증 방식을 먼저 확인하고 발급사에 문의하세요. 짧은 시간에 반복 제출하면 일부 리스크 관리 시스템이 잠글 수 있습니다. 게이트웨이를 쓰는 팀은 보통 위안화로 충전할 수 있으며, 구체적인 요율과 입금 규칙은 가격 페이지를 기준으로 합니다. 가격은 조정될 수 있으므로 주문 전에 페이지에 표시된 내용을 확인하세요.

4. SDK 설치와 첫 curl 요청

먼저 공식 Python SDK를 설치합니다.

python3 -m pip install --upgrade openai
export OPENAI_API_KEY="sk-여기에-키"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="가격 페이지나 공식 문서에서 복사한 모델 이름"

curl로 Responses API를 호출해 주소, 키, 네트워크가 모두 통하는지 확인합니다.

curl -sS "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "input": "API 게이트웨이가 무엇인지 한 문장으로 설명해 주세요."
  }'

모델 이름은 기억에 의존하지 말고 가격 페이지나 공식 문서에서 현재 사용 가능한 이름을 복사해 OPENAI_MODEL 환경 변수에 넣으세요. 200이 반환되고 응답 본문에 출력이 있으면 연결이 된 것입니다. 401이면 키를, 404면 Base URL과 모델 이름을 먼저 확인하세요.

5. Python 첫 호출

아래는 Responses API로 최소 요청을 보내고 텍스트 결과를 출력하는 예제입니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)

resp = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="당신의 능력 범위를 세 문장으로 소개해 주세요.",
)

print(resp.output_text)

프레임워크가 Chat Completions만 지원한다면 호출을 client.chat.completions.create(...)로 바꾸고 메시지를 messages에 넣으면 됩니다. 두 인터페이스는 요청 경로가 다르므로 섞어 쓰면 404가 나기 쉽습니다.

6. 사용량과 청구 내역 읽기

콘솔의 Usage 페이지는 보통 프로젝트, 모델, 시간 세 축으로 소비량을 보여 주고 입력과 출력을 구분합니다. 연동 초기에는 매일 한 번 확인하며 다음을 점검하세요.

어느 프로젝트가 소비하는가.
입력과 출력이 각각 얼마나 차지하는가.
비정상적인 실패 재시도가 있는가.
예산 알림이 실제로 작동하는가.

호출 응답의 요청 ID는 로그에 남겨 두세요. 과금 분쟁이나 장애가 생겼을 때 요청 ID는 서비스 제공자가 문제를 찾는 첫 번째 단서입니다. 또한 애플리케이션 쪽에서 사용자, 기능 모듈, 요청 ID의 대응 관계를 기록해야 합니다. 그렇지 않으면 청구서에서는 총량만 보이고 원인 귀속은 할 수 없습니다.

7. 401과 429 점검 방법

401은 신원이 인정되지 않았다는 뜻입니다. 순서대로 확인하세요. 요청 헤더에 Bearer가 있는지, 키에 공백이나 줄바꿈이 섞이지 않았는지, 키가 삭제되었거나 소속 프로젝트가 비활성화되지 않았는지, 게이트웨이 키를 공식 주소로 보내고 있지는 않은지. 키를 교체하기 전에 요청이 실제로 어디로 가는지 먼저 확인하지 않으면 헛수고가 될 수 있습니다.

429에는 두 가지 의미가 있습니다. 속도 제한과 잔액 부족입니다. 응답 본문의 오류 코드와 헤더를 보고, 무조건 속도를 낮추지 마세요. insufficient_quota는 보통 잔액이나 할당량을 가리키므로 충전하거나 프로젝트 상한을 조정해야 합니다. 지수 백오프는 속도 관련 오류에만 적합합니다. 재시도는 429, 5xx, 네트워크 오류에만 의미가 있고, 400, 401, 403, 404를 재시도하면 할당량만 낭비됩니다. 더 자세한 점검 순서는 모델 가격 페이지의 관련 안내를 참고하세요.

8. 공식 직결과 호환 게이트웨이 선택

항목	공식 직결	OpenAI 호환 게이트웨이
접속 주소	`https://api.openai.com/v1`	게이트웨이가 제공하는 Base URL, 보통 `/v1`로 끝남
계정과 결제	공식 계정, 공식 지원 결제 수단	사이트 내 계정 가입, 위안화 충전과 인보이스 지원
네트워크	로컬 네트워크와 국경 간 회선에 따라 다름	보통 중국 내에서 접속 가능한 진입점 제공
모델 범위	OpenAI 자체 모델	여러 업체 모델을 함께 제공할 수 있음, 가격 페이지 기준
과금	공식 청구서	사이트 내 잔액과 사용량 기록
장애 처리	공식 지원 채널	게이트웨이가 업스트림을 점검, 사용자는 요청 ID 보관
적합한 상황	OpenAI만 사용하고 규정을 충족하는 결제 경로가 있음	중국 내 팀, 멀티 모델, 통합 청구를 원함

선택할 때 단가만 보지 마세요. 결제가 원활한지, 장애 시 누가 처리하는지, 모델을 언제든 바꿀 수 있는지가 장기 비용에 영향을 줍니다. 가격은 변동될 수 있으므로 가격 페이지를 기준으로 합니다.

9. 호환 게이트웨이로 전환: Base URL만 변경

호환 게이트웨이는 요청 형식을 그대로 유지하므로 전환 비용은 생각보다 낮습니다. 순서는 다음과 같습니다.

게이트웨이에 가입하고 키를 만듭니다. 진입점은 가입 페이지입니다.
OPENAI_BASE_URL을 게이트웨이 주소로 바꾸고 /v1은 유지합니다.
키를 게이트웨이 키로 교체하고 두 키를 섞어 쓰지 않습니다.
모델 이름은 게이트웨이 가격 페이지에서 복사하고, 공식 이름을 그대로 써서 맞기를 기대하지 마세요.
먼저 /v1/models와 최소 요청을 호출한 뒤 운영 트래픽을 전환합니다.
공식 또는 대체 회선을 폴백으로 남겨 둡니다.

"OpenAI 호환"은 요청과 응답 형식의 호환이며 모든 확장 기능이 완전히 같다는 뜻은 아닙니다. 파일, 배치, 도구 호출 등 고급 인터페이스의 지원 여부는 게이트웨이 문서에서 항목별로 확인하고, 전부 사용 가능하다고 가정하지 마세요. 호환 범위의 세부 내용은 모델 가격 페이지와 공식 문서를 함께 참고하세요.

10. 키 보안과 출시 전 점검

키가 유출되면 곧바로 비용이 발생합니다. 최소 요구 사항은 다음과 같습니다.

키는 서버 환경 변수나 시크릿 관리 서비스에만 두고, 프런트엔드 코드에 쓰거나 Git에 커밋하지 않습니다.
환경별로 키를 분리하고 테스트와 운영이 같은 키를 쓰지 않게 합니다.
각 키에 담당자와 용도를 표시하고, 퇴사나 프로젝트 변경 시 즉시 비활성화합니다.
로그에 전체 키를 출력하지 않고 뒤 네 자리만 남깁니다.
정기적으로 교체하고, 비정상 호출이 발견되면 즉시 폐기합니다.

출시 전 체크리스트:

[ ] 계정, 조직, 프로젝트 귀속이 명확하다.
[ ] 결제 수단을 사용할 수 있고 예산 알림이 설정되어 있다.
[ ] 키가 환경 변수나 시크릿 관리에 저장되어 있다.
[ ] Base URL에 /v1이 한 번만 들어 있다.
[ ] 최소 요청이 200을 반환하고 응답 내용이 정상이다.
[ ] 429 백오프와 5xx 재시도가 구성되어 있다.
[ ] 사용량 로그에 요청 ID, 모델, 소요 시간이 포함된다.
[ ] 대체 회선과 키 비활성화 절차를 리허설했다.

11. 자주 묻는 질문

API 키와 ChatGPT 구독은 같은 것인가요?

아닙니다. 구독과 API는 별도로 과금되며, API 키는 API 플랫폼에서만 만들고 관리합니다. 팀 비용 정산 시 두 지출을 구분해야 합니다.

생성 후 전체 키가 보이지 않는 이유는 무엇인가요?

전체 키는 보통 생성 시 한 번만 표시되고, 플랫폼은 식별용으로 일부 문자만 보관합니다. 잃어버리면 새 키를 만들고 기존 키를 비활성화해야 합니다.

Base URL은 어디까지 적어야 하나요?

도메인에 /v1을 붙인 곳까지 적고, /chat/completions나 /responses는 붙이지 마세요. 경로는 SDK나 요청이 직접 조합하므로 한 단계 더 붙이면 404가 납니다.

하나의 키를 여러 프로젝트에 써도 되나요?

기술적으로는 가능하지만 관리상 권장하지 않습니다. 프로젝트나 환경별로 키를 나눠야 권한을 제어하고 사용량을 파악하며, 유출 시 영향을 줄일 수 있습니다.

중국 내 팀은 반드시 게이트웨이를 써야 하나요?

반드시 그렇지는 않습니다. 결제 채널, 네트워크 품질, 규정 요구 사항, 멀티 모델 필요 여부에 따라 다릅니다. OpenAI만 사용하고 결제와 네트워크가 안정적이라면 직결도 가능합니다. 위안화 정산과 통합 진입점이 필요한 팀은 모델 가격 페이지를 참고해 전환 방식을 검토할 수 있습니다.

다음 단계

먼저 최소 요청을 성공시킨 뒤 업무에 연결하세요. 위안화 충전과 통합 멀티 모델 진입점이 필요하다면 ZSQH AI Gateway에 가입하는 것부터 시작할 수 있습니다. 모델과 가격은 모델 가격을 기준으로 합니다.