OpenAI API 액세스 가이드: Chat Completions 호환 및 키 설정

1. 개요

본 사이트는 OpenAI Chat Completions(/v1/chat/completions) 형식의 호환 액세스를 제공합니다. OpenAI 공식 SDK 또는 OpenAI 호환 클라이언트에서 실행되는 기존 코드는 요청 주소를 본 사이트 게이트웨이의 OpenAI 엔드포인트로 변경하고 api_key를 사이트 내 sk- 키로 교체하기만 하면 됩니다. 그 외 호출 방식은 동일합니다.

현재 사용 가능한 GPT 시리즈 모델은 모델 광장(Model Square) 기준을 따르며(예: gpt-5.4, gpt-5.5, gpt-5.4-mini, gpt-4o 등), 전체 목록 및 단가는 GET /v1/models를 통해 조회할 수 있습니다.

2. 인터페이스 주소

메서드	경로	설명
POST	/v1/chat/completions	채팅 완성(비스트리밍 / 스트리밍), 요청 본문은 OpenAI 페이로드와 동일
GET	/v1/models	모델 및 단가 목록(인증 불필요)

게이트웨이 주소: https://www.relay-api.com. OpenAI 호환 호출 시 요청을 POST https://www.relay-api.com/v1로 보내고, 경로는 그대로 입력하십시오.

3. 인증 방식

Authorization: Bearer sk-본인의키

「사용자 센터 → API 키」에서 sk-로 시작하는 키를 생성하십시오. 공식 OpenAI와 동일한 인증 헤더를 사용하며, SDK가 자동으로 Authorization 헤더를 추가합니다.

4. 빠른 시작

4.1 curl (비스트리밍)

curl -X POST https://www.relay-api.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-본인의키" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "system", "content": "당신은 도움이 되는 어시스턴트입니다."},
      {"role": "user", "content": "자기소개를 세 문장으로 해주세요"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

4.2 OpenAI SDK (Python)

from openai import OpenAI

client = OpenAI(
    base_url="https://www.relay-api.com/v1",
    api_key="sk-본인의키",
)

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(resp.choices[0].message.content)

base_url을 위 표의 OpenAI 엔드포인트로 설정하고 api_key를 교체하면, 나머지 호출 방식은 공식 SDK와 완전히 동일합니다.

5. 요청 매개변수

필드	타입	필수	설명
model	string	예	모델 slug, 예: gpt-5.4
messages	array	예	메시지 목록, 요소는 {role, content}; role 값은 system / user / assistant
temperature	number	아니오	샘플링 온도, 기본값 1.0
top_p	number	아니오	핵 샘플링, 기본값 1.0
max_tokens	int	아니오	최대 출력 토큰 수
stream	bool	아니오	스트리밍 응답 여부, 기본값 false
stop	string / array	아니오	중단 시퀀스
presence_penalty / frequency_penalty	number	아니오	반복 페널티, 범위 -2~2

6. 응답 구조

{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "안녕하세요! 만나서 반갑습니다."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 12,
    "total_tokens": 30
  }
}

필드	설명
id	이번 완성 작업의 고유 ID
choices[].message	어시스턴트 응답, content는 텍스트 내용
choices[].finish_reason	종료 사유: stop / length / content_filter
usage.prompt_tokens	입력 토큰 수 (과금 기준)
usage.completion_tokens	출력 토큰 수 (과금 기준)
usage.total_tokens	총 토큰 수

7. 스트리밍 출력

요청 본문에 "stream": true를 추가하면 SSE 스트림이 반환되며, 각 data: 행은 청크입니다:

data: {"id": "chatcmpl-123456", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": {"role": "assistant"}, "finish_reason": null}]}

data: {"id": "chatcmpl-123456", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": {"content": "안녕하세요"}, "finish_reason": null}]}

data: {"id": "chatcmpl-123456", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}]}

data: [DONE]

클라이언트는 각 청크의 choices[0].delta.content를 이어 붙여 전체 응답을 완성할 수 있습니다. [DONE] 수신 시 스트림이 종료됩니다. OpenAI SDK에서 stream=True를 설정하면 이러한 이벤트를 자동으로 처리합니다.

8. 일반적인 오류 코드

HTTP 상태 코드	의미	처리 권장 사항
400	요청 매개변수 유효하지 않음 (모델 없음, messages 비어 있음 등)	요청 본문 필드 확인
401	유효하지 않거나 누락된 API 키	Authorization 헤더 및 키 형식 확인
403	키 비활성화, 잔액 부족, 또는 해당 모델/경로에 대한 권한 없음	충전 또는 키 권한 확인
404	경로 또는 모델 존재하지 않음	base_url 및 모델 이름 확인
429	속도 제한(Rate Limit) 초과	지수 백오프(Exponential backoff) 후 재시도
500	서비스 내부 오류	잠시 후 재시도, 지속 발생 시 고객센터 문의

오류 응답 본문은 항상 {"code": 상태코드, "message": "오류 설명", "data": null} 구조입니다.

9. 호환성 참고사항

• 사용자 정의 base_url을 통해 OpenAI SDK(Python / Node.js 등) 액세스를 지원합니다.
• 다양한 OpenAI 호환 클라이언트(LobeChat, ChatBox, NextChat, One API 등)의 사용자 정의 인터페이스 주소 설정을 지원합니다.
• 모델 이름은 GET /v1/models 호출 시 반환되는 slug를 기준으로 합니다.