#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 your own provider keys (BYOK), connect your credentials.

This is an API, not a portal chat. There is no dialog window for talking to a model in the VibeCode portal — do not look for one. The request (prompt) is entered in your AI tool, agent, or code (Cursor, an 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 all API keys) | Base URL: https://vibecode.bitrix24.tech/v1 | Authorization: X-Api-Key header or Authorization: Bearer YOUR_API_KEY

#OpenAI SDK compatibility

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

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

By default the SDK passes the key in the Authorization: Bearer header — VibeCode accepts both options (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 — generate model responses in synchronous or streaming mode (Server-Sent Events)
• Models — list of available models and details of an individual model
• Speech recognition — convert audio to text via Whisper Large v3 Turbo
• Your own keys (BYOK) — connect your own provider keys
• Provider list — provider reference for connecting BYOK
• Usage statistics — token consumption and cost per API key
• OpenAI SDK compatibility — set up Cursor, IDE agents, and any OpenAI-compatible clients
• Model lifecycle — behavior of ACTIVE / DEPRECATED / DISABLED and the related headers
• Migration from legacy routes — for projects that still have calls to /v1/ai/chat/completions and similar

#Quick start

#1. Generate a response with a free model

curl -X POST https://vibecode.bitrix24.tech/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 the available models

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

Returns only the models for which the portal has provider credentials configured. 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.tech/v1/ai/usage?days=7"

#Common use cases

• Lead classification: request leads via `GET /v1/leads`, pass 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 into 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 into the deal timeline.

#Step 1. Speech recognition

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

Response:

{
  "text": "Hello, Vector LLC here. 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.tech/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": "Vector 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 budget of 500 thousand per month.\"}"
      }
    }
  ],
  "usage": {"prompt_tokens": 92, "completion_tokens": 36, "total_tokens": 128}
}

#Step 3. Write the result into the deal timeline

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

curl -X POST https://vibecode.bitrix24.tech/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 budget of 500 thousand per month."
  }'

All three endpoints live under one API key and one authorization — no separate integrations are required.

#Endpoint reference

#Error codes

Endpoints fall into two groups by 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 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"
  }
}

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

#System errors

Apply to any Vibe 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 contain:

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

X-Deprecated-Use suggests the canonical path. Move your 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 — these are the canonical paths.

#See also

• Limits and optimization — general Vibe API rate limits
• Key management — creating API keys and working with scopes
• Timeline comments — write AI processing results into a CRM card
• Bot platform — send AI responses to Bitrix24 chats