Chat completions

Generate a model's response through a single OpenAI-compatible endpoint. Supports synchronous mode, streaming via Server-Sent Events, function calling, a guaranteed JSON response, and working with images.

Scope: vibe:ai

Create a chat completion

The response arrives in raw OpenAI format.

The {success, data} wrapper used by the other Vibecode endpoints — /v1/deals, /v1/tasks and others — is absent here.

This is done for compatibility with the OpenAI SDK. If you have a single client that checks if (!response.success), add an exception for the AI Router.

POST /v1/chat/completions

Generates an AI model's response to an array of messages. The request and response format is compatible with POST /v1/chat/completions from the OpenAI API.

The endpoint's capabilities are documented on separate pages: streaming, guaranteed JSON response, function calling, image analysis and rate limits.

Request fields (body)

Reasoning control

Reasoning models think before they answer. Reasoning tokens count towards usage.completion_tokens and are billed as output tokens at the same rate — the price lever is volume, not the rate. Vibecode describes that volume with five steps: none — answer immediately, low — a brief sketch, medium — the model's standard reasoning when it is enabled and no level is given, high — stronger than standard, max — everything the model can do.

The reasoning field in GET /v1/models shows what a particular model supports. Its map maps the steps onto the model's native modes; two steps sharing one native value are a declared collapse. default is the default step, and budgetTokens indicates support for a reasoning token budget. On a model with reasoning: null, control is unavailable: the parameter is ignored with the REASONING_NOT_SUPPORTED warning, and nothing is added to the model call.

Input normalization: minimal → low, xhigh → max. reasoning.enabled: true or chat_template_kwargs.thinking: true without a level gives medium. reasoning.max_tokens without effort gives medium with a budget. An empty reasoning: {} or chat_template_kwargs: {} is the same as no parameter. null in any of the three fields is equivalent to omitting it. When several fields arrive, the highest-precedence one wins: reasoning first, then reasoning_effort, then chat_template_kwargs. A value outside the vocabulary, a non-positive reasoning.max_tokens or a non-object chat_template_kwargs is rejected with 400 invalid_request.

If the model lacks the requested step, the nearest step below among the reasoning steps is applied, and warnings carries REASONING_EFFORT_ADJUSTED with the requested, applied and direction fields. The none step is never chosen by rounding — reasoning can only be disabled explicitly. If there is no step below, the nearest step above is taken. Asking for none on a model where reasoning cannot be disabled gives the lowest step and REASONING_CANNOT_BE_DISABLED. A budget on a model without budgetTokens is ignored with REASONING_BUDGET_NOT_SUPPORTED.

When the request omits the parameter, the platform explicitly sends the default step to a model with a reasoning declaration. The mode is not left to the model provider, so a model update on the provider's side does not change the behavior of requests without the parameter. The response's reasoning field reports that step.

The response carries the reasoning field with requested, applied and native, plus warnings in warnings. In streaming mode the body carries no warnings — the state travels in the X-Reasoning-Applied, X-Reasoning-Native and X-Reasoning-Warnings headers, the last one carrying comma-separated codes. On a synchronous response the same headers duplicate the body. A header is absent when there is nothing to report. When the model is substituted — a DISABLED redirect or a fallback to the backup model — the step is resolved against the model that ran the request, and the reasoning field and headers describe that model. reasoning.exclude is honored on every model, including ones without a reasoning declaration.

Model aliases

The model field accepts three values that resolve to the Bitrix24 account's default model (currently bitrix/bitrixgpt-5.5): auto, bitrix/free and an empty string.

The models bitrix/bitrixgpt-5 and bitrix/bitrixgpt-5-vl are marked as deprecated and work until July 31, 2026. After that date, requests to them are transparently redirected to bitrix/bitrixgpt-5.5 with the X-Model-Replacement header — see model lifecycle for details.

In addition, model accepts a model identifier without the provider prefix: bitrixgpt-5.5 resolves to bitrix/bitrixgpt-5.5. The short name must be an exact, case-sensitive match for an identifier from GET /v1/models with its first segment dropped. There is no partial matching: a request with bitrixgpt gets 404 ai_model_not_found, not the first model whose identifier contains that word. A request with a short name that matches several models available to your key also gets 404 — pass the full identifier. A model found by its short name is flagged in the response with the X-Model-Resolved header carrying its full identifier.

Examples

