调用工作区对话模型¶
使用工作区可用模型和路由生成回答,支持普通JSON响应及SSE流式响应。
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,内部直连不应替代已验证网关。调用可能按环境配置产生用量记录和费用,不向真实模型发送审计测试请求。
请求参数¶
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,并保持连接逐条读取:
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}'
参数 |
位置 |
类型 |
必填 |
说明 |
|---|---|---|---|---|
workspace_id |
路径 |
string |
是 |
同环境工作区ID。 |
X-API-Key |
请求头 |
string |
是 |
当前环境个人访问令牌。 |
X-Workspace-ID |
请求头 |
string |
依网关 |
示例显式携带同一工作区;处理器以路径工作区为准,实际认证/运行身份边界仍须验证。 |
service_slot |
查询 |
string |
否 |
已配置服务槽名称,影响选路与计费归属;不是授权凭证或可任意填写的用途标签。 |
X-LLM-Timeout |
请求头 |
integer |
否 |
正整数秒数;无效/非正值回退后端超时。流式场景只限定等待响应开始的时间,不是整个流的总时长。 |
完整请求字段及提供商适配限制见请求字段。context_budget只能用于非流式请求。
成功响应¶
{
"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
}
}
字段 |
类型 |
说明 |
|---|---|---|
id |
string |
提供商返回的结果标识。 |
object |
string |
提供商兼容的对象类型。 |
model |
string |
返回的模型标识。 |
choices |
object(对象数组) |
回答候选,嵌套message、结束原因及工具结果依提供商;见完整返回字段。 |
usage |
object |
提供商上报的用量,可能缺失。 |
moi_context_budget |
object |
仅启用预算时可能追加的检查结果。 |
错误响应¶
{
"code": 1,
"message": "No available LLM backend or endpoint"
}
字段 |
类型 |
说明 |
|---|---|---|
code |
integer 或 string |
接口错误为数字,认证/运行身份边界可能使用字符串。示例HTTP为503,但code为1。 |
message |
string |
接口失败说明,不按成功对象解析。 |
details |
object |
可选;上游诊断或计费拒绝时有不同字段,见错误规则。 |