调用动态 API 服务

按服务名称调用已发布且处于就绪状态的算子 API 服务或动态服务工作流,并等待本次运行返回结果。HTTP 状态码为 200 仅表示接口请求已返回,读取业务输出前需先核对 data.status 与 data.error。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/dynamic-services/invoke

调用前准备

  1. 准备具有目标服务运行权限的个人访问令牌和目标工作区 ID。

  2. 调用算子 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"

路径参数

参数

类型

是否必填

说明

workspace_id

string

是

目标工作区 ID。同时发送 X-Workspace-ID 请求头时,两者必须一致;使用 /v5/workflow/v2/dynamic-services/invoke 入口时无需此路径参数。

请求体参数

参数

类型

是否必填

说明

service_name

string

是

目标动态服务或算子 API 服务的名称,首尾空白会被去除,在当前工作区的动态服务中必须唯一。

payload

object

是

传入服务的业务输入对象,不能为空或 null,字段需符合目标服务版本的 input_schema。在 multipart/form-data 请求中以 JSON 对象字符串传入,省略时默认按 {} 解析。

version

string

否

可选版本标识字符串。实际运行的工作流版本由 version_number 或服务最新已发布版本决定。

version_number

integer

否

要调用的工作流版本号(正整数)。省略或小于等于 0 时调用最新已发布版本;指定不存在的版本号时返回 404。在 multipart/form-data 请求中以十进制整数字符串传入。

trace

object

否

单次调用的运行追踪选项。在 multipart/form-data 请求中以 JSON 对象字符串传入。

trace.enabled

boolean

否

是否为本次运行开启追踪。

trace.level

integer

否

追踪粒度代码:0 未指定、1 工作流级、2 节点级、3 Worker 级、4 流式级。

trace.include_payloads

boolean

否

是否在追踪属性中包含输入输出载荷。

trace.max_attr_bytes

integer

否

追踪属性 JSON 的最大字节数;0 表示使用服务端默认值。

<file_field>

binary

否

仅 multipart/form-data 请求使用。非保留字段名的上传文件部件,单次请求最多上传 16 个文件,单个文件不超过 64 MiB。

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"
        }
      ]
    }
  }
}

字段

类型

说明

code

string

接口请求处理成功时为 OK,不单独代表服务运行成功。

msg

string

请求处理的说明文本。

data

object

本次动态服务调用返回的结果。

data.case_id

string

本次运行实例 ID;为空时省略。

data.status

string

运行终态。非流式(oneshot)模式返回大写状态词(如 COMPLETED、FAILED、CANCELLED),流式(stream)模式返回小写状态词(completed、failed)。

data.result

any

服务输出的 JSON 值(流式模式下为最后一个非空事件的载荷);无输出时省略。

data.error

string

服务运行错误信息;无错误时省略。底层执行失败时 HTTP 状态码仍可能为 200。

data.events

array of object

流式(stream)模式下按顺序收集的事件帧列表;非流式模式下省略。

data.events[].case_id

string

产生该事件的运行实例 ID;为空时省略。

data.events[].data

any

单个流式事件携带的 JSON 数据;为空时省略。

data.events[].done

boolean

是否为流式输出的结束事件帧。

data.events[].error

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"
}

字段

类型

说明

code

string

错误代码。

msg

string

可读错误信息。

常见 HTTP 错误

HTTP 状态码

错误代码

常见原因

建议操作

400

ErrParamInvalid、ErrWorkspaceRequired、ErrWorkflowComputeResourceNotFound

service_name 或 payload 缺失、路径 workspace_id 与 X-Workspace-ID 不一致、上传文件超过 16 个或单文件超过 64 MiB,或计算资源不可用。

核对请求体、上传文件限制、工作区 ID 和服务输入定义。

401

Unauthorized、ErrUnauthorized

认证凭据缺失或无效。

检查 X-API-Key 请求头中的访问凭据。

403

ErrForbidden

当前身份缺少目标算子 API 服务或动态服务工作流的运行权限。

使用具备运行权限的身份,或联系管理员授权。

404

ErrNotFound

当前工作区不存在该 service_name、存在同名动态服务冲突,或指定的 version_number 不存在。

核对服务名称唯一性、目标工作区和版本号。

409

api_service_disabled

目标算子 API 服务或动态服务工作流未处于 ready 状态(例如已停用或已暂停)。

先启用算子 API 服务或恢复对应动态服务工作流后再调用。

429

ErrDynamicServiceConcurrencyLimit、ErrDynamicServiceRateLimit

超过当前服务配置的最大并发数或每分钟调用速率上限。

降低并发与调用频率,稍后重试。

500

ErrServer

服务端内部处理失败或等待运行超时。等待超时不代表底层运行未启动。

先核对目标资源和运行记录,避免盲目重复提交非幂等请求。

503

ErrServiceUnavailable

运行时、授权或存储依赖暂不可用。

恢复依赖后核对运行状态再重试。

最后更新于