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
- You submit a recording with
POST /ai/transcriptionsand get back HTTP202with atranscription_id. - You poll
GET /ai/transcriptions/{transcription_id}untilstatusiscompletedorerror. - When the job completes, the response contains the full
text, the speaker-labeledutterancesand thebilled_amount.
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.X-AI-Api-Key header on every request. Both endpoints allow 120 requests per minute.

Submit a recording
Your Company ID. It must belong to the same company as the key, otherwise you get HTTP
403.A public
https:// URL of the audio file, up to 1,024 characters. The URL must stay reachable while the job runs.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.Set to
true to identify the languages spoken. Send false to turn detection off. Accepts true/false, 1/0 or "true"/"false".Set to
true to mark sounds such as laughter or music in the transcript. Off by default.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.202 Accepted
transcription_id before you start polling.
Get the result
Your AI Transcriber key. You can only read transcriptions that belong to your own company.
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
Every language detected, with the most spoken first. Only present when languages were detected.
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.The amount in USD charged for this job. Only present when
status is completed and the charge has gone through.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
erroraren’t charged. - Before TalkChief accepts a job, your wallet must hold the minimum balance. If it doesn’t, you get HTTP
402withError balance is below $5, please topup to proceed, and nothing is submitted or charged. - To check your balance, call
GET /ai/billing/balancewith the sameX-AI-Api-Keyheader. The response hascompany_idandbalance(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.
Related
Authentication
Get and rotate the AI Transcriber key.
CDR webhook
Get recording URLs for completed calls, ready to transcribe.

