<span id="探测已配置嵌入后端模型"></span>

# Probe models on a configured embedding backend

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

Requires model_backend.read on the specified backend.


```http
POST https://api.moi.matrixorigin.cn/v5/embedding/backends/{backend_id}/probe-models
```

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

## Before you call this API

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

[Configure identity, workspace, and model information in the same environment](objects.md#prepare).

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

## Request

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

```bash
curl --request POST \
  "$BASE_URL/embedding/backends/$BACKEND_ID/probe-models" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-raw '{"api_key":"provider-key-example"}'
```

:::::
:::::{tab-item} Parameters

| Parameter | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Workspace-ID` | Headers | string | Yes | Workspace ID in the same environment. |
| `api_key` | Body | string | Yes | Provider key for this request, nonempty after trimming whitespace. Does not automatically reuse the backend's saved key. |
| `backend_id` | Path | integer | Yes | Positive backend ID from the list of the same backend kind. |

Requires model_backend.read on the specified backend. Reads the first saved address, without preferring online status or automatic rotation. An empty first address fails. Candidates are not automatically written back to the backend model list; update separately afterward.

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

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

## Successful response

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "models": [
      "bge-m3"
    ]
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `data` | object | [Model, probe, or settings result](objects.md#response). |

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

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

## Error responses

[States and errors](objects.md#errors) distinguishes string and numeric protocols. Confirm probe candidates, persistence, and actual inference separately.
