Invoke a workspace chat model¶
Generate responses through workspace models and routing, with ordinary JSON or SSE streaming responses.
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/llm/chat/completions
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.
Request parameters¶
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:
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}'
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 for complete fields and provider adapter limitations. context_budget is available only for nonstreaming requests.
Successful response¶
{
"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
}
}
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. |
usage |
object |
Provider-reported usage; may be absent. |
moi_context_budget |
object |
Check result that may be appended only when budgeting is enabled. |
Error responses¶
{
"code": 1,
"message": "No available LLM backend or endpoint"
}
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. |