> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# スマートルーティングAPI

> スマートルーティングのキー、モデルティア、推論、およびルーティング統計を作成・設定します。

## 概要

スマートルーティングは、リクエストの複雑さに応じて、設定済みのモデルプールからモデルを自動的に選択します。System APIでは、ルートは`smart_routing: true`を持つAPIキーレコードとして表されます。標準キーと同じ`/api/token/`の作成、更新、ステータス、表示、削除の各エンドポイントを使用します。

| コンソールのラベル | APIフィールド | 目的 |
| - | - | - |
| Simple | `simple` | 高速でコスト効率の高いリクエスト |
| Complex | `complex` | より高度なタスク |
| Ultra | `super` | 最高性能の基本ティア |

保存されるティアオブジェクトには`reasoning`も含まれます。現在のコンソールでは、互換性のために`simple`と同じモデルに設定されます。

<Warning>
  `smart_route_tiers`はJSONエンコードされた文字列です。ネストされたJSONオブジェクトとして送信しないでください。
</Warning>

## 現在のプリセットを取得

プリセットのモデルIDはデプロイ設定です。スクリーンショットからモデル名をコピーするのではなく、`/api/status`から取得してください。

```bash theme={null}
status_response=$(curl -fsS "$BASE_URL/api/status")

jq -e '
  .success == true
  and .data.smart_routing_enabled == true
  and (.data.smart_routing_model_aliases | index("auto") != null)
' <<< "$status_response" >/dev/null

presets=$(jq -er '.data.smart_routing_presets | fromjson' \
  <<< "$status_response")

jq '.' <<< "$presets"
```

最初のチェックでは、スマートルーティングが無効な場合、または`auto`がルーティング用エイリアスとして公開されていない場合に、ワークフローを停止します。

プリセットを選択し、互換性フィールドを正規化します。

```bash theme={null}
tiers=$(jq -ce '
  .[0].pools
  | .reasoning = .simple
  | {simple, reasoning, complex, super}
  | select(all(.[]; type == "string" and length > 0))
' <<< "$presets")
```

有効な3つのティアすべてに、選択したグループで利用可能なモデルIDが含まれていることを確認してください。`.data.smart_routing_excluded_models`と大文字・小文字を区別せずに照合してください。除外されたモデルは選択できません。

## スマートルーティングキーを作成する

```bash theme={null}
name="smart-route-$(date +%s)-$RANDOM"

payload=$(jq -n \
  --arg name "$name" \
  --arg tiers "$tiers" '{
    name: $name,
    expired_time: -1,
    remain_quota: 0,
    unlimited_quota: true,
    model_limits_enabled: false,
    model_limits: "",
    allow_ips: "",
    group: "default",
    cross_group_retry: false,
    smart_routing: true,
    smart_route_tiers: $tiers
  }')

curl -fsS -X POST "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$payload" | jq
```

作成時にはIDが返されません。`exclude_smart_routing=false`でルートを見つけてください。

```bash theme={null}
route=$(curl -fsS --get "$BASE_URL/api/token/search" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "keyword=$name" \
  --data-urlencode "exclude_smart_routing=false" \
  --data-urlencode "p=1" \
  --data-urlencode "size=10")

route_id=$(jq -er --arg name "$name" '
  [.data.items[]
    | select(.name == $name and .smart_routing == true)]
  | if length == 1 then .[0].id
    else error("expected exactly one matching Smart Routing key")
    end
' <<< "$route")
```

## モデルプールを更新

現在のレコードを読み取り、デコードした階層設定を変更します。更新ボディでは、その他すべての変更可能なフィールドを保持する必要があります。

```bash theme={null}
current=$(curl -fsS "$BASE_URL/api/token/$route_id" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

new_tiers=$(jq -cer '
  .data.smart_route_tiers
  | fromjson
  | .complex = "YOUR_COMPLEX_MODEL"
  | .reasoning = .simple
' <<< "$current")

update_payload=$(jq --arg tiers "$new_tiers" '.data | {
  id,
  name,
  expired_time,
  remain_quota,
  unlimited_quota,
  model_limits_enabled,
  model_limits,
  allow_ips,
  group,
  cross_group_retry,
  smart_routing,
  smart_route_tiers
} | .smart_routing = true | .smart_route_tiers = $tiers' <<< "$current")

curl -fsS -X PUT "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$update_payload" | jq
```

変更は、ルートキーを使用して行われる以降のリクエストに適用されます。

## ルートキーを表示して使用する

```bash theme={null}
stored_key=$(curl -fsS -X POST "$BASE_URL/api/token/$route_id/key" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  | jq -er '.data.key')

route_api_key="sk-${stored_key#sk-}"
```

推論エンドポイントを使用し、`model`を`auto`に設定します。

```bash theme={null}
curl -fsS https://api.mixroute.ai/v1/chat/completions \
  -H "Authorization: Bearer $route_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role":"user","content":"Summarize the tradeoffs of this architecture."}
    ]
  }' | jq
```

システムアクセストークンを推論エンドポイントに送信しないでください。

## ルーティング統計

すべてのルートキーの集計統計を読み取ります。

```bash theme={null}
curl -fsS "$BASE_URL/api/token/smart_route/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq
```

キーとUnix秒で指定した時間範囲で絞り込みます。

```bash theme={null}
curl -fsS --get "$BASE_URL/api/token/smart_route/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "token_id=$route_id" \
  --data-urlencode "start=START_UNIX_SECONDS" \
  --data-urlencode "end=END_UNIX_SECONDS" | jq
```

レスポンスには、`requests`、`actual_quota`、`saved_quota`、`baseline`と`actual`を持つ`daily`の各エントリ、`tier_dist`、`trial_start_ts`が含まれます。

`/api/status`から、現在のサービス手数料と試用の設定を読み取ります。

```bash theme={null}
curl -fsS "$BASE_URL/api/status" | jq '{
  trial_days: .data.smart_routing_free_trial_days,
  service_fee_percent: .data.smart_routing_service_fee_percent
}'
```

## 運用上の制約

* リクエストには、OpenAI互換の`/v1/chat/completions`形式を使用します。
* Claudeを対象とする場合はOpenAI互換モードでアクセスするため、Claudeのネイティブ専用機能は利用できない場合があります。
* 対象モデルを切り替えると、プロバイダー側のプロンプトキャッシュを再利用できなくなる場合があります。
* 本番環境の認証情報をローテーションする際は、ステータスのみを更新するエンドポイントでルートを無効にしてから削除してください。

コンソールでの手順と連携先のリンクについては、[スマートルーティング](/ja/api-reference/smart-routing)を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.