Transcribe audio

POST /v1/audio/transcriptions

Converts an audio file to text via BitrixGPT 5.6 Transcribe (see "Models" below) — no BYOK required. Transcription counts toward the Bitrix24 account's AI quota by audio duration: within the plan's quota nothing is charged to the balance; above the quota, usage is charged to the account's money balance at the model's base price. Accepts the file via multipart/form-data. The request and response format is compatible with POST /v1/audio/transcriptions from the OpenAI API. Transcription is not available on the international platform yet: every request, including the examples below, is rejected with 404 ai_model_not_found.

The response comes in raw OpenAI format.

The {success, data} wrapper used by the other Vibecode endpoints — /v1/deals, /v1/tasks and others — is not returned 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.

Models

Whisper Large v3 Turbo is being retired. From 16 November 2026, requests with bitrix/deepdml/faster-whisper-large-v3-turbo-ct2 and requests without model are served by BitrixGPT 5.6 Transcribe. The old ID remains accepted and remains the default when model is omitted. For new integrations, explicitly set model=bitrix/bitrixgpt-5.6-transcribe.

When the replacement handles a request, the response carries X-Model-Fallback: bitrix/deepdml/faster-whisper-large-v3-turbo-ct2, X-Model-Replacement: bitrix/bitrixgpt-5.6-transcribe and X-Model-Fallback-Reason: model_disabled. The replacement's language support, parameter handling and billing apply. See model lifecycle.

The X-Model-Fallback, X-Model-Replacement and X-Model-Fallback-Reason headers are not on the CORS exposure list, so a browser fetch cannot read them — read them server-side or in the developer tools.

The X-Ignored-Params header is informational: the response body and error codes do not change. It is not on the CORS exposure list, so a browser fetch cannot read it — read it server-side or in the developer tools.

Request fields (form-data)

Examples

curl — personal key

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

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/audio/transcriptions \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -F "file=@call-recording.mp3" \
  -F "model=bitrix/bitrixgpt-5.6-transcribe" \
  -F "response_format=json"

JavaScript — personal key

const formData = new FormData()
formData.append('file', audioFile)  // File or Blob object
formData.append('model', 'bitrix/bitrixgpt-5.6-transcribe')
formData.append('response_format', 'json')

const res = await fetch('https://vibecode.bitrix24.com/v1/audio/transcriptions', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  body: formData,
})

const result = await res.json()
console.log('Recognized text:', result.text)

JavaScript — OAuth application

const formData = new FormData()
formData.append('file', audioFile)
formData.append('model', 'bitrix/bitrixgpt-5.6-transcribe')

const res = await fetch('https://vibecode.bitrix24.com/v1/audio/transcriptions', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
  body: formData,
})

const result = await res.json()
console.log('Text:', result.text)

Response fields

The response structure depends on response_format. The json format (default) is the most compact; verbose_json adds timings.

`response_format: json`

`response_format: text`

The response is a plain string with the recognized text, without a JSON wrapper.

`response_format: verbose_json`

`response_format: srt` / `vtt`

The response is subtitles in SubRip Text or WebVTT format.

Response example

response_format: json:

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

response_format: verbose_json:

{
  "task": "transcribe",
  "language": "en",
  "duration": 8.42,
  "text": "Hello, this is Acme LLC. We want a CRM for 50 users, budget up to 500,000 per month.",
  "usage": null,
  "words": [],
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.0,
      "end": 3.2,
      "text": "Hello, this is Acme LLC.",
      "tokens": [50365, 2425, 11, 341, 307],
      "temperature": 0.0,
      "avg_logprob": -0.38,
      "compression_ratio": 1.12,
      "no_speech_prob": 0.02,
      "words": [],
      "emotion": null
    },
    {
      "id": 1,
      "seek": 320,
      "start": 3.2,
      "end": 8.42,
      "text": "We want a CRM for 50 users, budget up to 500,000 per month.",
      "tokens": [50414, 1003, 13767, 295, 1500],
      "temperature": 0.0,
      "avg_logprob": -0.41,
      "compression_ratio": 1.20,
      "no_speech_prob": 0.01,
      "words": [],
      "emotion": null
    }
  ]
}

Error response example

400 no_file — the file field was not provided:

