#AI Router

A single OpenAI-compatible API for working with language models from different providers. Free Bitrix24 models are available right away — for paid models and for your own provider keys (BYOK), connect the credentials.

This is an API, not a chat interface. There is no dialog window for talking to a model in your Vibecode account — you don't need to look for one. The request (prompt) is entered in your AI tool, agent, or code (Cursor, IDE agent, the openai library, your own application), which calls this API at the address below. Free Bitrix24 models work the same way as paid and BYOK models — through the same API.

Scope: vibe:ai (added automatically to every API key) | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: the X-Api-Key header or Authorization: Bearer YOUR_API_KEY

#OpenAI SDK compatibility

All responses are returned in the raw OpenAI format. Connect any OpenAI-compatible tool (Cursor, IDE agents, the openai library) through the standard settings:

Base URL: https://vibecode.bitrix24.com/v1
API Key:  your key vibe_api_... or vibe_app_...

By default the SDK passes the key in the Authorization: Bearer header — Vibecode accepts both (X-Api-Key and Authorization: Bearer). The request parameters (model, messages, temperature, tools, stream, response_format) and response fields (id, choices, usage) match the POST /v1/chat/completions contract from the OpenAI API.

#Documentation sections

• Chat completions — generating a model response in synchronous or streaming mode (Server-Sent Events)
• Models — the list of available models and details of a single model
• Speech recognition — converting audio to text via Whisper Large v3 Turbo
• Embeddings — converting text into vector representations (OpenAI format)
• Your own keys (BYOK) — connecting your own provider keys
• Consumption and limits — statistics per key, the company's monthly quota, and off-peak hours
• OpenAI SDK compatibility — configuring Cursor, IDE agents, and any OpenAI-compatible clients
• Model lifecycle — the behavior of ACTIVE / DEPRECATED / DISABLED and the related headers
• Migration from legacy routes — for projects that still call /v1/ai/chat/completions and similar legacy routes

#Quick start

#1. Generate a response with a free model

curl -X POST https://vibecode.bitrix24.com/v1/chat/completions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [{"role": "user", "content": "What is CRM?"}]
  }'

Response:

{
  "id": "chatcmpl-a1a73c6eb3f180fd",
  "object": "chat.completion",
  "created": 1777289339,
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "CRM is a customer relationship management system."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 18,
    "total_tokens": 30
  }
}

#2. View available models

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/models

Returns only the models that have provider credentials configured in your account. Bitrix24 models (bitrix/*) are available to everyone without separate BYOK keys. Most of them are free.

#3. Check token consumption

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/ai/usage?days=7"

#Common use cases

• Lead classification: request leads via GET /v1/leads, run them through a chat completion with response_format: json_object, update CRM fields via PATCH /v1/leads/:id.
• Content generation: read products via GET /v1/products, generate descriptions, update the cards in the catalog.
• Data extraction: take comments from GET /v1/timeline-logs, extract phone / email / company name, write them to CRM.
• Chatbot: register a bot via POST /v1/bots, receive events via GET /v1/bots/:botId/events, generate an AI response, send it via POST /v1/bots/:botId/messages.
• Reports: collect data via POST /v1/batch, generate a summary, send a notification.

#Full example: call transcription → classification → timeline entry

Scenario: get a call recording, transcribe it via Whisper, classify the lead quality via the model's JSON response, write the result to the deal timeline.

#Step 1. Speech recognition

curl -X POST https://vibecode.bitrix24.com/v1/audio/transcriptions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@call-recording.mp3" \
  -F "language=en" \
  -F "response_format=json"

Response:

{
  "text": "Hello, Acme LLC. We want CRM for 50 users, budget up to 500 thousand per month."
}

#Step 2. Lead classification with guaranteed `JSON`

curl -X POST https://vibecode.bitrix24.com/v1/chat/completions \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [
      {
        "role": "system",
        "content": "Classify the lead from the call text. Return JSON: {\"quality\": \"high|medium|low\", \"score\": 0-100, \"reason\": \"...\"}."
      },
      {
        "role": "user",
        "content": "Acme LLC. CRM for 50 users, budget up to 500 thousand per month."
      }
    ],
    "response_format": {"type": "json_object"}
  }'

Response:

{
  "id": "chatcmpl-acdb112cf9cdf9f9",
  "object": "chat.completion",
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "{\"quality\":\"high\",\"score\":88,\"reason\":\"Legal entity, specific volume (50 users) and a budget of 500 thousand per month.\"}"
      }
    }
  ],
  "usage": {"prompt_tokens": 92, "completion_tokens": 36, "total_tokens": 128}
}

#Step 3. Write the result to the deal timeline

Parse choices[0].message.content as JSON and send it to the timeline:

curl -X POST https://vibecode.bitrix24.com/v1/timeline-logs \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 1234,
    "title": "AI classification: high (88/100)",
    "text": "Legal entity, specific volume (50 users) and a budget of 500 thousand per month."
  }'

All three endpoints work with the same API key and the same authorization — no separate integrations are required.

#Endpoint reference

#Error codes

Endpoints fall into two groups by their error response format:

Raw OpenAI format (/v1/chat/completions, /v1/models, /v1/audio/transcriptions):

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": "ai_model_not_found"
  }
}

type takes the following values: invalid_request_error (4xx), insufficient_quota (402), service_unavailable (503), server_error (5xx). code is always lowercase.

V1 format (/v1/ai/usage, /v1/ai/credentials/*, /v1/ai/providers):

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}

The V1 format carries the regular errors of these endpoints themselves. An unexpected server error 5xx on any /v1/ai/* route is returned in the raw OpenAI format. It also works the other way round: quota and pacing rejections (402 ai_quota_exhausted, 429 ai_pacing_limited) on the OpenAI-compatible endpoints arrive in the envelope with success: false. An error handler must accept both envelopes on either route family.

Whisper / /v1/audio/transcriptions: the processing window is up to 15 minutes. Long / noisy audio may take several minutes. For audio longer than ~30 min, consider splitting it into parts.

#System errors

Applicable to any Vibecode API endpoint, including the AI Router section:

The full list of common API errors — Errors.

#Migration from legacy routes

If your code still has calls like /v1/ai/chat/completions, /v1/ai/models, /v1/ai/audio/transcriptions — they keep working in backward-compatibility mode. The response headers carry:

Deprecation: true
X-Deprecated-Use: /v1/chat/completions

X-Deprecated-Use indicates the canonical path. Move the calls to the canonical routes — this removes the Deprecation header and eliminates the risk of the old path being removed in the future.

The routes /v1/ai/usage, /v1/ai/credentials/*, /v1/ai/providers have no legacy equivalent — they are canonical paths.

#See also

• Limits and optimization
• Key management
• Timeline comments
• Bot platform