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.

Last updated on