<span id="调用工作区向量模型"></span>

# Invoke a workspace embedding model

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

Convert text or model-supported input into vectors through a workspace embedding model. Large inputs may require multiple upstream calls.

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

<span id="调用前准备"></span>

## Before you call this API

Set `MOI_ENDPOINT` to the product API prefix `https://api.moi.matrixorigin.cn/v5`; use the corresponding product API URL for a dedicated deployment.

Prepare a personal access token, workspace ID, and an actually invocable model name in the target environment. Confirm that the model/endpoints are configured and online. Successful model-list or routing-configuration reads do not establish inference availability. MOI_ENDPOINT must include the environment's actual API prefix; production documentation uses /v5. Internal direct access does not replace a verified gateway. Calls may generate usage records and charges under environment configuration. Do not send audit test requests to real models.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

| Parameter | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| workspace_id | Path | string | Yes | Workspace ID in the same environment. |
| X-API-Key | Headers | string | Yes | Personal access token in the current environment. |
| X-Workspace-ID | Headers | string | Gateway-dependent | The example explicitly includes the same workspace. The handler uses the path workspace; actual authentication/runtime identity boundaries still require verification. |
| service_slot | Queries | string | No | Configured service slot name, affecting routing and billing attribution. It is not an authorization credential or arbitrary purpose label. |

See [request fields](request-fields.md) for complete fields and provider adapter limitations. The body limit is 4 MiB and input arrays allow at most 4096 items. The current invoker accepts only OPENAI backends. The ability to create other types through management APIs does not establish executability.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| object | string | Usually list. |
| data | object (array of objects) | Vector entries, not a product envelope. See [complete response fields](responses-and-streams.md) for index/vector fields. |
| model | string | Model identifier returned by the provider. |
| usage | object | Provider usage; may be absent. Batched results may be merged. |

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

<span id="错误响应"></span>

## Error responses

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| code | integer or string | API errors use numbers; authentication/runtime identity boundaries may use strings. The example HTTP status is 503 while code is 1. |
| message | string | API failure description; do not parse as a success object. |
| details | object | Optional. Upstream diagnostics and billing denials have different fields; see [error rules](responses-and-streams.md#errors-and-completion-conditions). |

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