Эмбеддинги
POST /api/v1/embeddings — векторные представления текста для поиска, классификации и кластеризации
curl --request POST \
--url https://speshu.ai/api/v1/embeddings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"input": "<unknown>",
"dimensions": 2,
"input_type": "<string>",
"user": "<string>",
"provider": "<unknown>"
}
'import requests
url = "https://speshu.ai/api/v1/embeddings"
payload = {
"model": "<string>",
"input": "<unknown>",
"dimensions": 2,
"input_type": "<string>",
"user": "<string>",
"provider": "<unknown>"
}
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({
model: '<string>',
input: '<unknown>',
dimensions: 2,
input_type: '<string>',
user: '<string>',
provider: '<unknown>'
})
};
fetch('https://speshu.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://speshu.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([
'model' => '<string>',
'input' => '<unknown>',
'dimensions' => 2,
'input_type' => '<string>',
'user' => '<string>',
'provider' => '<unknown>'
]),
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://speshu.ai/api/v1/embeddings"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": \"<unknown>\",\n \"dimensions\": 2,\n \"input_type\": \"<string>\",\n \"user\": \"<string>\",\n \"provider\": \"<unknown>\"\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://speshu.ai/api/v1/embeddings")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": \"<unknown>\",\n \"dimensions\": 2,\n \"input_type\": \"<string>\",\n \"user\": \"<string>\",\n \"provider\": \"<unknown>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://speshu.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 \"model\": \"<string>\",\n \"input\": \"<unknown>\",\n \"dimensions\": 2,\n \"input_type\": \"<string>\",\n \"user\": \"<string>\",\n \"provider\": \"<unknown>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "list",
"model": "<string>",
"data": [
{
"object": "embedding",
"embedding": "<unknown>",
"index": 123
}
],
"usage": {
"prompt_tokens": 123,
"total_tokens": 123,
"cost": 123
},
"id": "<string>"
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}GET /api/v1/models, у которых в capabilities есть значение "embeddings".
Минимальный запрос
Сначала получите идентификатор модели из каталога, отфильтровав его поcapabilities:
MODEL=$(curl -s https://speshu.ai/api/v1/models \
| jq -r '.data[] | select(.capabilities | index("embeddings")) | .id' \
| head -n 1)
curl https://speshu.ai/api/v1/embeddings \
-H "Authorization: Bearer $SPESHU_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"model\": \"$MODEL\",
\"input\": \"Как вернуть товар в течение 14 дней?\"
}"
GET /api/v1/models и подставляйте как есть. Состав моделей меняется, поэтому в рабочем коде не зашивайте его литералом. Если передать идентификатор обычной текстовой модели или неизвестное значение, придёт 404 с кодом model_not_found.Поля запроса
| Поле | Тип | Описание |
|---|---|---|
model | string | Идентификатор модели из каталога с capabilities, содержащим "embeddings". Обязательно |
input | string или array | Текст для векторизации: строка, массив строк или массив мультимодальных блоков. Обязательно; пустая строка и пустой массив не принимаются |
encoding_format | string | Формат вектора: float (массив чисел, по умолчанию) или base64 (строка). Необязательно |
dimensions | integer | Размерность вектора, не меньше 1. Поддерживают не все модели — лишнее значение не отсекается сервером. Необязательно |
input_type | string | Тип входа для моделей, которые различают запрос и документ при поиске. Необязательно |
user | string | Идентификатор пользователя на вашей стороне, до 256 символов. Необязательно |
provider | object | Параметры выбора провайдера модели, передаются как есть. Необязательно |
input векторизует несколько текстов за один вызов — в ответе на каждый элемент приходится свой объект в data с его индексом. Проверки полей идут до обращения к модели: неверный encoding_format, dimensions меньше 1 или слишком длинный user дают 400 invalid_request, а не испорченный ответ.
Ответ
200 OK:
{
"id": "emb-...",
"object": "list",
"model": "идентификатор-модели",
"data": [
{
"object": "embedding",
"embedding": [0.012, -0.034, 0.008],
"index": 0
}
],
"usage": {
"prompt_tokens": 12,
"total_tokens": 12,
"cost": 0.0000014
}
}
| Поле | Тип | Описание |
|---|---|---|
object | string | Всегда "list" |
data | array | Один объект на каждый элемент input |
data[].object | string | Всегда "embedding" |
data[].embedding | array или string | Вектор: массив чисел с encoding_format: "float" (по умолчанию) или строка base64 с "base64" |
data[].index | integer | Позиция элемента в input — связывает вектор с его текстом |
model | string | Идентификатор модели, которая построила векторы |
usage.prompt_tokens | integer | Входные токены |
usage.total_tokens | integer | Всегда равен prompt_tokens — выходных токенов у эмбеддингов нет |
usage.cost | number | Сумма, списанная с вашего баланса за вызов. Поле отсутствует, если списание не зафиксировано |
Стоимость
Списание идёт только за входные токены по ценеcost_context модели из GET /api/v1/models; выходные токены всегда нулевые, поэтому cost_completion на стоимость вызова не влияет. usage.cost — та самая списанная сумма в рублях. Фактический остаток после вызова проверяйте через GET /api/v1/balance.
Проверки перед вызовом
Часть ошибок возвращается до обращения к модели:| Ситуация | Ответ |
|---|---|
| Нет ключа или ключ недействителен | 401 invalid_api_key |
| Модель не из списка эмбеддинг-моделей | 404 model_not_found |
| Не хватает денег | 402 insufficient_quota |
Нет model или input, пустой input, неверный encoding_format, dimensions меньше 1 | 400 invalid_request |
user длиннее 256 символов | 400 invalid_request |
error с полями message, type, param и code. Полная таблица кодов — на странице Ошибки.
Что дальше
Каталог моделей
Оценка решений
Баланс
Ошибки
Авторизации
API-ключ в формате sk-.... Альтернативно — заголовок X-Api-Key: sk-... (совместимо с Anthropic SDK).
Тело
Идентификатор модели из GET /api/v1/models: у неё в capabilities есть значение "embeddings". Передаётся как есть.
Текст для векторизации: строка, массив строк или массив мультимодальных блоков. Обязательно; пустая строка и пустой массив не принимаются.
Формат вектора: float — массив чисел (по умолчанию), base64 — строка.
float, base64 Размерность вектора, не меньше 1. Поддерживают не все модели. Необязательно.
x >= 1Тип входа для моделей, которые различают запрос и документ при поиске. Необязательно.
128Идентификатор пользователя на вашей стороне. Необязательно.
256Параметры выбора провайдера модели, передаются как есть. Необязательно.
curl --request POST \
--url https://speshu.ai/api/v1/embeddings \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"input": "<unknown>",
"dimensions": 2,
"input_type": "<string>",
"user": "<string>",
"provider": "<unknown>"
}
'import requests
url = "https://speshu.ai/api/v1/embeddings"
payload = {
"model": "<string>",
"input": "<unknown>",
"dimensions": 2,
"input_type": "<string>",
"user": "<string>",
"provider": "<unknown>"
}
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({
model: '<string>',
input: '<unknown>',
dimensions: 2,
input_type: '<string>',
user: '<string>',
provider: '<unknown>'
})
};
fetch('https://speshu.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://speshu.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([
'model' => '<string>',
'input' => '<unknown>',
'dimensions' => 2,
'input_type' => '<string>',
'user' => '<string>',
'provider' => '<unknown>'
]),
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://speshu.ai/api/v1/embeddings"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"input\": \"<unknown>\",\n \"dimensions\": 2,\n \"input_type\": \"<string>\",\n \"user\": \"<string>\",\n \"provider\": \"<unknown>\"\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://speshu.ai/api/v1/embeddings")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"input\": \"<unknown>\",\n \"dimensions\": 2,\n \"input_type\": \"<string>\",\n \"user\": \"<string>\",\n \"provider\": \"<unknown>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://speshu.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 \"model\": \"<string>\",\n \"input\": \"<unknown>\",\n \"dimensions\": 2,\n \"input_type\": \"<string>\",\n \"user\": \"<string>\",\n \"provider\": \"<unknown>\"\n}"
response = http.request(request)
puts response.read_body{
"object": "list",
"model": "<string>",
"data": [
{
"object": "embedding",
"embedding": "<unknown>",
"index": 123
}
],
"usage": {
"prompt_tokens": 123,
"total_tokens": 123,
"cost": 123
},
"id": "<string>"
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}{
"error": {
"message": "<string>",
"type": "invalid_request_error",
"param": "<string>",
"code": "invalid_request"
}
}