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。nucleus サンプリング。
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 が返され、クレジットは差し引かれません。