API reference · v1

От текста до ранжированного результата.

Два POST‑метода, стабильные псевдонимы моделей и единый формат ошибок. Базовый адрес — https://api.embeddings.ru.

01 / быстрый старт

Авторизация и повтор запроса

Передавайте API‑ключ в заголовке Authorization: Bearer …. Ключ показывается один раз при создании или ротации — восстановить его позже нельзя.

Каждый inference‑запрос требует новый Idempotency-Key. Безопасный повтор с тем же телом и ключом относится к исходной операции; повторное использование ключа с другим телом отклоняется.

Не отправляйте ключ в URL.Храните его в секретах сервера и никогда не добавляйте в браузерный код.

02 / embeddings

Постройте векторное представление

Метод принимает массив непустых строк. Поле input_type обязательно передаёт назначение: query для поискового запроса или document для индексируемого материала.

curl https://api.embeddings.ru/v1/embeddings \
  -H "Authorization: Bearer $EMBEDDINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "qwen3-embedding-4b-1536",
    "input": ["Как вернуть заказ?"],
    "input_type": "query"
  }'

ПолеЗначение

modelqwen3-embedding-4b-1536

inputМассив от 1 до 64 строк

input_typequery или document

03 / rerank

Уточните порядок кандидатов

Передайте запрос и уже найденные документы. Ответ содержит исходные индексы и оценки релевантности; текст документов не дублируется.

curl https://api.embeddings.ru/v1/rerank \
  -H "Authorization: Bearer $EMBEDDINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "условия возврата",
    "documents": [
      "Возврат доступен в течение 14 дней.",
      "Доставка занимает два рабочих дня."
    ],
    "top_n": 2
  }'

ПолеЗначение

modelbge-reranker-v2-m3

documentsМассив от 1 до 128 строк

top_nЦелое число от 1 до 128

04 / batches

Обрабатывайте большие наборы без долгого HTTP-запроса

POST /v1/batches принимает до 10 000 элементов, сохраняет задачу и сразу возвращает её идентификатор. Обработка продолжается в фоне: статус и прогресс доступны после разрыва соединения, перезапуска клиента или повторного входа в кабинет.

# Создать задачу
curl https://api.embeddings.ru/v1/batches \
  -H "Authorization: Bearer $EMBEDDINGS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "operation": "embeddings",
    "model": "qwen3-embedding-4b-1536",
    "input_type": "document",
    "input": ["первый документ", "второй документ"]
  }'

# Проверить статус
curl https://api.embeddings.ru/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $EMBEDDINGS_API_KEY"

# Читать результаты страницами
curl "https://api.embeddings.ru/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $EMBEDDINGS_API_KEY"

# Отменить незавершённую задачу
curl -X POST https://api.embeddings.ru/v1/batches/$BATCH_ID/cancel \
  -H "Authorization: Bearer $EMBEDDINGS_API_KEY"

МетодНазначение

GET /v1/batches/:idСтатус, общий прогресс и срок хранения

GET /v1/batches/:id/resultsРезультаты страницами до 500 элементов

POST /v1/batches/:id/cancelБезопасная повторяемая отмена

Для чего нужны batchesИспользуйте их для первичной индексации базы знаний, каталога, архива документов или массового пересчёта поиска. Для быстрых интерактивных вызовов остаются синхронные лимиты: 64 текста для embeddings и 128 документов для rerank.

05 / границы

Ограничения запроса

2 MiBмаксимальное JSON‑тело

4096токенов на один текст

64текста для embeddings

128документов для rerank

Лимиты аккаунта и доступный баланс проверяются до постановки запроса в очередь. При исчерпании лимита API отвечает безопасной ошибкой и не запускает вычисление.

06 / ошибки

Один конверт для всех ошибок

Сохраняйте request_id для диагностики и повторяйте запрос только когда retryable равно true. Сообщение предназначено для разработчика и не содержит внутренние детали исполнения.

{
  "error": {
    "version": "1",
    "request_id": "req_…",
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded",
    "retryable": true
  }
}

07 / models

Получите доступные псевдонимы

GET /v1/models использует тот же Bearer‑ключ и возвращает только публичные стабильные имена. Версию API фиксирует путь /v1.

Данные запросаТексты обрабатываются для inference и не записываются в прикладные логи. Подробности — в политике хранения данных.