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

# Router 管理面聊天与路由测试接口

> 通过咏唱引擎 ROUTER 发送一次测试聊天补全并预览路由决策。支持 dry-run 模式。

管理面聊天接口让你测试聊天请求将如何经由咏唱引擎 ROUTER 路由。它接受与 `/v1/chat/completions` 相同的请求体，并新增一个可选的 `dry_run` 标志。可用它在不向下游发出请求的情况下校验路由规则、检查 provider 选择并调试配方。

此接口会返回路由决策；在非 dry-run 模式下，还会返回下游 provider 的响应。

## 接口

```http theme={null}
POST /v1/router/chat
```

## 认证

使用会话 Cookie 认证，或携带 `Authorization: Bearer <api-key>`。

## 请求体

<ParamField body="model" type="string" required>
  目标模型或虚拟模型名称。
</ParamField>

<ParamField body="messages" type="array" required>
  标准 chat-completion 形态的对消息。
</ParamField>

<ParamField body="dry_run" type="boolean">
  为 `true` 时，router 计算路由决策但不向 provider 发送请求。
</ParamField>

<ParamField body="temperature" type="number">
  采样温度。
</ParamField>

<ParamField body="max_tokens" type="integer">
  生成的最大令牌数。
</ParamField>

## 响应

<ResponseField name="decision" type="object">
  router 产生的路由决策。

  <Expandable title="属性">
    <ResponseField name="provider" type="string">
      选定的 provider 名称。
    </ResponseField>

    <ResponseField name="model" type="string">
      发送给 provider 的解析后模型名称。
    </ResponseField>

    <ResponseField name="recipe" type="string">
      匹配此请求的配方。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="response" type="object">
  下游 provider 响应。`dry_run` 为 `true` 时省略。

  <Expandable title="属性">
    <ResponseField name="id" type="string">
      补全标识符。
    </ResponseField>

    <ResponseField name="choices" type="array">
      生成的候选。
    </ResponseField>

    <ResponseField name="usage" type="object">
      令牌用量摘要。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://router.example.com/v1/router/chat" \
    -H "Authorization: Bearer <api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "default",
      "messages": [{"role": "user", "content": "Hello router"}],
      "dry_run": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "decision": {
      "provider": "openai",
      "model": "gpt-4o",
      "recipe": "semantic-router"
    },
    "response": {
      "id": "chatcmpl-example",
      "choices": [
        {
          "index": 0,
          "message": {"role": "assistant", "content": "Hello! How can I help?"},
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 8,
        "total_tokens": 18
      }
    }
  }
  ```
</ResponseExample>