# 调用工作区向量模型

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

使用工作区向量模型把文本或模型支持的输入转为向量；大批输入可能分多次上游调用。

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/embeddings
```

## 调用前准备

`MOI_ENDPOINT` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

准备目标环境的个人访问令牌、工作区ID和实际可调用的模型名称。先确认对应模型/端点已配置且在线；模型列表或路由配置读取成功不代表实际推理可用。MOI_ENDPOINT须包含该环境实际API前缀，生产文档前缀为/v5，内部直连不应替代已验证网关。调用可能按环境配置产生用量记录和费用，不向真实模型发送审计测试请求。

## 请求参数

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

```bash
curl --request POST "$MOI_ENDPOINT/workspaces/$WORKSPACE_ID/embeddings" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-raw '{"model":"embed-example","input":["示例文本"]}'
```

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

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| workspace_id | 路径 | string | 是 | 同环境工作区ID。 |
| X-API-Key | 请求头 | string | 是 | 当前环境个人访问令牌。 |
| X-Workspace-ID | 请求头 | string | 依网关 | 示例显式携带同一工作区；处理器以路径工作区为准，实际认证/运行身份边界仍须验证。 |
| service_slot | 查询 | string | 否 | 已配置服务槽名称，影响选路与计费归属；不是授权凭证或可任意填写的用途标签。 |

完整请求字段及提供商适配限制见[请求字段](request-fields.md)。请求体最多4MiB，input数组最多4096项；当前调用器只接受OPENAI类型后端，不能由管理接口能创建其他类型推断均可执行。

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

## 成功响应

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

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.1,
        0.2
      ],
      "index": 0
    }
  ],
  "model": "embed-example",
  "usage": {
    "prompt_tokens": 1,
    "total_tokens": 1
  }
}
```

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | string | 常规为list。 |
| data | object（对象数组） | 向量条目，不是产品封套；index/向量字段见[完整返回字段](responses-and-streams.md)。 |
| model | string | 提供商返回的模型标识。 |
| usage | object | 提供商用量，可能缺失；分批结果可能合并。 |

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

## 错误响应

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

```json
{
  "code": 1,
  "message": "No available embedding backend or endpoint"
}
```

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | integer 或 string | 接口错误为数字，认证/运行身份边界可能使用字符串。示例HTTP为503，但code为1。 |
| message | string | 接口失败说明，不按成功对象解析。 |
| details | object | 可选；上游诊断或计费拒绝时有不同字段，见[错误规则](responses-and-streams.md#错误与结束条件)。 |

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