호환 엔드포인트 · 인증 · 스트리밍
개발자 문서
호환 엔드포인트, 인증, 요청 형식, 스트리밍 응답 및 오류 처리에 관한 참조 문서입니다.
빠른 시작
엔드포인트와 Key를 설정하고 클라이언트를 연동한 다음 첫 요청을 보내세요.
엔드포인트 선택
클라이언트가 요구하는 형식을 선택하세요. Chat Completions, Responses, Messages 호환 경로를 사용할 수 있습니다.
Base URL: https://new.weeanno.shop/v1API Key 준비
유효한 API Key를 서버 환경에서 사용하고 브라우저 코드에 노출하지 마세요.
Authorization: Bearer sk-your-api-key클라이언트 연동
호환 SDK를 사용하거나 사용자 지정 base_url로 REST API를 직접 호출하세요.
client = OpenAI(base_url='https://new.weeanno.shop/v1')호출 시작
요청을 보내고 AI 응답을 받으세요. 더 빠른 체감 응답을 위한 스트리밍을 지원합니다.
POST /v1/chat/completions인증
모든 API 요청에는 HTTP Authorization 헤더에 API Key가 포함되어야 합니다.
인증 형식
모든 요청의 Authorization 헤더에 API Key를 추가하세요.
POST
/v1/chat/completions인증된 요청 예시
요청 예시
json
curl https://new.weeanno.shop/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-api-key" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'응답 예시
json
{
"id": "chatcmpl_123",
"object": "chat.completion",
"choices": [{
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
}
}]
}권장 Base URL
https://new.weeanno.shop/v1대부분의 클라이언트에서 사용합니다대체 Base URL
https://new.weeanno.shop검증 중 클라이언트가 /v1을 거부할 때만 사용합니다Chat Completions 호환 엔드포인트
/v1/chat/completionsChat Completions를 요구하는 클라이언트용Responses 호환 엔드포인트
/v1/responsesResponses 지원 클라이언트에서 우선 사용합니다Messages 호환 엔드포인트
/v1/messagesMessages 호환 클라이언트에서 우선 사용합니다Chat Completions API
여러 모델 생태계를 위한 OpenAI 호환 Chat Completions 엔드포인트입니다.
python
from openai import OpenAI
# 클라이언트 초기화
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://new.weeanno.shop/v1"
)
# 채팅 요청 전송
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "간결하게 답변하는 어시스턴트입니다."},
{"role": "user", "content": "한 문장으로 자기소개해 주세요."}
]
)
print(response.choices[0].message.content)요청 매개변수
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
model | string | 필수 | 모델 ID(예: gpt-4o-mini) |
messages | array | 필수 | 채팅 메시지 배열 |
temperature | number | 선택 | 0~2의 샘플링 온도, 기본값 1 |
max_tokens | integer | 선택 | 생성할 최대 Token 수 |
stream | boolean | 선택 | 스트리밍 출력 활성화 여부 |
top_p | number | 선택 | Nucleus Sampling 값, 기본값 1 |
응답 필드
| 필드 | 유형 | 설명 |
|---|---|---|
id | string | 응답 고유 식별자 |
object | string | 객체 유형, 일반적으로 chat.completion |
created | integer | 생성 타임스탬프 |
model | string | 응답에 사용된 모델 ID |
choices | array | 생성된 응답 선택지 |
usage | object | Token 사용량 통계 |
스트리밍
스트리밍을 활성화하면 생성되는 Token을 실시간으로 받아 체감 지연 시간을 줄일 수 있습니다.
스트리밍의 장점
- 낮은 체감 지연 - 전체 응답을 기다리지 않고 출력을 즉시 확인할 수 있습니다.
- 더 나은 장문 경험 - 긴 답변이 실시간 입력처럼 점진적으로 표시됩니다.
- 동일한 비용 - 동기 출력과 요금은 같고 전송 방식만 다릅니다.
python
from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://new.weeanno.shop/v1"
)
# 스트리밍 활성화
stream = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "간결하게 답변하는 어시스턴트입니다."},
{"role": "user", "content": "한 문장으로 자기소개해 주세요."}
],
stream=True
)
# 수신되는 Token을 순서대로 출력
for chunk in stream:
if chunk.choices[0].delta.content is not None:
print(chunk.choices[0].delta.content, end="")
print() # 줄 바꿈오류
일반적인 API 오류와 권장 처리 방법입니다.
| HTTP 상태 | 오류 이름 | 설명 | 권장 조치 |
|---|---|---|---|
400 | INVALID_REQUEST | 요청 본문 형식이 잘못되었거나 매개변수가 유효하지 않습니다 | 요청 본문과 매개변수를 확인하세요 |
401 | UNAUTHORIZED | API Key가 유효하지 않거나 만료되었습니다 | API Key가 올바른지 확인하세요 |
429 | RATE_LIMIT | 요청 속도 제한을 초과했습니다 | 지수 백오프로 다시 시도하세요 |
500 | INTERNAL_ERROR | 서비스 내부 오류입니다 | 잠시 후 다시 시도하세요 |
503 | SERVICE_UNAVAILABLE | 서비스를 일시적으로 사용할 수 없습니다 | 잠시 후 다시 시도하세요 |
요청 한도
서비스 안정성을 위해 API 요청 속도가 제한됩니다.
요청 한도 규칙
- 각 API Key에는 개별 요청 속도 제한이 있습니다
- 429 응답을 받으면 지수 백오프로 다시 시도하세요
- 스트리밍 및 비스트리밍 요청은 동일한 속도 제한 쿼터를 공유합니다
- 실제 한도는 현재 Key 설정을 따릅니다