Chat Completions

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

POST/v1/chat/completions

AI SDK·Messages·Responses·Images 연결은 퀵스타트 방법 탭을 보세요.

chat.ts

OpenAI Chat Completions API

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "plm_xxxxxxxxxxxxxxxx",
  baseURL: "https://apirouter.pleum.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4.1",
  messages: [{ role: "user", content: "Why is the sky blue?" }],
});

console.log(response.choices[0].message.content);

OpenAI Chat Completions API

from openai import OpenAI

client = OpenAI(
    api_key="plm_xxxxxxxxxxxxxxxx",
    base_url="https://apirouter.pleum.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(response.choices[0].message.content)

OpenAI Chat Completions API

curl https://apirouter.pleum.ai/v1/chat/completions \
  -H "Authorization: Bearer plm_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}]
  }'

요청 본문#

파라미터	타입	필수	설명
model	string	필수	모델 ID. `GET /v1/models`에서 전체 목록 확인. `model@provider` 형식(예: `llama-3.3-70b@groq`)으로 특정 프로바이더에 고정할 수도 있습니다.
messages	array	필수	`{role, content}` 배열. role은 system \| user \| assistant.
temperature	number	선택	0.0 ~ 2.0. 기본값 0.7.
max_tokens	integer	선택	1 ~ 128,000. 기본값 4096. 크레딧 사전 홀드 금액 산정에 사용되므로 필요한 만큼만 지정하는 것을 권장.
stream	boolean	선택	true면 SSE 스트리밍 응답. 기본값 false.
top_p	number	선택	0.0 ~ 1.0. 누클리어스 샘플링.
stop	string \| string[]	선택	생성을 중단할 시퀀스.
tools	array	선택	함수 호출 도구 정의(OpenAI 형식). 툴 콜링 참고.
tool_choice	string \| object	선택	`"auto"` · `"none"` 또는 특정 도구 강제 객체.
response_format	object	선택	`{"type": "json_object"}` 등. 구조화 출력 참고.
seed	integer	선택	결정적 샘플링 시드. 지원 여부는 모델에 따라 다릅니다.
frequency_penalty	number	선택	-2.0 ~ 2.0.
presence_penalty	number	선택	-2.0 ~ 2.0.
parallel_tool_calls	boolean	선택	병렬 도구 호출 허용 여부.
logit_bias	object	선택	토큰 ID → 바이어스 값 맵.
reasoning_effort	string	선택	`minimal` \| `none` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`. 프로바이더별 형식으로 자동 번역됩니다. 추론 모델 참고.
thinking	boolean	선택	`reasoning_effort`의 편의 별칭 — `true`→medium, `false`→none. 둘 다 보내면 `reasoning_effort`가 우선합니다.
service_tier	string	선택	`auto` \| `default` \| `flex` \| `background` \| `priority`. OpenAI 계열에만 전달(지연/비용 트레이드오프).
reasoning_mode	string	선택	`standard` \| `pro`. GPT-5.6 Sol/Terra/Luna의 품질 우선(pro) 모드.
plugins	array	선택	`[{"id": "web", ...}]` 웹 검색 플러그인. 웹 검색 참고.
provider	object	선택	`{order, only, ignore, sort, max_price}` 프로바이더 라우팅 설정. 레이턴시 라우팅 참고.
trace_id	string	선택	최대 128자. weighted 라우팅 정책의 sticky 시드 — 같은 `trace_id`는 항상 같은 모델로 라우팅됩니다.

표준 샘플링 · 도구 파라미터(top_p ~ reasoning_effort)는 검증 없이 라우팅된 프로바이더로 그대로 전달(패스스루)되며, 모델이 지원하지 않는 파라미터는 프로바이더가 무시하거나 에러를 반환할 수 있습니다. n(다중 choice)은 지원하지 않습니다 — 항상 단일 응답만 반환됩니다.

request body

{
  "model": "gpt-4.1",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7,
  "max_tokens": 4096,
  "stream": false
}

응답#

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

200 OK

{
  "id": "chatcmpl-gpt-4.1-841ms",
  "object": "chat.completion",
  "model": "gpt-4.1",
  "provider": "openai",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello! How can I help you?"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36
  },
  "cost": {
    "usd": 0.000144,
    "krw": 1,
    "fx_rate": 1525.0,
    "markup_rate": 0.0
  }
}

스트리밍#

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

SSE stream

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello! "}}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"How can I help you?"}}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":8,"total_tokens":20},"cost":{"usd":0.000144,"krw":1,"fx_rate":1525.0,"markup_rate":0.0}}

data: [DONE]

프롬프트 캐싱#

PleumRouter는 프롬프트 캐싱을 지원합니다. OpenAI · Google Gemini · DeepSeek는 별도 설정 없이 자동 캐싱됩니다 — 반복되는 입력 접두사(긴 시스템 프롬프트, 참고 문서 등)가 프로바이더 측에서 자동으로 캐싱되고, 캐시 적중분은 정가보다 낮은 할인 단가로 과금되어 비용이 절감됩니다.

Anthropic(Claude)은 명시적 캐싱을 사용합니다. content 파트에 cache_control: {"type": "ephemeral"}를 붙여 캐시 분기점을 지정하세요. 그 위치까지의 접두사가 캐싱됩니다.

request body (explicit caching)

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<large reusable context: docs, schema, instructions...>",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    },
    {"role": "user", "content": "Answer based on the context above."}
  ]
}

캐시가 적중하면 응답 usage에 prompt_tokens_details.cached_tokens(적중 토큰)가 추가됩니다. Anthropic은 캐시 기록 토큰을 cache_creation_input_tokens로 함께 반환합니다. 그 외 프로바이더는 캐시 토큰 수가 노출되며 할인은 적용되지 않습니다.

usage (cache hit)

"usage": {
  "prompt_tokens": 10240,
  "completion_tokens": 120,
  "total_tokens": 10360,
  "prompt_tokens_details": {"cached_tokens": 10000},
  "cache_creation_input_tokens": 0
}

과금 방식#

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

프로바이더 일시 장애 시 자동 재시도(2회)가 이루어집니다. 그래도 실패하면 502가 반환되고 크레딧은 차감되지 않습니다.