> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flatkey.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddings — POST /v1/embeddings

> Генерация векторных эмбеддингов для текста с помощью POST /v1/embeddings. Поддерживает пакетный ввод и несколько моделей эмбеддингов для семантического поиска, кластеризации и RAG.

Эндпоинт `/v1/embeddings` генерирует векторные эмбеддинги для текстового ввода. Эмбеддинги представляют семантическое значение текста в виде многомерного массива чисел с плавающей точкой, что позволяет выполнять поиск по сходству, кластеризацию и генерацию с дополнением извлечением (RAG). Эндпоинт совместим с OpenAI Embeddings API.

## Эндпоинт

```
POST https://router.flatkey.ai/v1/embeddings
```

## Поддерживаемые модели эмбеддингов

| Модель                   | Размерность | Провайдер |
| ------------------------ | ----------- | --------- |
| `gemini-embedding-001`   | 3072        | Google    |
| `text-embedding-3-small` | 1536        | OpenAI    |
| `text-embedding-3-large` | 3072        | OpenAI    |

См. [Каталог моделей](https://flatkey.ai/models) для актуальной информации о доступности и ценах.

## Запрос

### Заголовки

| Заголовок       | Значение                  |
| --------------- | ------------------------- |
| `Authorization` | `Bearer $FLATKEY_API_KEY` |
| `Content-Type`  | `application/json`        |

### Параметры тела запроса

<ParamField body="model" type="string" required>
  Идентификатор модели эмбеддингов. Пример: `"gemini-embedding-001"`, `"text-embedding-3-small"`.
</ParamField>

<ParamField body="input" type="string | array" required>
  Текст для эмбеддинга. Может быть одной строкой или массивом строк для пакетного создания эмбеддингов.
</ParamField>

<ParamField body="encoding_format" type="string">
  `"float"` (по умолчанию) возвращает массив чисел с плавающей точкой. `"base64"` возвращает строку в кодировке base64.
</ParamField>

<ParamField body="dimensions" type="integer">
  Количество измерений для выходного эмбеддинга. Поддерживается не всеми моделями.
</ParamField>

## Примеры запросов

<CodeGroup>
  ```python python theme={"dark"}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["FLATKEY_API_KEY"],
      base_url="https://router.flatkey.ai/v1",
  )

  # Single text
  response = client.embeddings.create(
      model="gemini-embedding-001",
      input="The quick brown fox jumps over the lazy dog",
  )

  embedding = response.data[0].embedding
  print(f"Embedding dimensions: {len(embedding)}")
  print(f"First 5 values: {embedding[:5]}")
  ```

  ```python python batch theme={"dark"}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["FLATKEY_API_KEY"],
      base_url="https://router.flatkey.ai/v1",
  )

  # Batch embedding
  texts = [
      "What is machine learning?",
      "How does neural network training work?",
      "Explain gradient descent",
  ]

  response = client.embeddings.create(
      model="gemini-embedding-001",
      input=texts,
  )

  for i, item in enumerate(response.data):
      print(f"{texts[i]}: {len(item.embedding)} dimensions")
  ```

  ```bash curl theme={"dark"}
  curl https://router.flatkey.ai/v1/embeddings \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-embedding-001",
      "input": "The quick brown fox jumps over the lazy dog"
    }'
  ```
</CodeGroup>

## Ответ

```json theme={"dark"}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292, ...]
    }
  ],
  "model": "gemini-embedding-001",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}
```

### Поля ответа

<ResponseField name="data" type="array">
  Массив объектов эмбеддингов, по одному на каждую входную строку.

  <Expandable title="объект эмбеддинга">
    <ResponseField name="index" type="integer">Позиция во входном массиве.</ResponseField>
    <ResponseField name="embedding" type="array">Массив чисел с плавающей точкой — вектор эмбеддинга.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage.prompt_tokens" type="integer">
  Количество обработанных токенов.
</ResponseField>

## Пример косинусного сходства

```python python theme={"dark"}
import os
import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

def embed(text):
    return client.embeddings.create(
        model="gemini-embedding-001",
        input=text,
    ).data[0].embedding

def cosine_similarity(a, b):
    a, b = np.array(a), np.array(b)
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

q = embed("capital city of France")
doc1 = embed("Paris is the capital and most populous city of France.")
doc2 = embed("The Eiffel Tower is a famous landmark.")

print(cosine_similarity(q, doc1))  # higher — more relevant
print(cosine_similarity(q, doc2))  # lower
```