Create embeddings

POST /v1/embeddings

Converts text into a vector representation. Vectors are used for semantic search, clustering, duplicate detection, and finding similar CRM cards. The request and response format is compatible with the OpenAI API. Streaming is not supported.

Embeddings are supported only by models whose capabilities.embeddings field equals true in GET /v1/models.

Request fields (body)

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/embeddings \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/embeddings",
    "input": "We want a CRM for 50 users"
  }'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/embeddings \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/embeddings",
    "input": "We want a CRM for 50 users"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/embeddings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/embeddings',
    input: ['First text', 'Second text'],
  }),
})

const result = await res.json()
console.log(result.data.length)        // 2 — one vector per string
console.log(result.data[0].embedding)  // [0.0203, 0.0034, ...]

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/embeddings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/embeddings',
    input: ['First text', 'Second text'],
  }),
})

const result = await res.json()

Response fields

The response comes in raw OpenAI format, without the success and data wrapper.

Response example

The first three vector values are shown. The full dimensionality depends on the model — for bitrix/embeddings it is 4096 values, and the vector arrives normalized to unit length.

{
  "object": "list",
  "model": "bitrix/embeddings",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0203, 0.0034, -0.0156]
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 0,
    "total_tokens": 12
  }
}

Error response example

501 embeddings_unsupported — the model does not support embeddings:

{
  "error": {
    "message": "Model \"bitrix/bitrixgpt-5.5\" does not support embeddings.",
    "type": "server_error",
    "code": "embeddings_unsupported"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

Error codes come in lowercase. Most error bodies use the raw OpenAI format { "error": { "message", "type", "code" } }, without a success field. The 402 company_budget_exhausted rejection uses the same format — the scope and canRequest fields sit inside the same error object. Only quota and pacing rejections — 402 ai_quota_exhausted and 429 ai_pacing_limited — and an unexpected 5xx server error, whose code is written in uppercase, arrive in the { "success": false, "error": { … } } envelope. A handler must accept both envelopes.

The input array preserves order. The vector data[i] corresponds to the string input[i], and the data[].index field duplicates this position — you can use it to match the result after parallel processing.

The processing budget for a request is about 850 seconds. Once the budget runs out, 503 ai_provider_timeout is returned. This response deliberately carries no Retry-After header: repeating the same request would hit the same budget. Split the input array into smaller parts.

Response latency is not guaranteed for either a single text or an input array. It can vary from call to call, and several requests with an input array sent in a row may respond progressively more slowly. The dimensions parameter does not affect response speed. Add a pause between such requests and do not rely on the input array in an interactive scenario.

The top-up hint in a 402 ai_quota_exhausted response. Only in the reason: "wallet_empty" case may the response additionally carry a hint string and a topupUrl link to top up the balance. Both fields appear when enforced quota control and the top-up hint are enabled on the platform, so treat them as optional. The hint field in this response is a string. When the Bitrix24 account has no paid AI access, a reason: "wallet_off" response additionally carries details.learnMoreUrl — a page that describes the paid Bitrix24 plan that includes AI — and the message field names that plan. For other wallet_off causes details.learnMoreUrl is absent.

Usage is calculated from input tokens only. The usage.completion_tokens field is always 0, so you pay only for the input. The current input price of every model comes from GET /v1/models — read it there rather than from a fixed number in the documentation.

The dimensionality can be reduced. The bitrix/embeddings model is built so that the meaningful part of a vector is concentrated at its start: keeping the first k values and re-normalizing the vector to unit length left the ordering of search results unchanged in our tests, down to the smallest dimensions. This is a property of the model rather than a platform guarantee — measure it on your own data. The dimensions parameter does this on the platform side; you can get the same result yourself by truncating the vector and dividing every value by the length of the truncated vector. Re-normalizing is mandatory: a raw truncated vector has a length below one (for a 256-value vector the length is about 0.26), and without that step the dot product no longer matches cosine similarity and comparisons against previously stored vectors drift.

Sensible values are 256, 512, 1024, and 2048; these are reference points rather than the only accepted ones — any integer from 32 to 4096 works, including 1536 and 2000. The shorter the vector, the smaller the margin between a relevant result and a semantically close competitor, so choose the dimensionality by measuring on your own data.

A smaller dimensionality does not make a request cheaper or faster. The model still computes the full vector and the platform truncates it in the response: input-token usage and processing time do not change. The savings are on your side — less index storage, less memory, and faster search.

Vectors of different dimensionality must not be mixed in one similarity index. A 256-value and a 1024-value vector live in different spaces, and distances between them are meaningless. If you change the dimensionality, rebuild the entire index.

See also

• Models list
• Create a chat completion
• Company AI quota
• AI Router