Chat Completions

채팅 완성을 생성합니다. OpenAI Chat Completions API와 호환됩니다.

POST/v1/chat/completions

요청 본문

파라미터	타입	필수	설명
model	string	필수	모델 ID. `GET /v1/models`에서 전체 목록 확인.
messages	array	필수	`{role, content}` 배열. role은 system \| user \| assistant.
temperature	number	선택	0.0 ~ 2.0. 기본값 0.7.
max_tokens	integer	선택	1 ~ 128,000. 기본값 4096. 크레딧 사전 홀드 금액 산정에 사용되므로 필요한 만큼만 지정하는 것을 권장.
data_residency	string	선택	`strict` \| `korea_endpoint` \| `global`. 미지정 시 API 키 설정값.
stream	boolean	선택	true면 SSE 스트리밍 응답. 기본값 false.

request body

{
  "model": "gpt-4.1",
  "messages": [
    {"role": "system", "content": "당신은 친절한 비서입니다."},
    {"role": "user", "content": "안녕하세요"}
  ],
  "temperature": 0.7,
  "max_tokens": 4096,
  "data_residency": "korea_endpoint",
  "stream": false
}

응답

OpenAI 형식의 choices / usage에 더해, PleumRouter는 cost(원화 비용·환율·마크업)와 provider / data_tier(실제 라우팅 결과)를 추가로 반환합니다.

200 OK

{
  "id": "chatcmpl-gpt-4.1-841ms",
  "object": "chat.completion",
  "model": "gpt-4.1",
  "provider": "azure_openai",
  "data_tier": "tier2",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "안녕하세요! 무엇을 도와드릴까요?"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36
  },
  "cost": {
    "usd": 0.000144,
    "krw": 1,
    "fx_rate": 1390.5,
    "markup_rate": 0.005
  }
}

스트리밍

stream: true로 요청하면 text/event-stream으로 텍스트 조각이 전송되고, 마지막 이벤트에 비용 정보가 포함됩니다.

SSE stream

data: {"delta": "안녕하세요! "}

data: {"delta": "무엇을 도와드릴까요?"}

data: {"done": true, "cost": {"usd": 0.000144, "krw": 1}}

과금 방식

요청 시점에 예상 비용만큼 크레딧이 사전 홀드(freeze)되고, 호출이 끝나면 실제 토큰 사용량으로 정산됩니다. 호출이 실패하면 홀드는 전액 해제되며, 성공한 호출은 최소 ₩1이 차감됩니다.

Tier 1(국내 처리) 모델이 일시 장애일 경우, 동일 티어 내 대체 모델로 자동 폴백됩니다. 폴백 시에도 실제 사용한 모델 기준으로만 과금됩니다.