{ "openapi": "3.1.0", "info": { "title": "AirCaps API", "version": "1.0.0", "description": "Speech-to-text for English. A5S Async v1 (REST) and A5S v2 Streaming (WebSocket)." }, "servers": [ { "url": "https://api.aircaps.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Transcripts" }, { "name": "Files" }, { "name": "Account" } ], "paths": { "/v1/transcripts": { "post": { "summary": "Create a transcript", "description": "Start transcribing audio with A5S Async v1. The job runs asynchronously: poll [Get a transcript](/api-reference/get-transcript) or pass `webhook_url`.", "responses": { "201": { "description": "Created. A retried request with the same `Idempotency-Key` returns the original transcript with `200`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcript" }, "example": { "id": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7", "object": "transcript", "status": "queued", "created_at": "2026-10-06T18:01:02.123Z", "started_at": null, "completed_at": null, "audio_url": null, "file_id": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "language_code": "en", "model": "a5s-async-v1", "audio_duration": null, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status_code": null, "error": null } } }, "headers": { "Location": { "description": "URL of the new transcript.", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`, `unsupported_language`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "unsupported_language", "message": "language 'de' is not supported; only English (\"en\", \"en-US\", ...) is available today. Multilingual support is planned.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`, `usage_limit_reached`, `model_access_denied`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "model_access_denied", "message": "This account does not have access to A5S Async v1. To get access, talk to sales at https://research.aircaps.com/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "409": { "description": "Idempotency key reused with a different body. Codes: `idempotency_conflict`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_conflict", "message": "Idempotency-Key was used with a different request", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "429": { "description": "Rate or queue limit reached. Codes: `rate_limited`, `queue_full`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "too many requests; retry after the Retry-After interval", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Transcripts" ], "operationId": "createTranscript", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 255 characters. Makes retries safe: the same key and body return the original job.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranscriptRequest" }, "example": { "model": "a5s-async-v1", "audio_url": "https://example.com/meeting.mp3", "language_code": "en", "webhook_url": "https://example.com/hooks/aircaps", "metadata": { "meeting_id": 42 } } } } } }, "get": { "summary": "List transcripts", "description": "Your transcripts, newest first. Items omit the result fields (`text`, `speakers`, `utterances`, `words`).", "responses": { "200": { "description": "A page of transcripts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptList" }, "example": { "object": "list", "data": [ { "id": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7", "object": "transcript", "status": "completed", "created_at": "2026-10-06T18:01:02.123Z", "started_at": "2026-10-06T18:01:02.456Z", "completed_at": "2026-10-06T18:01:31.789Z", "audio_url": null, "file_id": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "language_code": "en", "model": "a5s-async-v1", "audio_duration": 3600.512, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status_code": 200, "error": null } ], "has_more": true, "next_before": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`, `unsupported_language`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "unsupported_language", "message": "language 'de' is not supported; only English (\"en\", \"en-US\", ...) is available today. Multilingual support is planned.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "account_disabled", "message": "this account is disabled", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Transcripts" ], "operationId": "listTranscripts", "parameters": [ { "name": "limit", "in": "query", "description": "Number of transcripts to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "description": "Only transcripts with this status.", "schema": { "type": "string", "enum": [ "queued", "processing", "completed", "error" ] } }, { "name": "before", "in": "query", "description": "Pagination cursor: the `next_before` of the previous page.", "schema": { "type": "string" } } ] } }, "/v1/transcripts/{id}": { "get": { "summary": "Get a transcript", "description": "Status and, once `completed`, the result.", "responses": { "200": { "description": "The transcript.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcript" }, "example": { "id": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7", "object": "transcript", "status": "completed", "created_at": "2026-10-06T18:01:02.123Z", "started_at": "2026-10-06T18:01:02.456Z", "completed_at": "2026-10-06T18:01:31.789Z", "audio_url": null, "file_id": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "language_code": "en", "model": "a5s-async-v1", "audio_duration": 3600.512, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status_code": 200, "error": null, "text": "hey good afternoon everybody ...", "speakers": [ { "id": "speaker_0", "speaking_time": 1402.11 }, { "id": "speaker_1", "speaking_time": 988.4 } ], "utterances": [ { "speaker": "speaker_0", "start": 0.48, "end": 6.12, "text": "hey good afternoon everybody ...", "words": [ { "text": "hey", "start": 0.48, "end": 0.71, "speaker": "speaker_0" } ] } ], "words": [ { "text": "hey", "start": 0.48, "end": 0.71, "speaker": "speaker_0" } ] } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "account_disabled", "message": "this account is disabled", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "404": { "description": "Not found. Codes: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "transcript not found", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Transcripts" ], "operationId": "getTranscript", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transcript ID.", "schema": { "type": "string", "example": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7" } } ] }, "delete": { "summary": "Delete a transcript", "description": "Cancels a `queued` or `processing` job (its `error.code` becomes `canceled`), or deletes a finished transcript and its stored data. Afterwards the ID returns `404`.", "responses": { "200": { "description": "The transcript as it was, with `deleted: true`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TranscriptSummary" }, { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } ] }, "example": { "id": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7", "object": "transcript", "status": "completed", "created_at": "2026-10-06T18:01:02.123Z", "started_at": "2026-10-06T18:01:02.456Z", "completed_at": "2026-10-06T18:01:31.789Z", "audio_url": null, "file_id": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "language_code": "en", "model": "a5s-async-v1", "audio_duration": 3600.512, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status_code": 200, "error": null, "deleted": true } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "account_disabled", "message": "this account is disabled", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "404": { "description": "Not found. Codes: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "transcript not found", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Transcripts" ], "operationId": "deleteTranscript", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transcript ID.", "schema": { "type": "string", "example": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7" } } ] } }, "/v1/transcripts/{id}/subtitles": { "get": { "summary": "Get subtitles", "description": "SRT or WebVTT captions for a completed transcript, with the speaker in each cue.", "responses": { "200": { "description": "Subtitles as text.", "content": { "application/x-subrip": { "schema": { "type": "string" }, "example": "1\n00:00:00,480 --> 00:00:02,310\n[speaker_0] hey good afternoon everybody\n" }, "text/vtt": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "404": { "description": "Not found. Codes: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "transcript not found", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "409": { "description": "The transcript is not completed. Codes: `transcript_not_ready`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "transcript_not_ready", "message": "transcript is processing", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Transcripts" ], "operationId": "getSubtitles", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transcript ID.", "schema": { "type": "string", "example": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "srt", "vtt" ], "default": "srt" } }, { "name": "chars_per_caption", "in": "query", "description": "Maximum characters per caption.", "schema": { "type": "integer", "minimum": 10, "maximum": 200, "default": 42 } } ] } }, "/v1/files/upload-url": { "post": { "summary": "Create an upload URL", "description": "Get a presigned URL to upload a file of up to 5 GB straight to storage. `PUT` the raw bytes to `upload_url` within an hour, then use `id` as `file_id`.", "responses": { "201": { "description": "Upload URL created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrl" }, "example": { "id": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "object": "file", "upload_url": "https://storage.example/...", "method": "PUT", "upload_expires_at": "2026-10-06T19:01:02Z", "expires_at": "2026-10-07T18:01:02Z", "max_size_bytes": 5368709120 } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`, `usage_limit_reached`, `model_access_denied`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "model_access_denied", "message": "This account does not have access to A5S Async v1. To get access, talk to sales at https://research.aircaps.com/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "429": { "description": "Rate or queue limit reached. Codes: `rate_limited`, `queue_full`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "too many requests; retry after the Retry-After interval", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Files" ], "operationId": "createUploadUrl" } }, "/v1/files": { "post": { "summary": "Upload a file", "description": "Upload up to 1 GB in the request body. For larger files, use an upload URL.", "responses": { "201": { "description": "File stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" }, "example": { "id": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "object": "file", "size_bytes": 115200044, "created_at": "2026-10-06T18:01:02Z", "expires_at": "2026-10-07T18:01:02Z" } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`, `unsupported_language`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "unsupported_language", "message": "language 'de' is not supported; only English (\"en\", \"en-US\", ...) is available today. Multilingual support is planned.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`, `usage_limit_reached`, `model_access_denied`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "model_access_denied", "message": "This account does not have access to A5S Async v1. To get access, talk to sales at https://research.aircaps.com/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "413": { "description": "Larger than 1 GB. Codes: `file_too_large`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "direct uploads are limited to 1 GB; use /v1/files/upload-url", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "429": { "description": "Rate or queue limit reached. Codes: `rate_limited`, `queue_full`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "too many requests; retry after the Retry-After interval", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Files" ], "operationId": "uploadFile", "requestBody": { "required": true, "description": "The raw file bytes (any audio or video format).", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/models": { "get": { "summary": "List models", "description": "The available models. No authentication needed.", "responses": { "200": { "description": "The models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" }, "example": { "object": "list", "data": [ { "id": "a5s-async-v1", "object": "model", "name": "A5S Async v1", "type": "async", "languages": [ "en" ], "endpoint": "/v1/transcripts" }, { "id": "a5s-v2-streaming", "object": "model", "name": "A5S v2 Streaming", "type": "streaming", "languages": [ "en" ], "endpoint": "/v1/realtime" } ] } } } } }, "tags": [ "Account" ], "operationId": "listModels", "security": [] } }, "/v1/account": { "get": { "summary": "Get account", "description": "Your usage limit, per-model access (`enabled`) and limits. For higher limits or model access, [talk to sales](https://research.aircaps.com/contact).", "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "id": "7f0c2b1e-0000-4000-8000-000000000001", "object": "account", "email": "dev@example.com", "display_name": "Dev Example", "created_at": "2026-09-30T12:00:00Z", "status": "active", "tier": "standard", "usage_limit": { "limit_seconds": 18000, "used_seconds": 2950.4, "reserved_seconds": 0, "remaining_seconds": 15049.6 }, "models": { "a5s-async-v1": { "name": "A5S Async v1", "type": "async", "enabled": true, "max_concurrent_jobs": 5, "max_queued_jobs": 2000, "max_requests_per_minute": 600, "max_audio_duration_seconds": 36000, "retention_days": 30, "jobs_queued": 0, "jobs_processing": 1 }, "a5s-v2-streaming": { "name": "A5S v2 Streaming", "type": "streaming", "enabled": true, "max_concurrent_sessions": 5, "max_session_seconds": 300 } } } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "account_disabled", "message": "this account is disabled", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Account" ], "operationId": "getAccount" } }, "/v1/usage": { "get": { "summary": "Get usage", "description": "Daily usage of both models.", "responses": { "200": { "description": "Usage report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "object": "usage", "timezone": "UTC", "start_date": "2026-09-07", "end_date": "2026-10-06", "models": [ { "id": "a5s-async-v1", "name": "A5S Async v1" }, { "id": "a5s-v2-streaming", "name": "A5S v2 Streaming" } ], "daily": [ { "date": "2026-10-06", "model": "a5s-async-v1", "requests": 12, "completed": 12, "failed": 0, "audio_seconds": 5410.2 } ], "totals": { "a5s-async-v1": { "requests": 12, "completed": 12, "failed": 0, "audio_seconds": 5410.2 } }, "by_key": [ { "key_id": "0123456789ab", "name": "Production", "model": "a5s-async-v1", "requests": 12, "audio_seconds": 5410.2 } ] } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`, `unsupported_language`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "unsupported_language", "message": "language 'de' is not supported; only English (\"en\", \"en-US\", ...) is available today. Multilingual support is planned.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "401": { "description": "Missing or invalid API key. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "invalid API key", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "403": { "description": "The account may not do this. Codes: `account_suspended`, `account_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "account_disabled", "message": "this account is disabled", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "500": { "description": "Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "internal error", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } } }, "tags": [ "Account" ], "operationId": "getUsage", "parameters": [ { "name": "days", "in": "query", "description": "Calendar days, including today.", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } }, { "name": "timezone", "in": "query", "description": "IANA time zone for day boundaries.", "schema": { "type": "string", "default": "UTC", "example": "America/New_York" } } ] } } }, "webhooks": { "transcript": { "post": { "summary": "Transcript finished", "description": "Sent to `webhook_url` when a transcript completes or fails. Signed per Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`). Reply 2xx within 15 s.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "transcript.completed", "id": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7", "status": "completed", "metadata": { "meeting_id": 42 } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key: `Authorization: Bearer aircaps_sk_...`" } }, "schemas": { "CreateTranscriptRequest": { "type": "object", "additionalProperties": false, "description": "Provide exactly one of `audio_url` or `file_id`.", "properties": { "model": { "type": "string", "enum": [ "a5s-async-v1" ], "default": "a5s-async-v1", "description": "The model. Any other value returns `400 unsupported_model`." }, "audio_url": { "type": "string", "maxLength": 8192, "format": "uri", "description": "An http(s) URL to download the audio from (public or presigned), up to 5 GB, resolving to a public address.", "example": "https://example.com/meeting.mp3" }, "file_id": { "type": "string", "maxLength": 64, "description": "ID from [Create an upload URL](/api-reference/upload-url) or [Upload a file](/api-reference/upload-file)." }, "language_code": { "type": "string", "maxLength": 16, "default": "en", "description": "Language of the audio. English only today: `en` or a regional variant (`en-US`, `en-GB`, `en-AU`, `en-CA`, `en-IN`, `en-IE`, `en-NZ`, `en-ZA`; case-insensitive, `-` or `_`). Any other value returns `400 unsupported_language`. Multilingual support is planned.", "example": "en-US" }, "webhook_url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Called with a [webhook event](/api-reference/objects/webhook-event) when the job finishes." }, "webhook_auth_header_name": { "type": "string", "maxLength": 256, "description": "Name of a header to add to webhook requests. Requires `webhook_url`.", "example": "Authorization" }, "webhook_auth_header_value": { "type": "string", "maxLength": 4096, "description": "Value of that header." }, "metadata": { "type": "object", "description": "Any JSON object up to 16 KB; echoed on the transcript and in webhooks.", "example": { "meeting_id": 42 } } } }, "Transcript": { "type": "object", "required": [ "id", "object", "status", "created_at", "started_at", "completed_at", "audio_url", "file_id", "language_code", "model", "audio_duration", "metadata", "webhook_url", "webhook_status_code", "error" ], "properties": { "id": { "type": "string", "description": "Transcript ID.", "example": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7" }, "object": { "type": "string", "enum": [ "transcript" ], "example": "transcript" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "error" ], "description": "`queued`: waiting for a processing slot. `processing`: being transcribed. `completed`: result fields present. `error`: see `error`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the transcript was created (UTC)." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When processing started." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the job finished (completed or error)." }, "audio_url": { "type": [ "string", "null" ], "description": "The submitted `audio_url`, if any." }, "file_id": { "type": [ "string", "null" ], "description": "The submitted `file_id`, if any." }, "language_code": { "type": "string", "enum": [ "en" ], "description": "Language of the transcript (normalised)." }, "model": { "type": "string", "enum": [ "a5s-async-v1" ] }, "audio_duration": { "type": [ "number", "null" ], "description": "Audio duration in seconds, once known.", "example": 3600.512 }, "metadata": { "type": [ "object", "null" ], "description": "Your `metadata`, echoed back." }, "webhook_url": { "type": [ "string", "null" ], "description": "Webhook target, if any." }, "webhook_status_code": { "type": [ "integer", "null" ], "description": "HTTP status of the last webhook delivery." }, "error": { "oneOf": [ { "$ref": "#/components/schemas/JobError" }, { "type": "null" } ], "description": "Set when `status` is `error`." }, "text": { "type": "string", "description": "Completed only. Full transcript: verbatim, lowercase, no punctuation." }, "speakers": { "type": "array", "items": { "$ref": "#/components/schemas/Speaker" }, "description": "Completed only." }, "utterances": { "type": "array", "items": { "$ref": "#/components/schemas/Utterance" }, "description": "Completed only. Speaker turns, in time order; overlapping speech overlaps." }, "words": { "type": "array", "items": { "$ref": "#/components/schemas/Word" }, "description": "Completed only. Every word, in time order." } } }, "TranscriptSummary": { "type": "object", "required": [ "id", "object", "status", "created_at", "started_at", "completed_at", "audio_url", "file_id", "language_code", "model", "audio_duration", "metadata", "webhook_url", "webhook_status_code", "error" ], "description": "A transcript without its result fields.", "properties": { "id": { "type": "string", "description": "Transcript ID.", "example": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7" }, "object": { "type": "string", "enum": [ "transcript" ], "example": "transcript" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "error" ], "description": "`queued`: waiting for a processing slot. `processing`: being transcribed. `completed`: result fields present. `error`: see `error`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the transcript was created (UTC)." }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When processing started." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the job finished (completed or error)." }, "audio_url": { "type": [ "string", "null" ], "description": "The submitted `audio_url`, if any." }, "file_id": { "type": [ "string", "null" ], "description": "The submitted `file_id`, if any." }, "language_code": { "type": "string", "enum": [ "en" ], "description": "Language of the transcript (normalised)." }, "model": { "type": "string", "enum": [ "a5s-async-v1" ] }, "audio_duration": { "type": [ "number", "null" ], "description": "Audio duration in seconds, once known.", "example": 3600.512 }, "metadata": { "type": [ "object", "null" ], "description": "Your `metadata`, echoed back." }, "webhook_url": { "type": [ "string", "null" ], "description": "Webhook target, if any." }, "webhook_status_code": { "type": [ "integer", "null" ], "description": "HTTP status of the last webhook delivery." }, "error": { "oneOf": [ { "$ref": "#/components/schemas/JobError" }, { "type": "null" } ], "description": "Set when `status` is `error`." } } }, "TranscriptList": { "type": "object", "required": [ "object", "data", "has_more", "next_before" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptSummary" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "description": "Pass as `before` for the next page." } } }, "Utterance": { "type": "object", "required": [ "speaker", "start", "end", "text", "words" ], "properties": { "speaker": { "type": "string", "description": "Speaker label (`speaker_0`, `speaker_1`, \u2026 in order of first speech).", "example": "speaker_0" }, "start": { "type": "number", "description": "Start time in seconds.", "example": 0.48 }, "end": { "type": "number", "description": "End time in seconds.", "example": 6.12 }, "text": { "type": "string", "description": "Text of the utterance.", "example": "hey good afternoon everybody" }, "words": { "type": "array", "items": { "$ref": "#/components/schemas/Word" }, "description": "Words of the utterance." } } }, "Word": { "type": "object", "required": [ "text", "start", "end", "speaker" ], "properties": { "text": { "type": "string", "description": "The word.", "example": "hey" }, "start": { "type": "number", "description": "Start time in seconds.", "example": 0.48 }, "end": { "type": "number", "description": "End time in seconds.", "example": 0.71 }, "speaker": { "type": "string", "description": "Speaker label.", "example": "speaker_0" } } }, "Speaker": { "type": "object", "required": [ "id", "speaking_time" ], "properties": { "id": { "type": "string", "example": "speaker_0" }, "speaking_time": { "type": "number", "description": "Seconds this speaker talks.", "example": 1402.11 } } }, "JobError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_audio", "audio_too_long", "file_too_large", "download_failed", "file_not_found", "usage_limit_reached", "internal_error", "canceled" ], "description": "Why the job failed. Failed jobs never count toward usage." }, "message": { "type": "string", "description": "Human-readable detail." } } }, "File": { "type": "object", "required": [ "id", "object", "size_bytes", "created_at", "expires_at" ], "properties": { "id": { "type": "string", "example": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "description": "Use as `file_id`." }, "object": { "type": "string", "enum": [ "file" ] }, "size_bytes": { "type": "integer", "example": 115200044 }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "24 hours after creation." } } }, "UploadUrl": { "type": "object", "required": [ "id", "object", "upload_url", "method", "upload_expires_at", "expires_at", "max_size_bytes" ], "properties": { "id": { "type": "string", "example": "file_01k6z3m4q8w7e5r2t1y0u9i8o7", "description": "Use as `file_id` after the upload." }, "object": { "type": "string", "enum": [ "file" ] }, "upload_url": { "type": "string", "description": "Presigned URL: `PUT` the raw file bytes here." }, "method": { "type": "string", "enum": [ "PUT" ] }, "upload_expires_at": { "type": "string", "format": "date-time", "description": "Upload before this (one hour)." }, "expires_at": { "type": "string", "format": "date-time", "description": "The file is deleted after this (24 hours)." }, "max_size_bytes": { "type": "integer", "example": 5368709120 } } }, "Model": { "type": "object", "required": [ "id", "object", "name", "type", "languages", "endpoint" ], "properties": { "id": { "type": "string", "enum": [ "a5s-async-v1", "a5s-v2-streaming" ] }, "object": { "type": "string", "enum": [ "model" ] }, "name": { "type": "string", "example": "A5S Async v1" }, "type": { "type": "string", "enum": [ "async", "streaming" ] }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ] }, "endpoint": { "type": "string", "example": "/v1/transcripts" } } }, "ModelList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "Account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account ID." }, "object": { "type": "string", "enum": [ "account" ] }, "email": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "suspended" ] }, "tier": { "type": "string" }, "usage_limit": { "type": "object", "description": "One limit shared by both models (5 hours free). To raise it, [talk to sales](https://research.aircaps.com/contact).", "properties": { "limit_seconds": { "type": "number", "example": 18000 }, "used_seconds": { "type": "number" }, "reserved_seconds": { "type": "number", "description": "Held by running jobs and sessions." }, "remaining_seconds": { "type": "number" } } }, "models": { "type": "object", "properties": { "a5s-async-v1": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "async" ] }, "enabled": { "type": "boolean", "description": "Whether this account may use the model." }, "max_concurrent_jobs": { "type": "integer" }, "max_queued_jobs": { "type": "integer" }, "max_requests_per_minute": { "type": "integer" }, "max_audio_duration_seconds": { "type": "integer" }, "retention_days": { "type": "integer" }, "jobs_queued": { "type": "integer" }, "jobs_processing": { "type": "integer" } } }, "a5s-v2-streaming": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "streaming" ] }, "enabled": { "type": "boolean" }, "max_concurrent_sessions": { "type": "integer" }, "max_session_seconds": { "type": "integer" } } } } } } }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "timezone": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "daily": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "model": { "type": "string" } } }, { "type": "object", "properties": { "requests": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "audio_seconds": { "type": "number" } } } ] } }, "totals": { "type": "object", "additionalProperties": { "type": "object", "properties": { "requests": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "audio_seconds": { "type": "number" } } }, "description": "Per model id." }, "by_key": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "model": { "type": "string" }, "requests": { "type": "integer" }, "audio_seconds": { "type": "number" } } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable code; see [Errors](/errors)." }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ], "description": "The request field at fault, if any." }, "request_id": { "type": "string", "description": "Also in the `x-request-id` header. Include it when contacting support." } } } } }, "WebhookEvent": { "type": "object", "required": [ "event", "id", "status" ], "properties": { "event": { "type": "string", "enum": [ "transcript.completed", "transcript.failed" ] }, "id": { "type": "string", "description": "Transcript ID." }, "status": { "type": "string", "enum": [ "completed", "error" ] }, "metadata": { "type": [ "object", "null" ], "description": "Your `metadata`." } } } } } }