{
  "error": {
    "message": "Audio file is required. Send as multipart/form-data with field \"file\".",
    "type": "invalid_request_error",
    "code": "no_file"
  }
}

Errors

The full list of common API errors — Errors.

Idempotency

Send the optional Idempotency-Key header to repeat the transcription of the same file safely. If the response to the first request was lost (a dropped connection, a timeout), a repeat with the same key and the same file transcribes the audio again but charges nothing a second time: neither the Bitrix24 account's AI quota, nor money from the balance, nor the Cowork subscription quota. The response of such a repeat carries the Idempotent-Replayed: true header.

• The key is a string of 1–255 characters from [A-Za-z0-9_.:-]. For a recording you split into parts, use the form <recording id>:<track id>:<part number>, for example rec-8f2c:mic:12.
• The key is scoped to the Bitrix24 account and the user the call is billed to, or to the API key when there is no user. A new API key of the same user does not break the repeat.
• A repeat is free for 72 hours after a successful charged call. Later, the same key is processed as a new call and charged.
• A free repeat goes through even when the quota is exhausted: this file has already been paid for.
• At most three free repeats are allowed per file. The fourth and later repeats with the same key are processed and charged as a regular call, with all quota and balance checks.
• If the first call ended with an error, the key is released, and a repeat is processed as a new charged call.
• If the first call charged nothing — for example, it ran on your own provider key — a repeat is also processed as a regular call, without the Idempotent-Replayed header.
• The platform stores neither the transcript nor the audio — only fingerprints of the key and the file. So the response to a repeat is a fresh transcription of the same file.
• Without the Idempotency-Key header the behaviour is unchanged.

Refusals related to the key — 400 invalid_idempotency_key, 409 idempotency_in_progress and 422 idempotency_key_reused — are described in Errors.

Known specifics

Transcribe detects the language automatically. It supports the 25 European languages listed above, compared with about 99 for Whisper. It does not separate speakers. language, prompt, hotwords, temperature and vad_filter are validated but do not affect recognition; sent field names are reported in X-Ignored-Params. Hints that influenced Whisper no longer do so when Transcribe serves the request. Check your recordings and required languages before migrating.

Within the quota — no charges, above the quota — the model's base price. BitrixGPT 5.6 Transcribe runs on Bitrix24 infrastructure. All its formats, including platform-rendered text, srt and vtt, are priced by audio duration and count toward the Bitrix24 account's monthly AI quota. As long as usage stays within the plan's quota, nothing is charged to the account balance. Above the quota, usage is charged to the account's money balance at the model's base catalog price. On accounts with quota control enabled, a request may return 402 ai_quota_exhausted when the monthly limit is exhausted. The reason field distinguishes three cases: breaker — the hourly over-quota spending breaker fired, 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 is the moment when requests will start passing 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.

A Cowork subscription key is metered separately. A call made with a key carrying the vibe:cowork scope does not count toward the account's AI quota. If the subscription is active and a platform administrator has set a per-minute or per-call price for a transcription model available to you, the call draws on the subscription quota: when the window is exhausted the endpoint responds with 402 and the code cowork_quota_exhausted, a Retry-After header and the fields window (5h, week or month), resetAt and nextTier. Until a price is set, transcription with such a key is not metered. With Whisper the text, srt and vtt formats do not report a duration, so they are billed at the per-call price; with BitrixGPT 5.6 Transcribe they are built by the platform and billed by duration.

Disabling Cowork at the platform level controls product features, but does not change AI billing for an already-issued key. With an active subscription, transcription continues to use its quota, just like chat; disabling the product does not move this usage to the account wallet. Without an active subscription, transcription still does not use the subscription quota, and standard billing applies as before.

Size limit — 25 MB. A file over the limit is rejected outright — 413 request_too_large, nothing is charged. For long recordings, split the file into parts of up to 25 MB and stitch the results on the client side. One hour of mp3 at 128 kbit/s is about 60 MB — you will have to split it.

Request timeout — 15 minutes. Transcription takes roughly 5-15% of the audio length. A 5-minute file (5-7 MB mp3) transcribes in 15-45 seconds. On a timeout, 503 ai_provider_timeout is returned.

See also

• Speech recognition
• Create a chat completion
• AI Router