API 레퍼런스 (OpenAI 호환)

게이트웨이는 OpenAI 호환 API를 제공합니다. 기존 OpenAI SDK의 base_url만 바꾸면 그대로 동작합니다.

Base URL: https://<gateway-host>/v1
인증: Authorization: Bearer <API_KEY> (포털에서 발급)
콘텐츠 타입: application/json

from openai import OpenAI
client = OpenAI(base_url="https://<gateway-host>/v1", api_key="YOUR_API_KEY")

인증

모든 추론 엔드포인트는 API 키가 필요합니다. 키는 포털 → 프로젝트 → API Key에서 발급합니다.

curl https://<gateway-host>/v1/models -H "Authorization: Bearer $API_KEY"

키 없이 호출하면 401/403이 반환됩니다. 키는 환경변수로 관리하고 코드·커밋에 넣지 마세요.

모델 목록 — `GET /v1/models`

curl https://<gateway-host>/v1/models -H "Authorization: Bearer $API_KEY"

{ "object": "list", "data": [ { "id": "qwen2.5-72b", "object": "model" }, { "id": "exaone-3.5-32b" }, { "id": "bge-m3" } ] }

모델은 크게 채팅(예: qwen2.5-72b, exaone-3.5-32b(한국어), qwen2.5-coder-32b(코드)), 임베딩(bge-m3), 리랭커(bge-reranker-v2-m3), 비전(qwen2.5-vl-*)으로 나뉩니다. 실제 가용 목록은 위 호출로 확인하세요.

채팅 — `POST /v1/chat/completions`

resp = client.chat.completions.create(
    model="qwen2.5-72b",
    messages=[{"role": "system", "content": "간결한 한국어 도우미"},
              {"role": "user", "content": "제주도 2박3일 코스 추천"}],
    max_tokens=512, temperature=0.3,
)
print(resp.choices[0].message.content)

curl https://<gateway-host>/v1/chat/completions -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -d '{
    "model": "qwen2.5-72b",
    "messages": [{"role":"user","content":"안녕"}],
    "max_tokens": 128
  }'

스트리밍 (`stream: true`) — SSE 토큰 단위

stream = client.chat.completions.create(
    model="qwen2.5-72b",
    messages=[{"role": "user", "content": "긴 설명을 써줘"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://<gateway-host>/v1", apiKey: process.env.API_KEY });
const stream = await client.chat.completions.create({
  model: "qwen2.5-72b",
  messages: [{ role: "user", content: "안녕" }],
  stream: true,
});
for await (const part of stream) process.stdout.write(part.choices[0]?.delta?.content ?? "");

주요 파라미터

파라미터	설명
`model`	모델 id (`/v1/models`)
`messages`	`[{role: system\\|user\\|assistant, content}]`
`max_tokens`	최대 생성 토큰
`temperature`	0~2, 낮을수록 결정적
`top_p`	뉴클리어스 샘플링
`stream`	`true` 면 SSE 스트리밍
`tools` / `tool_choice`	함수 호출(지원 모델)

도구 호출 (function calling)

지원 모델(예: qwen2.5-72b)은 OpenAI 형식 tools를 그대로 받습니다.

resp = client.chat.completions.create(
    model="qwen2.5-72b",
    messages=[{"role": "user", "content": "서울 날씨 알려줘"}],
    tools=[{"type": "function", "function": {"name": "get_weather",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}],
    tool_choice="auto",
)

텍스트 완성 — `POST /v1/completions`

curl https://<gateway-host>/v1/completions -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen2.5-72b","prompt":"한국의 수도는","max_tokens":16}'

임베딩 — `POST /v1/embeddings`

emb = client.embeddings.create(model="bge-m3", input=["문장1", "문장2"])
vec = emb.data[0].embedding

RAG 파이프라인의 벡터화에 사용합니다(bge-m3).

리랭킹 — `POST /v1/rerank`

질의와 문서들의 관련도를 재정렬합니다(bge-reranker-v2-m3).

curl https://<gateway-host>/v1/rerank -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -d '{
    "model": "bge-reranker-v2-m3",
    "query": "환불 규정",
    "documents": ["환불은 7일 이내", "배송은 2-3일"]
  }'

응답은 각 문서의 index와 score를 관련도 순으로 반환합니다. 점수 계산만 필요하면 POST /v1/score.

기능 템플릿 — `GET /api/templates` · `POST /v1/templates/{id}/run`

원시 모델 API 위에, 검증된 기능 템플릿(RAG·OCR·챗·어시스턴트)을 한 번의 호출로 실행할 수 있습니다.

curl https://<gateway-host>/api/templates -H "Authorization: Bearer $API_KEY"      # 목록
curl https://<gateway-host>/v1/templates/rag-document-qa/run \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{
    "inputs": {"question": "환불 며칠 이내?", "documents": ["환불은 7일 이내"]}
  }'

템플릿 개념·카탈로그: templates.md · CLI로 앱 만들기: quickstart.md

안전 · 한도

항목	설명
안전 모드	요청 헤더 `X-Safety-Mode: off\\|observe\\|enforce` 로 입력·출력 가드레일 제어
Rate limit	키별 분당 요청(RPM)·일일 토큰(TPM) 한도. 초과 시 `429`
사용량	프로젝트·모델·기간별 요청·토큰이 집계되어 콘솔에서 조회

오류 코드

코드	의미
`401` / `403`	인증 실패 (키 없음·무효·권한 없음)
`404`	미등록 모델·엔드포인트
`429`	Rate limit 초과
`503`	백엔드(모델) 일시 불가 — 재시도

{ "error": { "message": "invalid api key", "type": "auth_error", "code": 401 } }

다음: 빠른 시작 · 템플릿 카탈로그 · CLI

API 레퍼런스 (OpenAI 호환)

인증

모델 목록 — GET /v1/models

채팅 — POST /v1/chat/completions

스트리밍 (stream: true) — SSE 토큰 단위