# Create an embedding vector

Compatible with OpenAI `POST /v1/embeddings`. `input` may be a single string or an array of strings; when masking is on, personal fields detected in the text are replaced with placeholders **before** the vector is computed. The returned vector is therefore the vector of the masked text.

Two consequences follow, and both should be known upfront:

- **The same document always yields the same vector.** Placeholders on this endpoint are deterministic (`<PERSON_1>`), so re-embedding a document keeps your index consistent.
- **Masked entities cannot be told apart.** Two documents that differ only in a person’s name produce the same vector (measured: similarity 1.000), and a query naming a person scores both equally. Search does not fail; it returns the wrong person’s document just as readily. Topic search is unaffected. Indexing and querying must go through the same path.

Pre-tokenized input (an array of token ids) is not text and cannot be masked, so it is rejected **fail-closed** with 415.

POST `/v1/embeddings`

## Request body

required `application/json`

`model` string required

Embedding model id (defined in the panel).

`input` string | string[] required

Text or array of texts to embed. Token id arrays are not accepted (they cannot be masked and are rejected with 415).

One of:

string

`string`

string[]

Array of `string`

`string`

`dimensions` integer

Output vector size, when the model supports it.

min 1

`encoding_format` string

default: "float"

Allowed: `float` `base64`

## Responses

200 List of vectors

`object` string

`model` string

`data` object[]

Array of `object`

`object` string

`index` integer

`embedding` number[] | string<byte>

A number array when `encoding_format` is the default (`float`); a base64-encoded STRING when `base64` is requested. Your client must handle both shapes.

One of:

number[]

Array of `number`

`number`

string<byte>

`string<byte>`

`usage` object

`prompt_tokens` integer

`total_tokens` integer

401 Missing or invalid virtual key

`error` object

`message` string

`type` string

413 Input exceeds the masking limit. The request is not forwarded; split the text and retry.

`error` object

`message` string

`type` string

415 Input is pre-tokenized (an array of token ids). It is not text and cannot be masked, so the request is **fail-closed** and never reaches the provider. Send text instead.

`error` object

`message` string

`type` string

429 Quota or rate limit exceeded

`error` object

`message` string

`type` string

502 The masking step could not run. The request is **fail-closed** and never reaches the provider; there is no "send it unmasked" option.

`error` object

`message` string

`type` string

### Request

#### python

```
import requests

response = requests.post(
    "https://gw-tr.gurubase.io/v1/embeddings",
    headers={
        "Content-Type": "application/json"
    },
    json={
  "model": "text-embedding-3-small",
  "input": "string",
  "dimensions": 0,
  "encoding_format": "float"
},
)
```

#### curl

```
curl -X POST "https://gw-tr.gurubase.io/v1/embeddings" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "text-embedding-3-small",
  "input": "string",
  "dimensions": 0,
  "encoding_format": "float"
}'
```

#### js

```
const response = await fetch("https://gw-tr.gurubase.io/v1/embeddings", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "text-embedding-3-small",
  "input": "string",
  "dimensions": 0,
  "encoding_format": "float"
})
});
```

### Response

#### 200

```
{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "total_tokens": 0
  }
}
```

#### 401

```
{
  "error": {
    "message": "string",
    "type": "string"
  }
}
```

#### 413

```
{
  "error": {
    "message": "string",
    "type": "string"
  }
}
```

#### 415

```
{
  "error": {
    "message": "string",
    "type": "string"
  }
}
```

#### 429

```
{
  "error": {
    "message": "string",
    "type": "string"
  }
}
```

#### 502

```
{
  "error": {
    "message": "string",
    "type": "string"
  }
}
```