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 in 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.

What a particular model supports is shown by the reasoning field in GET /v1/models. 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, budgetTokens — reasoning token-budget support. 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 — 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, direction fields. The none step is never chosen by rounding — reasoning can only be disabled explicitly. If nothing exists below, the nearest step above is taken. Asking for none on a model where it 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.

Without the parameter in the request the model's behavior does not change — nothing is added to the model call, and the response's reasoning field merely reports the default step.

In the response: the reasoning field with requested, applied, native and warnings in warnings. In streaming mode the body carries no warnings — the state travels in the X-Reasoning-Applied, X-Reasoning-Native, X-Reasoning-Warnings headers, with codes comma-separated. 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 one without a 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, a partial modelId is matched against the catalog by substring: if you pass gpt-4o-mini, the platform picks a model available to your key whose identifier contains that substring.

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 thousand 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 thousand 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 thousand 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 thousand per month.' },
    ],
    temperature: 0.3,
    max_tokens: 300,
  }),
})

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

Response fields

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 thousand 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].

An 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 read them as optional. The hint field in this response is a string. 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 — 30 MiB. This is enough to pass a single image of up to 20 MiB: after base64 encoding it takes about 27 MiB.

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