#Transcribe audio

POST /v1/audio/transcriptions

Converts an audio file to text via Whisper Large v3 Turbo — no BYOK required. The 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 the 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.

The response comes in raw OpenAI format.

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

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.

#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 "language=en" \
  -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 "language=en" \
  -F "response_format=json"

#JavaScript — personal key

const formData = new FormData()
formData.append('file', audioFile)  // File or Blob object
formData.append('language', 'en')
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('language', 'en')

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 — with 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 thousand 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 thousand 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 thousand 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.

#Known specifics

Hints improve accuracy on rare terms. The prompt field sets the context — the conversation topic, style, correct spelling of terms. The hotwords field lists comma-separated special words the decoder gives higher priority to. The difference on the phrase "discussing the NeuralDeep integration with Kimi and the RAG approach":

Within the quota — no charges, above the quota — the model's base price. Whisper runs on Bitrix24 infrastructure. Transcription is priced by audio duration and counts 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 read them as optional. The hint field in this response is a string.

Size limit — 25 MB. For long recordings, split the file into parts 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 cut 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