curl — personal key

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": "You are a sales expert. Classify leads by quality."},
      {"role": "user", "content": "Acme LLC, 50 users, budget 500,000 per month."}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/chat/completions \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a sales expert. Classify leads by quality."},
      {"role": "user", "content": "Acme LLC, 50 users, budget 500,000 per month."}
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/bitrixgpt-5.5',
    messages: [
      { role: 'system', content: 'You are a sales expert. Classify leads by quality.' },
      { role: 'user', content: 'Acme LLC, 50 users, budget 500,000 per month.' },
    ],
    temperature: 0.3,
    max_tokens: 300,
  }),
})

const data = await res.json()
console.log(data.choices[0].message.content)
console.log('Tokens:', data.usage.total_tokens)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/bitrixgpt-5.5',
    messages: [
      { role: 'system', content: 'You are a sales expert. Classify leads by quality.' },
      { role: 'user', content: 'Acme LLC, 50 users, budget 500,000 per month.' },
    ],
    temperature: 0.3,
    max_tokens: 300,
  }),
})

const data = await res.json()
console.log(data.choices[0].message.content)

Response fields

If a request with tools ends without a usable answer or function call, content may gain an English explanation and warnings may carry { code: "TOOL_CALL_MISSING", message: "..." } with the same text. Any existing text is kept, followed by a blank line and the explanation. HTTP 200, finish_reason: "stop" and usage are preserved; the explanation does not affect billing. It is not added for tool_choice: "none", structured output or reasoning-only turns ending with stop. In streams it is a separate delta.content event before the finish, without a warnings array.

Response example

{
  "id": "chatcmpl-a1a73c6eb3f180fd",
  "object": "chat.completion",
  "created": 1777289339,
  "model": "bitrix/bitrixgpt-5.5",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Quality: HIGH\n\nRationale:\n- Legal entity (LLC) — B2B client\n- Budget 500,000 per month — above average\n- Specific volume (50 users) — a deliberate need\n\nRecommendation: schedule a call within 24 hours."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 85,
    "total_tokens": 127
  }
}

Error response example

404 ai_model_not_found — model not found or the key has no access to it:

{
  "error": {
    "message": "Model \"anthropic/claude-imaginary-x\" not found or disabled.",
    "type": "invalid_request_error",
    "code": "ai_model_not_found"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

Automatic fallback to a backup model on a provider failure. If a paid model returns a 5xx error or times out, the synchronous request is retried with the default model. The X-Model-Fallback: <original modelId> header appears in the response. In streaming mode there is no such fallback — the client receives an error in the last event before data: [DONE].

Exhausted Cowork/Code quota: the response announces the limit instead of doing the work. This is a separate state, unrelated to X-Model-Fallback above: that header marks a model substitution, whereas here the subscription quota is exhausted. When a quota window is exhausted and a backup model is configured on the platform, the request returns 200, but no work is done for it: the tools, tool_choice and response_format fields are stripped, the request's own system messages have no effect, and the model states that the limit is reached and when it resets. The markers of this state are the X-Cowork-Fallback: true header and the COWORK_QUOTA_FALLBACK warning in the warnings array. In streaming mode there is no warning in the body; the state is visible from the header. Nothing is charged for such a response and no quota is spent. Do not expect tool_calls or schema-shaped JSON here: even with response_format in the request you get plain text. When no backup model is configured — or the configured one fails to answer — 402 cowork_quota_exhausted arrives instead. The response code does not tell those two cases apart, so always handle 402 on this endpoint.

The Bitrix24 account's monthly AI quota. On Bitrix24 accounts with quota control enabled, a request may return 402 ai_quota_exhausted. The reason field distinguishes three cases: breaker — the hourly over-quota spending breaker tripped, wallet_empty — the quota is exhausted and the account balance has no funds, wallet_off — over-quota spend is not available for the account. The resetAt field holds the moment when requests will pass again. For wallet_off it may be absent. In the wallet_empty case the response may 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. While usage stays within the quota, the endpoint's behavior is unchanged. Beyond the quota, if such spend is allowed for the account, requests are charged to the account's money balance at the model's base catalog price.

The processing budget for a synchronous 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. Reduce the request size or switch to streaming, where an idle timeout between events applies instead of a single budget for the whole call.

Request body size limit. For bitrix/* models the limit is 2 MiB for the whole body, images included. The platform downscales data: images in a body over the limit, and a body still over it gets 413 ai_payload_too_large. For models called with your own provider key, the limit is 30 MiB, enough for a single image of up to 20 MiB. How the platform downscales images — image analysis.

Passing content as an array. For text models, pass content as a string. An array with a single text element also works but is redundant. An array is required only for requests with images.

See also

• Streaming
• Guaranteed JSON response
• Function calling
• Image analysis
• Rate limits
• Model lifecycle
• List of models
• AI Router
• Assistant bot for deals and workflows