# 调用动态 API 服务

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## 调用前准备

1. 准备具有目标服务运行权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。
2. 调用算子 API 服务时，先[查询算子 API 服务配置](get-operator-api-service.md#成功响应)，确认 `data.service.status` 为 `ready`，并记录 `service_name` 与 `input_schema`；调用动态服务工作流时，先[查询工作流列表](../workflows/list-workflows.md)（传入 `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` 解析目标工作区。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

### JSON 请求

```bash
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`，不要手动覆盖请求头。

```bash
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"
```

:::::
:::::{tab-item} 参数说明

### 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `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>` 数组。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "case_id": "case-001",
    "status": "COMPLETED",
    "result": {
      "rows": [
        {
          "now": "2026-08-28 10:00:00"
        }
      ]
    }
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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`。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "api_service_disabled",
  "msg": "Conflict"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码。 |
| `msg` | string | 可读错误信息。 |

:::::
::::::
:::::::

### 常见 HTTP 错误

```{list-table}
:header-rows: 1

* - 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 服务](enable-operator-api-service.md)或恢复对应动态服务工作流后再调用。
* - 429
  - `ErrDynamicServiceConcurrencyLimit`、`ErrDynamicServiceRateLimit`
  - 超过当前服务配置的最大并发数或每分钟调用速率上限。
  - 降低并发与调用频率，稍后重试。
* - 500
  - `ErrServer`
  - 服务端内部处理失败或等待运行超时。等待超时不代表底层运行未启动。
  - 先核对目标资源和运行记录，避免盲目重复提交非幂等请求。
* - 503
  - `ErrServiceUnavailable`
  - 运行时、授权或存储依赖暂不可用。
  - 恢复依赖后核对运行状态再重试。
```
