Create transcript

Starts a transcription and returns it right away with `status: "processing"`. **Audio**: `url` (any public http(s) address) **or** `uploadId` (from `POST /v1/uploads`), exactly one of the two. **Result**: poll `GET /v1/transcripts/{id}` until `status` is `done` or `failed`, or pass `webhookUrl` to be called when it finishes. **Billing**: charged on completion, from the real audio duration (max 10 hours). Failed transcripts are never charged. `reuseIfIdentical` (on an upload created with `sha256`) returns the transcript the account already has for that exact audio instead of charging twice. **Retries**: send an `Idempotency-Key` header (up to 64 chars); the same key returns the same transcript instead of creating and charging a second one. The same key with a different body is a `409`. An `uploadId` changes on every retry, so key the request by your first `uploadId`, never by your own media id. **Trial limit**: until the first top-up, at most 2 transcriptions run at once; a third gets `429 concurrency_limit`.

Starts a transcription and returns it right away with status: "processing".

Audio: url (any public http(s) address) or uploadId (from POST /v1/uploads), exactly one of the two.

Result: poll GET /v1/transcripts/{id} until status is done or failed, or pass webhookUrl to be called when it finishes.

Billing: charged on completion, from the real audio duration (max 10 hours). Failed transcripts are never charged. reuseIfIdentical (on an upload created with sha256) returns the transcript the account already has for that exact audio instead of charging twice.

Retries: send an Idempotency-Key header (up to 64 chars); the same key returns the same transcript instead of creating and charging a second one. The same key with a different body is a 409. An uploadId changes on every retry, so key the request by your first uploadId, never by your own media id.

Trial limit: until the first top-up, at most 2 transcriptions run at once; a third gets 429 concurrency_limit.

Authorization

bearerAuth

AuthorizationBearer <token>

API key (tk_...)

In: header

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

url?string

Public http(s) URL of the audio. Send this or uploadId, never both

Length1 <= length <= 2048

uploadId?string

Id returned by POST /v1/uploads. Send this or url, never both

Lengthlength <= 36

language?string

Language code ("pt", "en", …). Omit to detect it automatically

Lengthlength <= 16

speakers?||

Separate speakers: true (count unknown), 3 (exactly 3) or "2-5" (between 2 and 5). Omit for a single block of text. Changes the hourly rate

webhookUrl?string

Public http(s) URL that receives a POST when this transcript reaches done or failed. The body is the transcript without text and words; fetch those with GET /v1/transcripts/{id}. Use it instead of polling.

Deliveries are signed: Transcrevo-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body>, keyed with the lowercase hex SHA-256 of the API key that created the transcript. Recompute over the raw body, compare in constant time, reject old t. Respond 2xx to acknowledge; anything else is retried with backoff for about 9 hours

Length1 <= length <= 2048

glossary?

Corrections that apply to this audio only, as {"what the engine hears": "what to write"} (for example {"gatu": "Gato"}). Proper names and jargon are what this is for. Applied after transcription, on top of the built-in corrections

externalId?string

Your own id for this audio (a media id, a row id, a ticket number). Returned unchanged on every read and inside the webhook, and accepted as a filter on GET /v1/transcripts, so a delivery is recognizable without a lookup table on your side. Not unique: the same audio can be transcribed twice with different options

Length1 <= length <= 128

metadata?

Key/value pairs carried with the transcript and returned unchanged on every read and in the webhook. Never interpreted by the API. Up to 20 pairs, keys up to 40 chars, values up to 500

retentionDays?integer

Erase the CONTENT of this transcript this many days after it is created: text, words and the stored audio go, and the transcript then reads like a deleted one. The usage record stays, because the invoice is built from it. Omit to follow the account default. There is no zero here: content has to survive long enough for you to fetch it

Range1 <= value <= 365

reuseIfIdentical?boolean

Return the transcript this account already has for this exact audio, instead of transcribing (and charging) again. Requires an upload created with sha256, which is what identifies the content. Responds 200 with the existing transcript instead of 201

Response Body

`application/json`

curl -X POST "https://example.com/v1/transcripts" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "id": "string",    "status": "processing",    "text": "string",    "words": [      {        "start": 0,        "end": 0,        "text": "string",        "speaker": "string"      }    ],    "utterances": [      {        "start": 0,        "end": 0,        "text": "string",        "speaker": "string",        "overlap": true      }    ],    "diarizationSegments": [      {        "start": 0,        "end": 0,        "speakers": [          "string"        ]      }    ],    "error": {      "code": "audio_too_long",      "message": "string"    },    "language": "string",    "durationSeconds": 0,    "speakerCount": 0,    "cost": 0,    "currency": "USD",    "model": "string",    "url": "string",    "retentionDays": 0,    "externalId": "string",    "metadata": {},    "createdAt": "string"  }}

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

402application/json

404application/json

409application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`