# Create an Embedding

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

Convert input content into vectors for retrieval or similarity calculations.

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

## Before you begin

1. Prepare a personal access token or service account API key for Genesis. See [Access credentials](../../../../guides/billing/credentials.md#choose-credential-type) for credential selection and permissions.
2. Use [List callable models](../models.md) to select a model that supports Embeddings.

## Request body

Replace `$GENESIS_ACCESS_TOKEN` and `$MODEL_ID` with your credential and the selected model ID.

:::::::{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": [
    "database",
    "search"
  ],
  "encoding_format": "float"
}'
```

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

The fields below cover text input. Images, videos, and multi-content vector output require corresponding model capabilities and input configuration.

::::{div} mo-api-parameter-table

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Selected model ID from `data[].id` in the model list. |
| `input` | string or array of string or array of object | Yes | Nonempty text input. Object fields are listed below. |
| `input[].content` | string or array of object | Required for object input | Text or text blocks for an object input. |
| `input[].content[].type` | string | Required for a text block | Use `text` for a text block. |
| `input[].content[].text` | string | Required for a text block | Nonempty text content. |
| `encoding_format` | string | No | Vector encoding. The text example uses `float`; `base64` requires model and service support. |
| `dimensions` | integer | No | Requested positive vector dimension; set only when supported by the selected model. |

::::

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

## Successful response

A successful request returns the vector for each input and token usage.

:::::::{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
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.032,
        0.011,
        0.296
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Object type `list`. |
| `model` | string | Model that processed the request. |
| `data` | array of object | Vectors for the input texts. |
| `data[].object` | string | Result type `embedding`. |
| `data[].index` | integer | Zero-based position in the input. |
| `data[].embedding` | array of number or string | Vector values; `float` returns a numeric array. The example vectors are shortened; actual length depends on the model and dimension setting. |
| `usage` | object | Token usage returned by the model. |
| `usage.prompt_tokens` | integer | Input tokens. |
| `usage.total_tokens` | integer | Total tokens. |

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

## Error response

A missing model ID returns HTTP `400`. Supply the model ID before sending the request again.

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

```json
{
  "error": {
    "message": "missing required parameter: model",
    "type": "invalid_request",
    "code": "invalid_request"
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `error` | object | Error details. |
| `error.message` | string | Error description; the example indicates a missing model ID. |
| `error.type` | string | Error type; may be omitted by a model service. |
| `error.code` | string or null | Error code; may be omitted by a model service. |

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