调用动态 API 服务¶
按服务名称调用已发布且处于就绪状态的算子 API 服务或动态服务工作流,并等待本次运行返回结果。HTTP 状态码为 200 仅表示接口请求已返回,读取业务输出前需先核对 data.status 与 data.error。
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/dynamic-services/invoke
调用前准备¶
调用算子 API 服务时,先查询算子 API 服务配置,确认
data.service.status为ready,并记录service_name与input_schema;调用动态服务工作流时,先查询工作流列表(传入include_dynamic_service=true),确认目标工作流状态为ready且服务名称在当前工作区唯一。
请求参数¶
将 $AI_STUDIO_API_KEY、$WORKSPACE_ID、$SERVICE_NAME 和示例中的输入字段替换为实际值。调用等价请求头作用域入口时,可使用 POST https://api.moi.matrixorigin.cn/v5/workflow/v2/dynamic-services/invoke,此时不传路径参数 workspace_id,服务端直接从 X-Workspace-ID 解析目标工作区。
JSON 请求
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/dynamic-services/invoke" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"service_name": "'"$SERVICE_NAME"'",
"payload": {
"sql": "SELECT now()"
}
}'
Multipart 文件请求
使用 -F 上传文件时,由 cURL 自动生成带 boundary 的 Content-Type,不要手动覆盖请求头。
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/dynamic-services/invoke" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-F "service_name=$SERVICE_NAME" \
-F 'payload={"language":"zh"}' \
-F "file=@sample.pdf;type=application/pdf"
路径参数
参数 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
是 |
目标工作区 ID。同时发送 |
请求体参数
参数 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
是 |
目标动态服务或算子 API 服务的名称,首尾空白会被去除,在当前工作区的动态服务中必须唯一。 |
|
object |
是 |
传入服务的业务输入对象,不能为空或 |
|
string |
否 |
可选版本标识字符串。实际运行的工作流版本由 |
|
integer |
否 |
要调用的工作流版本号(正整数)。省略或小于等于 |
|
object |
否 |
单次调用的运行追踪选项。在 |
|
boolean |
否 |
是否为本次运行开启追踪。 |
|
integer |
否 |
追踪粒度代码: |
|
boolean |
否 |
是否在追踪属性中包含输入输出载荷。 |
|
integer |
否 |
追踪属性 JSON 的最大字节数; |
|
binary |
否 |
仅 |
multipart/form-data 文件注入规则:
service_name、payload、version、version_number、trace为保留表单字段,不能作为文件部件上传。每个上传文件会先写入工作区文件目录,并转换为
{"file_id": "...", "original_name": "..."}引用对象。文件字段名为
sources,或字段名为file且payload中未显式包含file键时,文件引用会写入或追加到payload.sources数组;使用其他字段名上传单个文件时写入payload.<file_field>对象,上传多个同名文件时写入payload.<file_field>数组。
成功响应¶
{
"code": "OK",
"msg": "OK",
"data": {
"case_id": "case-001",
"status": "COMPLETED",
"result": {
"rows": [
{
"now": "2026-08-28 10:00:00"
}
]
}
}
}
字段 |
类型 |
说明 |
|---|---|---|
|
string |
接口请求处理成功时为 |
|
string |
请求处理的说明文本。 |
|
object |
本次动态服务调用返回的结果。 |
|
string |
本次运行实例 ID;为空时省略。 |
|
string |
运行终态。非流式( |
|
any |
服务输出的 JSON 值(流式模式下为最后一个非空事件的载荷);无输出时省略。 |
|
string |
服务运行错误信息;无错误时省略。底层执行失败时 HTTP 状态码仍可能为 |
|
array of object |
流式( |
|
string |
产生该事件的运行实例 ID;为空时省略。 |
|
any |
单个流式事件携带的 JSON 数据;为空时省略。 |
|
boolean |
是否为流式输出的结束事件帧。 |
|
string |
流式事件携带的错误信息;无错误时省略。 |
仅当 data.status 表示已完成(COMPLETED 或 completed)且 data.error 为空时,才将 data.result 作为成功输出处理。若 service_name 命中工作区内的智能体自动化 API 触发任务,接口会返回 HTTP 202 及异步运行回执(data.run_id、data.status、data.result_url)。
错误响应¶
请求参数缺失、服务已停用、并发或速率超限,或未找到目标服务时返回非 200 HTTP 错误。服务已提交运行但内部执行失败时仍可能返回 HTTP 200,请同时检查 data.status 和 data.error。
{
"code": "api_service_disabled",
"msg": "Conflict"
}
字段 |
类型 |
说明 |
|---|---|---|
|
string |
错误代码。 |
|
string |
可读错误信息。 |
常见 HTTP 错误¶
HTTP 状态码 |
错误代码 |
常见原因 |
建议操作 |
|---|---|---|---|
400 |
|
|
核对请求体、上传文件限制、工作区 ID 和服务输入定义。 |
401 |
|
认证凭据缺失或无效。 |
检查 |
403 |
|
当前身份缺少目标算子 API 服务或动态服务工作流的运行权限。 |
使用具备运行权限的身份,或联系管理员授权。 |
404 |
|
当前工作区不存在该 |
核对服务名称唯一性、目标工作区和版本号。 |
409 |
|
目标算子 API 服务或动态服务工作流未处于 |
先启用算子 API 服务或恢复对应动态服务工作流后再调用。 |
429 |
|
超过当前服务配置的最大并发数或每分钟调用速率上限。 |
降低并发与调用频率,稍后重试。 |
500 |
|
服务端内部处理失败或等待运行超时。等待超时不代表底层运行未启动。 |
先核对目标资源和运行记录,避免盲目重复提交非幂等请求。 |
503 |
|
运行时、授权或存储依赖暂不可用。 |
恢复依赖后核对运行状态再重试。 |