OpenAI API 연결 가이드: Chat Completions 호환 및 키 설정

1. 개요

본 사이트는 OpenAI Chat Completions(/v1/chat/completions) 형식 호환 연결을 지원합니다. OpenAI 공식 SDK나 OpenAI 호환 클라이언트에서 이미 작동하는 코드라면, 요청 주소를 본 사이트 게이트웨이의 OpenAI 엔드포인트로 설정하고 api_key를 사이트에서 발급받은 sk- 키로 교체하기만 하면 됩니다. 나머지 호출 방식은 동일합니다.

현재 사용 가능한 GPT 시리즈 모델은 모델 광장을 기준으로 합니다(예: gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna 등). 전체 목록과 단가는 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.5",
    "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.5",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(resp.choices[0].message.content)

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

5. 요청 매개변수

필드	타입	필수	설명
model	string	예	모델 슬러그, 예: gpt-5.5
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.5",
  "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: 행은 하나의 청크(chunk)입니다:

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) 초과	지수 백오프 후 재시도
500	서비스 내부 오류	나중에 재시도, 지속 발생 시 고객 센터 문의

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

9. 호환성 참고사항

• OpenAI SDK(Python / Node.js 등)에서 base_url 커스텀 설정을 통한 연결 지원.
• 다양한 OpenAI 호환 클라이언트(LobeChat, ChatBox, NextChat, One API 등)에서 사용자 지정 인터페이스 주소 구성 지원.
• 모델명은 GET /v1/models로 반환되는 슬러그를 기준으로 함.

Base URL 참고: 본 사이트는 /v1beta/models/...와 /v1beta/v1beta/models/... (및 /v1/...와 /v1/v1/...)을 모두 허용하므로, 클라이언트가 직접 /v1이나 /v1beta를 붙여도 호출에는 영향을 주지 않습니다. Base URL에 도메인 루트를 입력하거나 /v1beta가 포함된 주소를 입력해도 모두 작동합니다. 모델 ID는 콘솔의 「토큰」 페이지 우측 상단 「모델 ID」에서 조회 및 복사할 수 있습니다.