# 调用工作区对话模型

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

使用工作区可用模型和路由生成回答，支持普通JSON响应及SSE流式响应。

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/llm/chat/completions
```

## 调用前准备

`MOI_ENDPOINT` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

准备目标环境的个人访问令牌、工作区ID和实际可调用的模型名称。先确认对应模型/端点已配置且在线；模型列表或路由配置读取成功不代表实际推理可用。MOI_ENDPOINT须包含该环境实际API前缀，生产文档前缀为/v5，内部直连不应替代已验证网关。调用可能按环境配置产生用量记录和费用，不向真实模型发送审计测试请求。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --request POST "$MOI_ENDPOINT/workspaces/$WORKSPACE_ID/llm/chat/completions" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-raw '{"model":"chat-example","messages":[{"role":"user","content":"你好"}],"max_tokens":128,"stream":false}'
```

流式请求使用stream=true，并保持连接逐条读取：

```bash
curl --no-buffer --request POST "$MOI_ENDPOINT/workspaces/$WORKSPACE_ID/llm/chat/completions" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-raw '{"model":"chat-example","messages":[{"role":"user","content":"你好"}],"max_tokens":128,"stream":true}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| workspace_id | 路径 | string | 是 | 同环境工作区ID。 |
| X-API-Key | 请求头 | string | 是 | 当前环境个人访问令牌。 |
| X-Workspace-ID | 请求头 | string | 依网关 | 示例显式携带同一工作区；处理器以路径工作区为准，实际认证/运行身份边界仍须验证。 |
| service_slot | 查询 | string | 否 | 已配置服务槽名称，影响选路与计费归属；不是授权凭证或可任意填写的用途标签。 |
| X-LLM-Timeout | 请求头 | integer | 否 | 正整数秒数；无效/非正值回退后端超时。流式场景只限定等待响应开始的时间，不是整个流的总时长。 |

完整请求字段及提供商适配限制见[请求字段](request-fields.md)。context_budget只能用于非流式请求。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "id": "completion-example",
  "object": "chat.completion",
  "model": "chat-example",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 2,
    "total_tokens": 10
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 提供商返回的结果标识。 |
| object | string | 提供商兼容的对象类型。 |
| model | string | 返回的模型标识。 |
| choices | object（对象数组） | 回答候选，嵌套message、结束原因及工具结果依提供商；见[完整返回字段](responses-and-streams.md)。 |
| usage | object | 提供商上报的用量，可能缺失。 |
| moi_context_budget | object | 仅启用预算时可能追加的检查结果。 |

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 1,
  "message": "No available LLM backend or endpoint"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | integer 或 string | 接口错误为数字，认证/运行身份边界可能使用字符串。示例HTTP为503，但code为1。 |
| message | string | 接口失败说明，不按成功对象解析。 |
| details | object | 可选；上游诊断或计费拒绝时有不同字段，见[错误规则](responses-and-streams.md#错误与结束条件)。 |

:::::
::::::
:::::::
