Skip to main content
The AI Transcription API turns a call recording into text. Each part of the transcript is labeled with its speaker and timing. You send the URL of the recording and get back a transcription ID. Then you poll that ID until the transcript is ready.
This API is separate from automatic AI transcription, the add-on that transcribes your TalkChief calls for you. The API transcribes any recording you send it, and each job is billed from your wallet.

How it works

  1. You submit a recording with POST /ai/transcriptions and get back HTTP 202 with a transcription_id.
  2. You poll GET /ai/transcriptions/{transcription_id} until status is completed or error.
  3. When the job completes, the response contains the full text, the speaker-labeled utterances and the billed_amount.
There’s no webhook or callback for transcriptions. Poll for the result, or send wait to hold the submit request open for up to about 50 seconds.

Before you start

1

Get the AI Transcriber key

As a company admin, go to Integrations → API → Overview & keys. On the AI Transcriber panel, click Generate key if you don’t have one yet, then click Copy.
2

Copy your Company ID

The Company ID appears at the top of the same page. Send it as company_id on every submit request.
3

Top up your wallet

Your wallet must hold at least the minimum balance before you submit. If it doesn’t, the request fails with HTTP 402.
Send the key in the X-AI-Api-Key header on every request. Both endpoints allow 120 requests per minute.
Integrations > API > AI Transcription reference with pricing, the parameter table and example submit, poll and wait requests

Submit a recording

string
required
Your AI Transcriber key.
integer
required
Your Company ID. It must belong to the same company as the key, otherwise you get HTTP 403.
string
required
A public https:// URL of the audio file, up to 1,024 characters. The URL must stay reachable while the job runs.
string
A language hint such as en, ar or he, up to 16 characters. If you leave it out, the language is detected automatically. When detection finds a language, it replaces your hint in the result.
boolean
default:"true"
Set to true to identify the languages spoken. Send false to turn detection off. Accepts true/false, 1/0 or "true"/"false".
boolean
default:"false"
Set to true to mark sounds such as laughter or music in the transcript. Off by default.
boolean
Send 1 to wait for the result in a single request, for up to about 50 seconds. You can send it in the body or as a query parameter (?wait=1). If the job is still running when time is up, you get back the normal pending response. Keep polling that ID.
Language detection and audio event detection don’t cost extra.
202 Accepted
Save transcription_id before you start polling.
Never submit the same recording again because a request timed out. Each submission is a new job that’s billed on its own. Poll the ID you already have instead.

Get the result

string
required
The transcription_id from the submit response.
string
required
Your AI Transcriber key. You can only read transcriptions that belong to your own company.
Poll every 3 to 5 seconds until status is completed or error. Polling is free. Once a transcript is complete it’s stored, so you can fetch it again any time.
200 OK

Response fields

boolean
false only when status is error.
string
The job ID (a UUID).
string
One of queued, processing, completed or error.
integer | null
Length of the audio in milliseconds, once it’s known.
string | null
The main language detected. If nothing was detected, this is your language hint.
string[]
Every language detected, with the most spoken first. Only present when languages were detected.
string
The full transcript. Only present when status is completed.
object[]
The transcript split by speaker. Only present when status is completed. Each item has speaker, start_ms, end_ms and text. Speaker labels tell voices apart within one recording. They don’t say which speaker is the agent or the customer.
number
The amount in USD charged for this job. Only present when status is completed and the charge has gone through.
string
Only present when status is error. For example: “The recording could not be processed. Check that the URL is reachable and points to a supported audio file.”

Billing

  • Each completed transcription is charged to your company wallet per minute of audio. The current rate is shown in Integrations → API → AI Transcription.
  • Every job is billed for at least one minute. After the first minute, billing is per second, so a 26-second recording is billed as 60 seconds and a 73-second recording as 73 seconds.
  • Jobs that end in error aren’t charged.
  • Before TalkChief accepts a job, your wallet must hold the minimum balance. If it doesn’t, you get HTTP 402 with Error balance is below $5, please topup to proceed, and nothing is submitted or charged.
  • To check your balance, call GET /ai/billing/balance with the same X-AI-Api-Key header. The response has company_id and balance (a string with 5 decimal places).

Errors

A job that fails after it was accepted still returns HTTP 200 when you poll. The response has success: false, status: "error" and an error message.

Authentication

Get and rotate the AI Transcriber key.

CDR webhook

Get recording URLs for completed calls, ready to transcribe.