success verdict and
the fields your agent extracts.
It runs in the background. You get an id straight away, then read the
recording with GET until it finishes, or let a webhook tell you.
Base URL https://sandbox.voice.miraiminds.co. Every request carries
Authorization: Bearer sk_live_…, your workspace API key. A recording belongs
to the workspace whose key sent it.
Transcript only, or with insight
Insight uses the agent’s analysis settings: its
prompt, success_criteria and output_schema. So the result has the same
shape as that agent’s live calls, and one agent can analyse both. The agent
must have analysis turned on. If it doesn’t, the request is refused with
400 analysis_disabled. Turn analysis on, or leave out agent_id to get only
the transcript.
A recording has no call variables, so any {{variables}} in the agent’s
analysis prompt or success_criteria are left empty.
How it works
- Queued. The recording waits for a free slot. Uploads run with their own
capacity, separate from live calls, so a large batch never slows your
agents’ calls down. While it waits,
queue_positionsays about how many recordings are ahead of it. - Transcribing. A long recording is cut into parts at quiet moments, the
parts are transcribed a few at a time, and the transcript is joined back
together by timestamp.
progresscounts the parts. - Analyzing. With an
agent_id, the transcript is analysed with that agent’s analysis settings. - Completed or failed. A failure says which stage it happened in.
How long it takes
These are estimates, not measurements: about 1 to 3 minutes for a 5-minute
recording, and about 8 to 20 minutes for a 60-minute one. It takes longer when
other uploads are queued ahead of yours. Poll every 10 to 30 seconds, or use a
webhook.
Send a recording
- As
multipart/form-datawith the file infile. Up to 45 MB. - As
application/jsonwith anhttpsrecording_urlthat we fetch. Up to 200 MB.
Upload a file
Any other form field is refused with
400 invalid_request.
- cURL
- Python
- Node.js
Send a link
The same fields as JSON, withrecording_url in place of the file and
metadata as an object.
The link must point to a public address on the default
https port (443),
with no user name or password in it. Redirects are followed to https
addresses only, at most 5 of them, and each one is checked the same way. If
the link is pre-signed, give it at least 15 minutes to live.
- cURL
- Python
- Node.js
Response
202 Accepted, with a Location header and the recording:
202 Accepted
Idempotency
Send anIdempotency-Key header (up to 255 characters) with a value from your
own records, such as your call ID. A request with a key your workspace has
already used returns the recording that key created. It makes no second job
and no second charge, so a request that timed out is safe to send again.
Get a recording
status is completed or failed.
- cURL
- Python
- Node.js
200 OK
The recording object
transcript, analysis and delivery appear only when you read one
recording. The create response and the list carry every
other field.
Statuses
Statuses only move forward, except that retrying a failed analysis
moves the recording back to
queued, then analyzing. started_at, transcribed_at and
completed_at show where the time went.
Speakers
A two-channel file whose channels are identical, or with one channel silent,
is treated as one channel. With
unlabelled, the analysis is told that the
lines are not labelled, so it does not credit a statement to a particular
person unless the words make it clear.
Get the result by webhook
When a recording finishes, we send one signedPOST to its webhook_url, and
the same event to your webhook subscriptions. It
is the same event, with the same shape and the same
signature, as a live call’s analysis:
data.call.source is upload, and data.call.id is the recording’s id.
That is how you tell a recording’s result from a live call’s.
call.analysis.completed
GET /v2/recordings/{id}. Treat the event as additive:
new fields can appear, so ignore what you don’t recognise. Deliveries are
retried like a call’s, and delivery on the recording
says how it went.
List recordings
transcript, analysis
and delivery.
200 OK
Retry a failed analysis
If a recording failed in theanalysis stage, run the analysis again:
analysis.generation you read. The answer is 202 with the
recording, now queued: it waits for a free slot again, then moves to
analyzing. The retry uses the stored transcript, so the
recording is not transcribed again, and transcription is not charged again.
Insight is charged once, when an analysis completes, however many times you
retry. If the analysis has not failed, or someone retried it already, the
answer is 409 conflict: read the recording again first.
A recording that failed in the transcription stage cannot be retried. Send
it again.
Pricing
- Each stage is billed per second of audio, rounded up to the next second with a one-second minimum, and the amount is rounded up to the paisa.
- Each stage is charged once, only when it succeeds. A failed stage is free.
- Retrying an analysis never charges it twice.
- When you send a recording, your wallet must hold enough for the whole
recording: ₹0.30 a minute for a transcript only, ₹0.50 a minute with
insight. If it doesn’t, you get
402 insufficient_balance, and the message says how much is needed. Nothing is held: the charges come when the stages finish.
recording, the recording’s id as reference, and descriptions
such as “Recording transcription · 5m13s of audio” and “Recording insight ·
5m13s of audio”.
cost on the recording:
Limits
Errors
When you send a recording
Why a recording failed
A failed stage is never charged. Branch on
error.code, allow for codes not
listed here, and show error.message if you need a sentence for a person.
Privacy and your data
- The audio is deleted once the transcript is stored.
- The transcript and analysis stay with the recording, so that
GET /v2/recordings/{id}can return them. - Recordings often hold personal details of people who are not your customers yet. Make sure the people in a recording were told it may be recorded and analysed, as your local rules require.
Related
- Call analysis: set up the summary, success criteria and fields an agent extracts.
- Webhooks: verify signatures and handle retries.
- Transcriptions: transcripts only, with vocabulary and word timings.