Gateway API
Gateway는 Planet에 등록한 AI 모델을 하나의 주소로 호출하게 해 주는 중계입니다. OpenAI API와 같은 형식이라 OpenAI SDK의 기본 주소만 바꾸면 그대로 쓸 수 있습니다.
개요
| 항목 | 값 | 설명 |
|---|---|---|
| 기본 주소 | URL | https://swdev.co.kr/api/llm/v1 |
| 인증 | 헤더 | 범위에 Gateway가 있는 API 키 (Authorization: Bearer swd_…) |
| 모델 이름 (model) | 문자열 | Gateway > Models의 이름(별칭, 없으면 모델 ID) 또는 Gateway > Routes의 라우트 이름 |
- 라우트로 부르면 라우트에 정한 순서대로 다른 모델로 다시 시도하고(폴백), 한도 · 캐시가 적용됩니다.
- 모델은 종류(LLM · 임베딩 · 리랭크 · 결정 · 이미지 · 음성)마다 부르는 경로가 다릅니다. 다른 종류의 경로로 부르면 400
model_kind_mismatch입니다. - 호출 기록 · 토큰 · 비용은 Gateway의 Overview · Log에서 확인합니다.
빠른 시작
from openai import OpenAI
client = OpenAI(base_url="https://swdev.co.kr/api/llm/v1", api_key="swd_…")
res = client.chat.completions.create(
model="chat-default",
messages=[{"role": "user", "content": "안녕하세요"}],
)
print(res.choices[0].message.content)import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'https://swdev.co.kr/api/llm/v1', apiKey: process.env.SWDEV_API_KEY });
const res = await client.chat.completions.create({
model: 'chat-default',
messages: [{ role: 'user', content: '안녕하세요' }],
});
console.log(res.choices[0].message.content);curl https://swdev.co.kr/api/llm/v1/chat/completions \
-H "Authorization: Bearer $SWDEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "chat-default", "messages": [{"role": "user", "content": "안녕하세요"}]}'예시의 chat-default 자리에는 Planet에 등록한 모델 · 라우트 이름을 넣으십시오. 부를 수 있는 이름은 GET /models로 확인합니다.
경로
| 경로 (/api/llm/v1 아래) | 설명 |
|---|---|
GET /models | 이 키로 부를 수 있는 모델 · 라우트 |
POST /chat/completions | LLM 채팅 (스트림 포함) |
POST /embeddings | 임베딩 |
POST /rerank | 리랭크 (Cohere · Jina 형식) |
POST /systemone | 결정 (TypeSafe Jev 형식) |
POST /images/generations | 이미지 생성 |
POST /audio/speech | 음성 합성 (글 → 음성) |
POST /audio/transcriptions | 음성 인식 (음성 → 글) |
OpenAI의 Responses API(/responses)는 받지 않습니다. SDK에서는 client.responses.create 대신 client.chat.completions.create를 쓰십시오.
모델 목록
라우트가 먼저 오고, 그다음 켜진 모델이 옵니다. kind는 그 이름을 부를 경로의 종류입니다(chat · embedding · rerank · decision · image · audio). 키에 허용 라우트를 정했으면 그 라우트만 보입니다.
{
"object": "list",
"data": [
{ "id": "chat-default", "object": "model", "created": 1793328000, "owned_by": "route", "kind": "chat" },
{ "id": "text-embedding-3-small", "object": "model", "created": 1793328000, "owned_by": "openai", "kind": "embedding" }
]
}채팅
OpenAI Chat Completions와 같습니다. messages · tools · response_format · stream 등을 그대로 보내고, 모델이 지원하지 않는 값은 맞게 바꾸거나 빼고 보냅니다 (응답 헤더 x-llm-dropped-params · x-llm-adjusted-params).
stream = client.chat.completions.create(
model="chat-default",
messages=[{"role": "user", "content": "세 줄로 요약해 주세요"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")- 첫 답이 늦으면 15초 뒤부터 SSE 주석(
: ping)으로 연결을 유지합니다. 답을 보내기 전에 실패하면 다른 모델로 다시 시도하므로 호출하는 쪽은 알 필요가 없습니다. - 답을 보내는 도중 끊기면
{"error": {"code": "stream_interrupted", …}}이벤트를 보내고[DONE]없이 끝납니다. OpenAI SDK는 오류를 올립니다. stream_options.include_usage를 켜면 마지막 사용량 청크의x_llm에 비용 · 시도 정보가 들어 있습니다.
임베딩
| 필드 | 형식 | 설명 |
|---|---|---|
model | 문자열 | 임베딩 모델 · 라우트 이름 |
input | 문자열 | 문자열 배열 | 2,048개까지. 토큰 배열은 받지 않습니다. |
dimensions | 정수 (선택) | 모델이 지원하면 차원 수 |
encoding_format | float | base64 (선택) | base64는 float32 little-endian |
res = client.embeddings.create(model="text-embedding-3-small", input=["첫 문장", "둘째 문장"])
vectors = [d.embedding for d in res.data]리랭크
질문과 관련도가 높은 문서 순서로 돌려줍니다. OpenAI SDK에는 없는 경로라 HTTP로 부릅니다.
| 필드 | 형식 | 설명 |
|---|---|---|
model | 문자열 | 리랭크 모델 · 라우트 이름 |
query | 문자열 | 질문 |
documents | 문자열 | {text} 배열 | 1,000개까지 |
top_n | 정수 (선택) | 돌려받을 개수 |
return_documents | 불리언 (선택) | 결과에 문서 본문도 넣기 |
curl https://swdev.co.kr/api/llm/v1/rerank \
-H "Authorization: Bearer $SWDEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "rerank-v3.5", "query": "휴가 신청 방법", "documents": ["연차는 사내 포털에서 신청합니다.", "식당은 2층에 있습니다."], "top_n": 1}'{
"id": "…",
"model": "rerank-v3.5",
"results": [{ "index": 0, "relevance_score": 0.93 }],
"usage": { "total_tokens": 31 }
}결정
상황(state)을 주고 질문마다 선택(choice) · 점수(score) · 예/아니오(noul)로 답을 받습니다. 형식이 틀리면 모델을 부르기 전에 400으로 알려 줍니다.
| 필드 | 형식 | 설명 |
|---|---|---|
model | 문자열 | 결정 모델 · 라우트 이름 |
state | 문자열 | JSON | 판단할 상황 |
questions | {이름: 질문} | 질문 400개까지. 질문마다 type · instructions, choice · score 는 criteria도 |
{
"model": "jev-latest",
"state": "고객이 배송이 늦다며 환불을 요청했습니다.",
"questions": {
"intent": {
"type": "choice",
"instructions": "고객의 요청 종류",
"criteria": { "refund": "환불 요청", "exchange": "교환 요청", "inquiry": "단순 문의" }
},
"urgent": { "type": "noul", "instructions": "바로 응대해야 하는가" }
}
}{
"model": "jev-latest",
"answers": {
"intent": { "choice": "refund", "probabilities": { "refund": 0.94, "exchange": 0.04, "inquiry": 0.02 }, "confidence": 0.94 },
"urgent": { "noul": 0.81 }
},
"usage": { … }
}choice의 criteria는 {선택지: 설명} 2~255개, score의 criteria는 낮은 것부터 단계 배열 2~10개입니다. noul의 답은 '예'일 확률입니다.
이미지 · 음성
OpenAI SDK의 이미지 · 음성 함수를 그대로 쓸 수 있습니다. 스트림은 없습니다.
| 경로 | 요청 | 응답 |
|---|---|---|
/images/generations | {model, prompt, n? (1~10), size?, …} | {created, data: [{b64_json | url}]} |
/audio/speech | {model, input (4,096자까지), voice?, response_format?} | 음성 파일 |
/audio/transcriptions | multipart: file · model · 그 밖의 필드 | {text, …} 또는 text · srt · vtt |
img = client.images.generate(model="gpt-image-1", prompt="파란 행성 일러스트", size="1024x1024")
speech = client.audio.speech.create(model="gpt-4o-mini-tts", voice="alloy", input="안녕하세요")
speech.write_to_file("hello.mp3")
with open("meeting.m4a", "rb") as f:
text = client.audio.transcriptions.create(model="gpt-4o-transcribe", file=f).text헤더
요청 헤더 (선택)
| 헤더 | 값 | 설명 |
|---|---|---|
x-llm-cache | skip | refresh | 캐시를 켠 라우트에서 캐시를 건너뛰거나 새로 채웁니다. |
x-llm-fallback | off | 라우트의 다른 모델로 다시 시도하지 않습니다. |
x-llm-timeout | 예: 30s | 이 요청의 전체 기한. 라우트에 정한 값보다 짧게만 줄일 수 있습니다. |
traceparent | W3C Trace Context | 호출하는 쪽의 추적에 이어 붙입니다. |
응답 헤더
| 헤더 | 값 | 설명 |
|---|---|---|
x-request-id | 문자열 | 문의할 때 알려 주십시오. Gateway의 Log에서 찾을 수 있습니다. |
x-llm-route · x-llm-model · x-llm-provider | 문자열 | 부른 라우트와 실제로 답한 모델 · 프로바이더 |
x-llm-attempts · x-llm-fallback | 숫자 · 불리언 | 시도 횟수, 다른 모델로 넘어갔는지 |
x-llm-cost-usd | 숫자 | 이 요청의 비용 (스트림이 아닐 때) |
x-ratelimit-* | OpenAI와 같은 이름 | 남은 요청 · 토큰 한도와 초기화 시각 |
오류
OpenAI 형식 {"error": {"message", "type", "param", "code"}}으로 돌려주므로 OpenAI SDK의 예외로 그대로 받습니다.
| code | HTTP | 언제 |
|---|---|---|
invalid_request · unsupported_parameter · ambiguous_model · context_length_exceeded · model_kind_mismatch | 400 | 요청 오류, 다른 종류의 경로로 부른 모델, 별칭이 여럿인 모델 ID |
invalid_api_key | 401 | 키 없음 · 틀림 · 만료 · 폐기 |
scope_not_allowed · route_not_allowed | 403 | 키의 범위에 Gateway가 없음, 키에 허용하지 않은 라우트 |
model_not_found | 404 | 없거나 꺼진 모델 · 라우트 |
rate_limit_exceeded · insufficient_quota | 429 | 요청 · 토큰 한도, 사용 한도 (retry-after 헤더) |
upstream_error | 502 | 모든 대상이 실패 |
access_unavailable · no_available_target · gateway_draining | 503 | 키 확인 불가, 쓸 수 있는 대상 없음, 재시작 중 (잠시 후 다시) |
upstream_timeout | 504 | 전체 기한 초과 |