Перейти к основному содержанию
POST
/
v1
/
embeddings
Создать эмбеддинги
curl --request POST \
  --url https://polza.ai/api/v1/embeddings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "Пример текста для создания эмбеддинга",
  "model": "thenlper/gte-base",
  "encoding_format": "float",
  "dimensions": 768,
  "user": "user-123"
}
'
import requests

url = "https://polza.ai/api/v1/embeddings"

payload = {
    "input": "Пример текста для создания эмбеддинга",
    "model": "thenlper/gte-base",
    "encoding_format": "float",
    "dimensions": 768,
    "user": "user-123"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: 'Пример текста для создания эмбеддинга',
    model: 'thenlper/gte-base',
    encoding_format: 'float',
    dimensions: 768,
    user: 'user-123'
  })
};

fetch('https://polza.ai/api/v1/embeddings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://polza.ai/api/v1/embeddings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => 'Пример текста для создания эмбеддинга',
    'model' => 'thenlper/gte-base',
    'encoding_format' => 'float',
    'dimensions' => 768,
    'user' => 'user-123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://polza.ai/api/v1/embeddings"

	payload := strings.NewReader("{\n  \"input\": \"Пример текста для создания эмбеддинга\",\n  \"model\": \"thenlper/gte-base\",\n  \"encoding_format\": \"float\",\n  \"dimensions\": 768,\n  \"user\": \"user-123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://polza.ai/api/v1/embeddings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": \"Пример текста для создания эмбеддинга\",\n  \"model\": \"thenlper/gte-base\",\n  \"encoding_format\": \"float\",\n  \"dimensions\": 768,\n  \"user\": \"user-123\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://polza.ai/api/v1/embeddings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": \"Пример текста для создания эмбеддинга\",\n  \"model\": \"thenlper/gte-base\",\n  \"encoding_format\": \"float\",\n  \"dimensions\": 768,\n  \"user\": \"user-123\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": "gen_581761234567890123",
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797347
      ],
      "index": 0
    }
  ],
  "model": "thenlper/gte-base",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8,
    "cost_rub": 0.00001,
    "cost": 0.00001
  }
}

Доступные модели

МодельIDРазмерность
text-embedding-3-largetext-embedding-3-large3072
text-embedding-3-smalltext-embedding-3-small1536

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

ПараметрТипОбязательныйОписание
modelstringДаID модели
inputstring/arrayДаТекст или массив текстов
encoding_formatstringНетФормат: float, base64
dimensionsintegerНетРазмерность вывода
userstringНетИдентификатор конечного пользователя

Примеры

curl -X POST "https://polza.ai/api/v1/embeddings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-large",
    "input": ["Пример текста для поиска", "Второй пример"]
  }'
from openai import OpenAI

client = OpenAI(
    base_url="https://polza.ai/api/v1",
    api_key="YOUR_API_KEY"
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=["Первый документ", "Второй документ"]
)

for item in response.data:
    print(f"Index {item.index}: {len(item.embedding)} dimensions")
const response = await fetch('https://polza.ai/api/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'text-embedding-3-large',
    input: 'Текст для получения эмбеддинга'
  })
});

const data = await response.json();
console.log(data.data[0].embedding);

Ответ (200)

{
  "id": "emb_123456",
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.01, -0.02, 0.03, "..."],
      "index": 0
    },
    {
      "object": "embedding",
      "embedding": [0.03, 0.11, -0.05, "..."],
      "index": 1
    }
  ],
  "model": "text-embedding-3-large",
  "usage": {
    "prompt_tokens": 42,
    "total_tokens": 42,
    "cost_rub": 0.05,
    "cost": 0.05
  }
}

Работа с изображениями

