openapi: 3.0.3 info: title: ConvertAudioToText Public API version: "1.0.0" description: >- Public transcription API for ConvertAudioToText. Submit an audio or video file (by upload or URL), poll for the result, and export the transcript as SRT, WebVTT, plain text, or JSON. Billing is pay-per-success: minutes are deducted only when a transcription completes successfully, and failed jobs are never charged. This document describes only the public developer surface served at /v1. The dashboard and admin APIs are not part of this contract and are not documented here. contact: name: ConvertAudioToText url: https://convertaudiototext.com termsOfService: https://convertaudiototext.com/api-disclosure servers: - url: https://convertaudiototext.com/v1 description: Public API (primary origin) - url: https://api.convertaudiototext.com/v1 description: Public API (direct backend origin) security: - apiKey: [] tags: - name: Transcription description: Create transcription jobs, read results, and export transcripts. paths: /transcribe: post: tags: [Transcription] summary: Create a transcription job description: >- Submit a media file for transcription, either by public URL or by file upload. Returns immediately with a job id; the transcript is produced asynchronously. Requires an API key with the `transcribe` scope. To upload a file, send `multipart/form-data` with `source=upload` and the media in the `file` field: `curl -X POST https://api.convertaudiototext.com/v1/transcribe -H "Authorization: Bearer ck_live_..." -F "source=upload" -F "file=@meeting.mp3" -F "language=en"` Accepted audio: mp3, wav, flac, m4a, ogg, opus, aac, wma, amr, aiff, aif, oga, caf, weba. Accepted video: mp4, mov, avi, mkv, webm, wmv, flv, 3gp, 3gpp, mpg, mpeg, m4v, mts, ts, m2ts, vob, mxf, ogv. The format is read from the file name's extension, and the file must contain an audio track. API plans accept files up to 10 GB, but one upload request is limited to 100 MB at our edge. For a larger file, put it at a URL the API can fetch (a public link or a presigned storage URL) and send it with `source=url`. operationId: createTranscription requestBody: required: true content: application/json: schema: type: object required: [source] properties: source: type: string enum: [url, upload] default: url input_url: type: string format: uri description: URL of the audio/video file (required when source is url). language: $ref: '#/components/schemas/LanguageCode' multipart/form-data: schema: type: object required: [source, file] properties: source: type: string enum: [upload] file: type: string format: binary description: >- The audio or video file. Up to 100 MB per request; see the operation description for formats and larger files. language: $ref: '#/components/schemas/LanguageCode' responses: '201': description: Job accepted for asynchronous processing. content: application/json: schema: $ref: '#/components/schemas/TranscribeAccepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '402': $ref: '#/components/responses/PaymentRequired' '422': $ref: '#/components/responses/UnprocessableSource' '429': $ref: '#/components/responses/TooManyRequests' get: tags: [Transcription] summary: List transcription jobs description: >- List the jobs on the account behind the API key, newest first. The response is one page: `total` is the number of jobs on the account, not the number returned, so page with `limit` and `offset` until `has_more` is false. operationId: listTranscriptions parameters: - name: limit in: query description: Jobs per page. Values outside 1..500 are clamped. schema: type: integer default: 50 minimum: 1 maximum: 500 - name: offset in: query description: Jobs to skip. Negative values are treated as 0. schema: type: integer default: 0 minimum: 0 responses: '200': description: A page of jobs. content: application/json: schema: type: object required: [jobs, total, limit, offset, has_more] properties: jobs: type: array items: $ref: '#/components/schemas/Job' total: type: integer description: >- Total jobs on the account, across every page. example: 345 limit: type: integer description: The page size actually applied, after clamping. example: 50 offset: type: integer description: The offset actually applied, after clamping. example: 0 has_more: type: boolean description: Whether jobs remain beyond this page. example: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /transcribe/{job_id}: get: tags: [Transcription] summary: Get a transcription result description: >- Read one job and its transcript. Poll this endpoint until `status` is `completed`. operationId: getTranscription parameters: - $ref: '#/components/parameters/JobId' responses: '200': description: The job and, once ready, its transcript. content: application/json: schema: $ref: '#/components/schemas/TranscriptResult' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /transcribe/{job_id}/srt: get: tags: [Transcription] summary: Export as SRT subtitles operationId: exportSrt parameters: - $ref: '#/components/parameters/JobId' - $ref: '#/components/parameters/ExportSpeakers' - $ref: '#/components/parameters/ExportCues' responses: '200': description: SRT subtitle file. content: application/x-subrip: schema: type: string text/plain: schema: type: string '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /transcribe/{job_id}/vtt: get: tags: [Transcription] summary: Export as WebVTT subtitles operationId: exportVtt parameters: - $ref: '#/components/parameters/JobId' - $ref: '#/components/parameters/ExportSpeakers' - $ref: '#/components/parameters/ExportCues' responses: '200': description: WebVTT subtitle file. content: text/vtt: schema: type: string '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /transcribe/{job_id}/txt: get: tags: [Transcription] summary: Export as plain text operationId: exportTxt parameters: - $ref: '#/components/parameters/JobId' - $ref: '#/components/parameters/ExportSpeakers' - $ref: '#/components/parameters/ExportTimestamps' - $ref: '#/components/parameters/ExportSummary' - $ref: '#/components/parameters/ExportGrouping' - $ref: '#/components/parameters/ExportEvery' responses: '200': description: Plain-text transcript. content: text/plain: schema: type: string '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /transcribe/{job_id}/json: get: tags: [Transcription] summary: Export as JSON operationId: exportJson parameters: - $ref: '#/components/parameters/JobId' responses: '200': description: Structured JSON transcript. content: application/json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: securitySchemes: apiKey: type: http scheme: bearer description: >- API key with the `ck_live_` (production) or `ck_test_` (test) prefix, sent as `Authorization: Bearer ck_live_...`. Create a key on the Developer or Business plan at https://convertaudiototext.com/dashboard/developers. Session JWTs are rejected on this API; only ck_live_/ck_test_ keys are accepted, and each must carry the `transcribe` scope. parameters: JobId: name: job_id in: path required: true schema: type: string format: uuid ExportSpeakers: name: speakers in: query required: false description: >- 1 labels each line with its speaker, 0 leaves speakers out. Lines nobody attributed never carry a speaker. schema: type: integer enum: [0, 1] default: 1 ExportTimestamps: name: timestamps in: query required: false description: >- 1 prints the start time before each line, 0 leaves it out. schema: type: integer enum: [0, 1] default: 1 ExportSummary: name: summary in: query required: false description: >- 1 includes the summary and the details footer, 0 leaves both out. schema: type: integer enum: [0, 1] default: 1 ExportCues: name: cues in: query required: false description: >- readable cuts each turn into subtitle cues of at most 2 lines of 42 characters and 7 seconds, closing at sentence ends; spoken keeps one cue per spoken turn. schema: type: string enum: [readable, spoken] default: readable ExportGrouping: name: grouping in: query required: false description: >- utterance keeps one block per line; paragraph merges a speaker's consecutive lines until a pause of 2 seconds or 600 characters. schema: type: string enum: [utterance, paragraph] default: utterance ExportEvery: name: every in: query required: false description: >- Seconds between timestamps. Long lines are split at a sentence end once the interval has passed (at the latest after 1.5 times the interval) and a speaker's short lines are joined, so each block starts with a timestamp. Overrides grouping. Leave out for one timestamp per line or paragraph. schema: type: integer enum: [15, 30, 60, 120, 300] responses: BadRequest: description: The request was malformed or missing required fields. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key. Session JWTs are rejected on this API. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key is valid but lacks the required `transcribe` scope. content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: >- The account has no transcription minutes remaining, or API access is not included on the current plan. content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableSource: description: >- The link was understood but can never produce a transcript, so no job was created and none will be. `code` names which case it is, and `error` carries a sentence that says what to do instead. Retrying the same link will always return this. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - spotify_chapter_link - spotify_music_link - podcast_no_public_source description: >- `spotify_chapter_link`: a /podcast-chapter/ clip rather than an episode. `spotify_music_link`: a /track/, /album/, /playlist/ or /artist/ link. `podcast_no_public_source`: the episode has no publicly fetchable audio (commonly a platform-exclusive show). NotFound: description: No job with that id belongs to this account. content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object properties: success: type: boolean example: false error: type: string description: Human-readable message. code: type: string description: >- Stable, machine-readable identifier for the refusal. Present on typed errors only; branch on this rather than on `error`, which is prose and gets reworded. request_id: type: string TranscribeAccepted: type: object properties: job_id: type: string format: uuid status: type: string example: queued message: type: string Job: type: object properties: id: type: string format: uuid user_id: type: string format: uuid status: type: string enum: [uploading, queued, processing, completed, failed] source_type: type: string enum: [upload, url] source_url: type: string description: The submitted link, for url jobs. filename: type: string description: The job's display name. audio_url: type: string description: A signed, short-lived link to the stored audio, when kept. language: type: string description: The requested language code, or `auto`. duration: type: number description: Length of the media in seconds. file_size: type: integer description: Size of the uploaded file in bytes. error_message: type: string description: Why the job failed, when status is failed. processing_started: type: string format: date-time processing_ended: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time TranscriptResult: type: object properties: job_id: type: string format: uuid status: type: string enum: [uploading, queued, processing, completed, failed] language: type: string description: The requested language code, or `auto`. filename: type: string source_type: type: string enum: [upload, url] file_size: type: integer duration: type: number description: Length of the media in seconds, once completed. created_at: type: string format: date-time updated_at: type: string format: date-time processing_started: type: string format: date-time processing_ended: type: string format: date-time error: type: string description: Why the job failed, when status is failed. summary_status: type: string transcript: type: object description: Present once status is completed. properties: overview: type: object properties: duration: type: number summary: type: string speaker_count: type: integer word_count: type: integer avg_confidence: type: number timeline: type: array items: type: object properties: speaker: type: integer speaker_label: type: string start: type: number end: type: number text: type: string avg_confidence: type: number word_count: type: integer topics: type: array items: type: object key_points: type: array items: type: string action_items: type: array items: type: object keywords: type: array items: type: string example: job_id: cc613d07-cefb-4ac6-a34c-dd7d119ca38b status: completed language: en duration: 231 transcript: overview: summary: "..." speaker_count: 6 word_count: 564 avg_confidence: 0.99 timeline: - speaker: 0 start: 0.0 end: 4.2 text: Good morning everyone. LanguageCode: type: string default: auto example: en description: >- The spoken language. Leave it out, or send `auto`, to detect it. 99 languages are supported, plus the regional codes en-GB and en-AU. Other regional tags such as en-US or pt-BR resolve to their base language. Supported codes: af, am, ar, as, az, ba, be, bg, bn, bo, br, bs, ca, cs, cy, da, de, el, en, en-AU, en-GB, es, et, eu, fa, fi, fo, fr, gl, gu, ha, haw, he, hi, hr, ht, hu, hy, id, is, it, ja, jw, ka, kk, km, kn, ko, la, lb, ln, lo, lt, lv, mg, mi, mk, ml, mn, mr, ms, mt, my, ne, nl, nn, no, oc, pa, pl, ps, pt, ro, ru, sa, sd, si, sk, sl, sn, so, sq, sr, su, sv, sw, ta, te, tg, th, tk, tl, tr, tt, uk, ur, uz, vi, yi, yo, zh.