# Embeddings

Convert text or multimodal content to vectors for later retrieval or similarity calculations.

```text
POST https://token.moi.matrixorigin.cn/v1/embeddings
```

## Before you call

Prepare credentials with Genesis access and a model ID that supports Embeddings.

## Request body

Replace `$GENESIS_ACCESS_TOKEN` with an access token or service-account API key, and `$MODEL_ID` with the model ID to call.

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

```bash
curl -X POST \
  "https://token.moi.matrixorigin.cn/v1/embeddings" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "input": [
      "MatrixOne is a database for the intelligent era.",
      "Genesis provides model invocation APIs."
    ],
    "encoding_format": "float"
  }'
```

:::::
:::::{tab-item} Parameter description

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Embeddings model ID to call. |
| `input` | string or array of string or array of object | Yes | Text to convert to vectors. |
| `encoding_format` | string | No | Vector encoding format. The example uses `float`. |
| `dimensions` | integer | No | Expected vector dimensions; use only when the selected model supports them. |

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

## Successful response

The service returns one corresponding vector result for each input.

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

```json
{
  "object": "list",
  "model": "<MODEL_ID>",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.018, -0.042, 0.337] }
  ]
}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Response object type; the example is `list`. |
| `model` | string | Model ID that processed the request. |
| `data` | array of object | Vector results for this input; each item corresponds to one input text. |

:::
:::{tab-item} Result item

The following table expands each item in the example `data` array.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Result object type; the example is `embedding`. |
| `index` | integer | Position corresponding to the `input` array. |
| `embedding` | array of number or string | Vector for this text; the actual type depends on the requested encoding format. |

:::
::::

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

## Error response

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

```json
{
  "error": {
    "message": "<human-readable error message>",
    "type": "<error type; may be omitted>",
    "code": "<error code; may be omitted>"
  }
}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `error` | object | Error object. |

:::
:::{tab-item} Error object

The following table expands the example `error` object.

| Field | Type | Description |
| --- | --- | --- |
| `message` | string | Human-readable error message. |
| `type` | string | Error category returned by the model service; it may be omitted. |
| `code` | string or null | Error code returned by the model service; it may be omitted. |

:::
::::

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

## Next steps

- [Rerank](../text-reranking/rerank.md)
- [List models](../models.md)