Некоторые модели эмбеддингов поддерживают изображения на входе — это даёт мультимодальные эмбеддинги, которые улавливают визуальный контент вместе с текстом. Полезно для поиска по изображениям, определения визуального сходства и кросс-модального поиска. Чтобы передать изображение, оберните входные данные в мультимодальный формат с массивом content, содержащим объекты image_url. В одном блоке ввода можно комбинировать текст и изображения.
МодельIDМультимодальная
Google: Gemini Embedding 2 Previewgoogle/gemini-embedding-2-previewмультимодальная (текст + изображения)
curl https://polza.ai/api/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $POLZA_API_KEY" \
  -d '{
  "model": "google/gemini-embedding-2-preview",
  "input": [
    {
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,..."
          }
        }
      ]
    }
  ],
  "encoding_format": "float"
}'
Текст и изображения можно совместить в одном входе, чтобы получить объединённый эмбеддинг:
curl https://polza.ai/api/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $POLZA_API_KEY" \
  -d '{
    "model": "google/gemini-embedding-2-preview",
    "input": [
      {
        "content": [
          {"type": "text", "text": "Деревянный настил среди зелёного луга"},
          {"type": "image_url", "image_url": {"url": "https://example.com/example.jpg"}}
        ]
      }
    ],
    "encoding_format": "float"
  }'
Возможность передавать изображения зависит от модели. Полный список моделей с поддержкой image input см. в разделе «Доступные модели» ниже и в каталоге моделей.

Все доступные модели

  • YandexGPT Embeddings — Query: yandex/text-search-query
  • YandexGPT Embeddings — Doc: yandex/text-search-doc
  • Google: Gemini Embedding 001: google/gemini-embedding-001
  • Google: Gemini Embedding 2 Preview: google/gemini-embedding-2-preview (мультимодальная)
  • Qwen: Qwen3 Embedding 8B: qwen/qwen3-embedding-8b
  • Qwen: Qwen3 Embedding 4B: qwen/qwen3-embedding-4b
  • OpenAI: Text Embedding Ada 002: openai/text-embedding-ada-002
  • OpenAI: Text Embedding 3 Small: openai/text-embedding-3-small
  • OpenAI: Text Embedding 3 Large: openai/text-embedding-3-large

Применения

Семантический поиск

Поиск по смыслу, а не по ключевым словам

RAG

Retrieval-Augmented Generation для LLM

Кластеризация

Группировка похожих документов

Классификация

Категоризация текстов

Рекомендации

1

Нормализуйте тексты

Приведите тексты к единому формату перед получением эмбеддингов
2

Разделяйте на чанки

Оптимальный размер чанка: 200-800 токенов
3

Используйте косинусное сходство

Для сравнения эмбеддингов используйте cosine similarity или dot-product
4

Кэшируйте результаты

Сохраняйте эмбеддинги и кэшируйте повторяющиеся по хешу текста

Авторизации

Authorization
string
header
обязательно

API ключ передаётся в заголовке: Authorization: Bearer <POLZA_AI_API_KEY>

Тело

application/json
input
обязательно

Входной текст или массив текстов для создания эмбеддингов

Пример:

"Пример текста для создания эмбеддинга"

model
string
обязательно

Идентификатор модели для создания эмбеддингов

Пример:

"thenlper/gte-base"

encoding_format
enum<string>
по умолчанию:float

Формат кодирования эмбеддингов

Доступные опции:
float,
base64
Пример:

"float"

dimensions
number

Размерность выходного эмбеддинга (если модель поддерживает). Должна быть меньше или равна максимальной размерности модели

Требуемый диапазон: x >= 1
Пример:

768

user
string

Уникальный идентификатор конечного пользователя для отслеживания и предотвращения злоупотреблений

Пример:

"user-123"

Ответ

id
string
обязательно

Уникальный идентификатор запроса

Пример:

"gen_581761234567890123"

object
enum<string>
обязательно

Тип объекта (всегда "list")

Доступные опции:
list
Пример:

"list"

data
object[]
обязательно

Массив эмбеддингов

model
string
обязательно

ID модели, которая создала эмбеддинги

Пример:

"thenlper/gte-base"

usage
object
обязательно

Информация об использовании токенов