<span id="调用工作区对话模型"></span>

# Invoke a workspace chat model

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

Generate responses through workspace models and routing, with ordinary JSON or SSE streaming responses.

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

<span id="调用前准备"></span>

## Before you call this API

Set `MOI_ENDPOINT` to the product API prefix `https://api.moi.matrixorigin.cn/v5`; use the corresponding product API URL for a dedicated deployment.

Prepare a personal access token, workspace ID, and an actually invocable model name in the target environment. Confirm that the model/endpoints are configured and online. Successful model-list or routing-configuration reads do not establish inference availability. MOI_ENDPOINT must include the environment's actual API prefix; production documentation uses /v5. Internal direct access does not replace a verified gateway. Calls may generate usage records and charges under environment configuration. Do not send audit test requests to real models.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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}'
```

For streaming, set stream=true and keep the connection open to read each event:

```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} Parameters

| Parameter | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| workspace_id | Path | string | Yes | Workspace ID in the same environment. |
| X-API-Key | Headers | string | Yes | Personal access token in the current environment. |
| X-Workspace-ID | Headers | string | Gateway-dependent | The example explicitly includes the same workspace. The handler uses the path workspace; actual authentication/runtime identity boundaries still require verification. |
| service_slot | Queries | string | No | Configured service slot name, affecting routing and billing attribution. It is not an authorization credential or arbitrary purpose label. |
| X-LLM-Timeout | Headers | integer | No | Positive integer seconds. Invalid/nonpositive values fall back to the backend timeout. For streaming, this limits waiting for the response to start, not total stream duration. |

See [request fields](request-fields.md) for complete fields and provider adapter limitations. context_budget is available only for nonstreaming requests.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| id | string | Result identifier returned by the provider. |
| object | string | Provider-compatible object type. |
| model | string | Returned model identifier. |
| choices | object (array of objects) | Answer choices; nested message, finish reason, and tool results depend on the provider. See [complete response fields](responses-and-streams.md). |
| usage | object | Provider-reported usage; may be absent. |
| moi_context_budget | object | Check result that may be appended only when budgeting is enabled. |

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

<span id="错误响应"></span>

## Error responses

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| code | integer or string | API errors use numbers; authentication/runtime identity boundaries may use strings. The example HTTP status is 503 while code is 1. |
| message | string | API failure description; do not parse as a success object. |
| details | object | Optional. Upstream diagnostics and billing denials have different fields; see [error rules](responses-and-streams.md#errors-and-completion-conditions). |

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