Gateway API

Gateway는 Planet에 등록한 AI 모델을 하나의 주소로 호출하게 해 주는 중계입니다. OpenAI API와 같은 형식이라 OpenAI SDK의 기본 주소만 바꾸면 그대로 쓸 수 있습니다.

개요

항목값설명
기본 주소URLhttps://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에서 확인합니다.

빠른 시작

Python (openai)
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)
Node.js (openai)
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
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/completionsLLM 채팅 (스트림 포함)
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).

Python (스트림)
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_formatfloat | base64 (선택)base64는 float32 little-endian
Python
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
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/transcriptionsmultipart: file · model · 그 밖의 필드{text, …} 또는 text · srt · vtt
Python
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-cacheskip | refresh캐시를 켠 라우트에서 캐시를 건너뛰거나 새로 채웁니다.
x-llm-fallbackoff라우트의 다른 모델로 다시 시도하지 않습니다.
x-llm-timeout예: 30s이 요청의 전체 기한. 라우트에 정한 값보다 짧게만 줄일 수 있습니다.
traceparentW3C 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의 예외로 그대로 받습니다.

codeHTTP언제
invalid_request · unsupported_parameter · ambiguous_model · context_length_exceeded · model_kind_mismatch400요청 오류, 다른 종류의 경로로 부른 모델, 별칭이 여럿인 모델 ID
invalid_api_key401키 없음 · 틀림 · 만료 · 폐기
scope_not_allowed · route_not_allowed403키의 범위에 Gateway가 없음, 키에 허용하지 않은 라우트
model_not_found404없거나 꺼진 모델 · 라우트
rate_limit_exceeded · insufficient_quota429요청 · 토큰 한도, 사용 한도 (retry-after 헤더)
upstream_error502모든 대상이 실패
access_unavailable · no_available_target · gateway_draining503키 확인 불가, 쓸 수 있는 대상 없음, 재시작 중 (잠시 후 다시)
upstream_timeout504전체 기한 초과