{ "openapi": "3.1.0", "info": { "title": "AirCaps AI API", "version": "1.0.0", "description": "Speech-to-text for English: A5S Async v1 (REST) and A5S Small V2 Streaming (WebSocket). Speaker diarization: AirCaps Diarization-v1 (REST). Speaker identification: AirCaps Speaker ID-v1 (REST, synchronous)." }, "servers": [ { "url": "https://api.aircaps.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Transcripts" }, { "name": "Diarizations" }, { "name": "Speakers" }, { "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": null, "webhook_status_code": null, "error": null, "timing_mode": "phrase" } } }, "headers": { "Location": { "description": "URL of the new transcript.", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`, `unsupported_language`, `unsupported_model`, `no_enrolled_speakers`, `speaker_not_enrolled`.", "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://aircaps.ai/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "404": { "description": "Not found. Codes: `file_not_found`, `speaker_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "file_id not found or expired", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "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 } }, { "name": "wait", "in": "query", "required": false, "description": "Seconds to wait for the transcript to finish before answering (0 to 120). Answers as soon as it finishes, or with its current state when the time is up.", "schema": { "type": "number", "minimum": 0, "maximum": 120, "default": 0 } } ], "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": "delivered", "webhook_status_code": 200, "error": null, "timing_mode": "phrase" } ], "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "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/transcribe": { "post": { "summary": "Transcribe (one request)", "description": "Send the audio and get the finished transcript back in one request: the upload, [Create a transcript](/api-reference/create-transcript) and the wait in one call. The body is the raw audio (any audio or video format) with the options as query parameters, or a `multipart/form-data` form whose `file` field is the audio and whose other fields are the options. Options are those of Create a transcript except `audio_url` and `file_id`; `keyterms` may repeat, `metadata` and `speaker_identification` are JSON. If the transcript is not finished within `wait`, the answer is `202` with the transcript so far: fetch it with [Get a transcript](/api-reference/get-transcript), optionally with `wait`.", "responses": { "200": { "description": "The finished transcript (as Get a 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": "delivered", "webhook_status_code": 200, "error": null, "timing_mode": "phrase", "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" } ] } } }, "headers": { "Location": { "description": "URL of the transcript.", "schema": { "type": "string" } } } }, "202": { "description": "Not finished within `wait`: the transcript so far.", "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": null, "webhook_status_code": null, "error": null, "timing_mode": "phrase" } } }, "headers": { "Location": { "description": "URL of the 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": "invalid_request", "message": "empty request body; send the audio bytes as the body", "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://aircaps.ai/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" } } } } }, "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 for larger files (up to 5 GB)", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Transcripts" ], "operationId": "transcribe", "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string", "example": "a5s-async-v1" } }, { "name": "language_code", "in": "query", "required": false, "description": "Language of the audio. English only today: `en` or a regional English code (`en-US`, `en-GB`, `en-IN`, ...); for best results use the one that matches the speakers' locale or accent. The transcript reports `en`. Any other value returns `400 unsupported_language`. Multilingual support is planned.", "schema": { "type": "string", "default": "en" } }, { "name": "wait", "in": "query", "required": false, "description": "Seconds to wait for the transcript (0 to 120).", "schema": { "type": "number", "minimum": 0, "maximum": 120, "default": 120 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 255 characters. Makes retries safe: the same key and options return the original job.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "description": "The raw audio bytes, or a multipart form with `file`.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string" }, "language_code": { "type": "string" } } } } } } } }, "/v1/transcripts/{id}": { "get": { "summary": "Get a transcript", "description": "Status and, once `completed`, the result. Pass `wait` to hold the request until the transcript finishes instead of polling.", "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": "delivered", "webhook_status_code": 200, "error": null, "timing_mode": "phrase", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Transcripts" ], "operationId": "getTranscript", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transcript ID.", "schema": { "type": "string", "example": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7" } }, { "name": "wait", "in": "query", "required": false, "description": "Seconds to wait for the transcript to finish before answering (0 to 120). Answers as soon as it finishes, or with its current state when the time is up.", "schema": { "type": "number", "minimum": 0, "maximum": 120, "default": 0 } } ] }, "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, including the uploaded file it used. Afterwards the ID returns `404`.", "responses": { "200": { "description": "The transcript, with `deleted: true`. Your `metadata`, `audio_url` and webhook settings are already removed.", "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": "delivered", "webhook_status_code": 200, "error": null, "timing_mode": "phrase", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "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" } } } }, "400": { "description": "Invalid query parameter (`param` names it). Codes: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "Input should be greater than or equal to 10", "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" } } } } }, "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "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/diarizations": { "post": { "summary": "Create a diarization", "description": "Find who spoke when with AirCaps Diarization-v1 (enabled per account). The job runs asynchronously: poll [Get a diarization](/api-reference/get-diarization) or pass `webhook_url`.", "responses": { "201": { "description": "Created. A retried request with the same `Idempotency-Key` returns the original diarization with `200`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diarization" }, "example": { "id": "dia_01k72p0x9h6t3b8r1n4m7q2w5e", "object": "diarization", "status": "queued", "created_at": "2026-10-08T18:01:02.123Z", "started_at": null, "completed_at": null, "audio_url": "https://example.com/meeting.mp3", "file_id": null, "model": "aircaps-diarization-v1", "audio_duration": null, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status": null, "webhook_status_code": null, "error": null } } }, "headers": { "Location": { "description": "URL of the new diarization.", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "unsupported_model", "message": "model 'a5s-async-v1' is not available for diarization; use \"aircaps-diarization-v1\"", "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 AirCaps Diarization-v1. To get access, talk to sales at https://aircaps.ai/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "404": { "description": "Not found. Codes: `file_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_not_found", "message": "file_id not found or expired", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Diarizations" ], "operationId": "createDiarization", "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/CreateDiarizationRequest" }, "example": { "model": "aircaps-diarization-v1", "audio_url": "https://example.com/meeting.mp3", "webhook_url": "https://example.com/hooks/aircaps", "metadata": { "meeting_id": 42 } } } } } }, "get": { "summary": "List diarizations", "description": "Your diarizations, newest first. Items omit the result fields.", "responses": { "200": { "description": "A page of diarizations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiarizationList" }, "example": { "object": "list", "data": [ { "id": "dia_01k72p0x9h6t3b8r1n4m7q2w5e", "object": "diarization", "status": "completed", "created_at": "2026-10-08T18:01:02.123Z", "started_at": "2026-10-08T18:01:02.456Z", "completed_at": "2026-10-08T18:02:11.789Z", "audio_url": "https://example.com/meeting.mp3", "file_id": null, "model": "aircaps-diarization-v1", "audio_duration": 1834.112, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status": "delivered", "webhook_status_code": 200, "error": null } ], "has_more": true, "next_before": "dia_01k72p0x9h6t3b8r1n4m7q2w5e" } } } }, "400": { "description": "Invalid query parameter (`param` names it). Codes: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "Input should be greater than or equal to 10", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Diarizations" ], "operationId": "listDiarizations", "parameters": [ { "name": "limit", "in": "query", "description": "Number of diarizations to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "description": "Only diarizations 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/diarizations/{id}": { "get": { "summary": "Get a diarization", "description": "Status and, once `completed`, the result.", "responses": { "200": { "description": "The diarization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diarization" }, "example": { "id": "dia_01k72p0x9h6t3b8r1n4m7q2w5e", "object": "diarization", "status": "completed", "created_at": "2026-10-08T18:01:02.123Z", "started_at": "2026-10-08T18:01:02.456Z", "completed_at": "2026-10-08T18:02:11.789Z", "audio_url": "https://example.com/meeting.mp3", "file_id": null, "model": "aircaps-diarization-v1", "audio_duration": 1834.112, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status": "delivered", "webhook_status_code": 200, "error": null, "num_speakers": 3, "speakers": [ { "id": "speaker_0", "speaking_time": 702.31 }, { "id": "speaker_1", "speaking_time": 611.08 }, { "id": "speaker_2", "speaking_time": 240.6 } ], "segments": [ { "speaker": "speaker_0", "start": 0.48, "end": 6.12 }, { "speaker": "speaker_1", "start": 5.9, "end": 9.33 }, { "speaker": "speaker_0", "start": 9.71, "end": 14.02 } ], "speech_duration": 1498.27, "overlap_duration": 61.44 } } } }, "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": "diarization 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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Diarizations" ], "operationId": "getDiarization", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Diarization ID.", "schema": { "type": "string", "example": "dia_01k72p0x9h6t3b8r1n4m7q2w5e" } } ] }, "delete": { "summary": "Delete a diarization", "description": "Cancels a `queued` or `processing` job (its `error.code` becomes `canceled`), or deletes a finished diarization and its stored data, including the uploaded file it used. Afterwards the ID returns `404`.", "responses": { "200": { "description": "The diarization, with `deleted: true`. Your `metadata`, `audio_url` and webhook settings are already removed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DiarizationSummary" }, { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } ] }, "example": { "id": "dia_01k72p0x9h6t3b8r1n4m7q2w5e", "object": "diarization", "status": "completed", "created_at": "2026-10-08T18:01:02.123Z", "started_at": "2026-10-08T18:01:02.456Z", "completed_at": "2026-10-08T18:02:11.789Z", "audio_url": "https://example.com/meeting.mp3", "file_id": null, "model": "aircaps-diarization-v1", "audio_duration": 1834.112, "metadata": { "meeting_id": 42 }, "webhook_url": "https://example.com/hooks/aircaps", "webhook_status": "delivered", "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": "diarization 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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Diarizations" ], "operationId": "deleteDiarization", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Diarization ID.", "schema": { "type": "string", "example": "dia_01k72p0x9h6t3b8r1n4m7q2w5e" } } ] } }, "/v1/diarizations/{id}/rttm": { "get": { "summary": "Get RTTM", "description": "The segments of a completed diarization as an RTTM file (one `SPEAKER` line per segment), the format diarization scoring tools read.", "responses": { "200": { "description": "RTTM as text.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "SPEAKER dia_01k72p0x9h6t3b8r1n4m7q2w5e 1 0.480 5.640 speaker_0 \n" } } }, "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": "diarization not found", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "409": { "description": "The diarization is not completed. Codes: `diarization_not_ready`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "diarization_not_ready", "message": "diarization 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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Diarizations" ], "operationId": "getDiarizationRttm", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Diarization ID.", "schema": { "type": "string", "example": "dia_01k72p0x9h6t3b8r1n4m7q2w5e" } } ] } }, "/v1/speakers": { "post": { "summary": "Create a speaker", "description": "Create a speaker to enroll (AirCaps Speaker ID-v1, enabled per account). A speaker is a name and optional metadata until you [add enrollments](/api-reference/add-enrollment).", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrolledSpeaker" }, "example": { "id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "object": "speaker", "name": "Ana Garc\u00eda", "metadata": { "employee_id": "E-1042" }, "model": "aircaps-speaker-id-v1", "num_enrollments": 0, "enrolled_duration": 0, "enrollments": [], "created_at": "2026-10-08T18:02:40.118Z", "updated_at": "2026-10-08T18:02:40.118Z" } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "metadata exceeds 16 KB", "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 AirCaps Speaker ID-v1. To get access, talk to sales at https://aircaps.ai/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "409": { "description": "The account has the maximum number of speakers. Codes: `speaker_limit_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "speaker_limit_reached", "message": "an account can have at most 1000 speakers; delete one first, or talk to sales at https://aircaps.ai/contact for more", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "createSpeaker", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpeakerRequest" }, "example": { "name": "Ana Garc\u00eda", "metadata": { "employee_id": "E-1042" } } } } } }, "get": { "summary": "List speakers", "description": "Your enrolled speakers, newest first, with their enrollments.", "responses": { "200": { "description": "A page of speakers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrolledSpeakerList" }, "example": { "object": "list", "data": [ { "id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "object": "speaker", "name": "Ana Garc\u00eda", "metadata": { "employee_id": "E-1042" }, "model": "aircaps-speaker-id-v1", "num_enrollments": 2, "enrolled_duration": 27.9, "enrollments": [ { "id": "enr_01k73b2c4d5e6f7g8h9j0k1m2n", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 12.48, "consistency": 0.712, "created_at": "2026-10-08T18:03:11.402Z" }, { "id": "enr_01k73b5f1h2j3k4m5n6p7q8r9s", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 15.42, "consistency": 0.712, "created_at": "2026-10-08T18:04:52.015Z" } ], "created_at": "2026-10-08T18:02:40.118Z", "updated_at": "2026-10-08T18:04:52.015Z" } ], "has_more": false, "next_before": null } } } }, "400": { "description": "Invalid query parameter (`param` names it). Codes: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "Input should be greater than or equal to 10", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "listSpeakers", "parameters": [ { "name": "limit", "in": "query", "description": "Number of speakers to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "before", "in": "query", "description": "Pagination cursor: the `next_before` of the previous page.", "schema": { "type": "string" } } ] } }, "/v1/speakers/identify": { "post": { "summary": "Identify a speaker", "description": "Score one clip against your enrolled speakers: every speaker (or the ones in `speaker_ids`), best first, with a similarity score for each speaker's profile and for each enrollment. Synchronous: the result is the response. No threshold is applied; see [Speaker ID](/guides/speaker-id#scores-and-thresholds).", "responses": { "200": { "description": "The scores.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeakerIdentification" }, "example": { "id": "sid_01k73c0q9w8e7r6t5y4u3i2o1p", "object": "speaker_identification", "model": "aircaps-speaker-id-v1", "created_at": "2026-10-08T18:06:30.551Z", "audio_duration": 4.21, "speakers_compared": 3, "margin": 0.476, "results": [ { "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "name": "Ana Garc\u00eda", "score": 0.684, "enrollment_scores": [ { "enrollment_id": "enr_01k73b2c4d5e6f7g8h9j0k1m2n", "score": 0.661 }, { "enrollment_id": "enr_01k73b5f1h2j3k4m5n6p7q8r9s", "score": 0.648 } ] }, { "speaker_id": "spk_01k73a7m6n5b4v3c2x1z0l9k8j", "name": "Ben Ito", "score": 0.208, "enrollment_scores": [ { "enrollment_id": "enr_01k73a8h7g6f5d4s3a2p1o0i9u", "score": 0.208 } ] }, { "speaker_id": "spk_01k73a5q4w3e2r1t0y9u8i7o6p", "name": null, "score": 0.031, "enrollment_scores": [ { "enrollment_id": "enr_01k73a6z5x4c3v2b1n0m9l8k7j", "score": 0.031 } ] } ] } } } }, "400": { "description": "The clip or request is not usable. Codes: `no_enrolled_speakers`, `speaker_not_enrolled`, `invalid_request`, `invalid_audio`, `audio_too_short`, `audio_too_long`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "audio_too_short", "message": "the clip is 0.62 s long; it must be at least 1 s", "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 AirCaps Speaker ID-v1. To get access, talk to sales at https://aircaps.ai/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "404": { "description": "A speaker in `speaker_ids` was not found. Codes: `speaker_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "speaker_not_found", "message": "speaker 'spk_01k73a9x8w7v6u5t4s3r2q1p0n' not found", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "413": { "description": "Larger than 100 MB. Codes: `file_too_large`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "clips are limited to 100 MB", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "429": { "description": "More requests in the last minute than the account allows. Codes: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "more than 600 requests in the last minute", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "identifySpeaker", "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.aircaps.com/v1/speakers/identify\" \\\n -H \"Authorization: Bearer $AIRCAPS_API_KEY\" \\\n -H \"Content-Type: audio/wav\" \\\n --data-binary @clip.wav" }, { "lang": "python", "label": "Python", "source": "import os, requests\n\nwith open(\"clip.wav\", \"rb\") as f:\n r = requests.post(\"https://api.aircaps.com/v1/speakers/identify\",\n headers={\"Authorization\": f\"Bearer {os.environ['AIRCAPS_API_KEY']}\", \"Content-Type\": \"audio/wav\"},\n data=f)\nprint(r.json()[\"results\"][0])" } ], "parameters": [ { "name": "speaker_ids", "in": "query", "required": false, "description": "Only these speakers: comma-separated, or the parameter repeated. Default: every enrolled speaker of the account. Verification of one person is `speaker_ids=`.", "schema": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n,spk_01k73a7m6n5b4v3c2x1z0l9k8j" } }, { "name": "top_k", "in": "query", "required": false, "description": "Return only the best `top_k` results (all speakers are still scored; `margin` and `speakers_compared` are unchanged).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "model", "in": "query", "required": false, "description": "Optional: `aircaps-speaker-id-v1`. Any other value returns `400 unsupported_model`.", "schema": { "type": "string", "enum": [ "aircaps-speaker-id-v1" ] } }, { "name": "Content-Type", "in": "header", "required": false, "description": "The clip's media type, for example `audio/wav`. Informational: the format is detected from the bytes.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The clip's raw audio bytes (any common audio or video format; channels are mixed down and audio is resampled to 16 kHz). Not multipart form data. The whole clip is used as given: crop it to one person's speech first.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "audio/*": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/speakers/{id}": { "get": { "summary": "Get a speaker", "description": "The speaker and its enrollments.", "responses": { "200": { "description": "The speaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrolledSpeaker" }, "example": { "id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "object": "speaker", "name": "Ana Garc\u00eda", "metadata": { "employee_id": "E-1042" }, "model": "aircaps-speaker-id-v1", "num_enrollments": 2, "enrolled_duration": 27.9, "enrollments": [ { "id": "enr_01k73b2c4d5e6f7g8h9j0k1m2n", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 12.48, "consistency": 0.712, "created_at": "2026-10-08T18:03:11.402Z" }, { "id": "enr_01k73b5f1h2j3k4m5n6p7q8r9s", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 15.42, "consistency": 0.712, "created_at": "2026-10-08T18:04:52.015Z" } ], "created_at": "2026-10-08T18:02:40.118Z", "updated_at": "2026-10-08T18:04:52.015Z" } } } }, "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: `speaker_not_found`, `enrollment_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "speaker_not_found", "message": "speaker 'spk_01k73a9x8w7v6u5t4s3r2q1p0n' 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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "getSpeaker", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Speaker ID.", "schema": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" } } ] }, "patch": { "summary": "Update a speaker", "description": "Change the name or metadata. Omitted fields stay as they are; `null` clears one.", "responses": { "200": { "description": "The updated speaker.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrolledSpeaker" }, "example": { "id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "object": "speaker", "name": "Ana Garc\u00eda", "metadata": { "employee_id": "E-1042" }, "model": "aircaps-speaker-id-v1", "num_enrollments": 2, "enrolled_duration": 27.9, "enrollments": [ { "id": "enr_01k73b2c4d5e6f7g8h9j0k1m2n", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 12.48, "consistency": 0.712, "created_at": "2026-10-08T18:03:11.402Z" }, { "id": "enr_01k73b5f1h2j3k4m5n6p7q8r9s", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 15.42, "consistency": 0.712, "created_at": "2026-10-08T18:04:52.015Z" } ], "created_at": "2026-10-08T18:02:40.118Z", "updated_at": "2026-10-08T18:04:52.015Z" } } } }, "400": { "description": "Invalid request. Codes: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "metadata exceeds 16 KB", "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" } } } } }, "404": { "description": "Not found. Codes: `speaker_not_found`, `enrollment_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "speaker_not_found", "message": "speaker 'spk_01k73a9x8w7v6u5t4s3r2q1p0n' 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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "updateSpeaker", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Speaker ID.", "schema": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSpeakerRequest" }, "example": { "name": "Ana Garc\u00eda L\u00f3pez" } } } } }, "delete": { "summary": "Delete a speaker", "description": "Deletes the speaker and all its enrollment embeddings, immediately and permanently. Afterwards the ID returns `404`.", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "speaker" ] }, "deleted": { "type": "boolean", "enum": [ true ] } } }, "example": { "id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "object": "speaker", "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: `speaker_not_found`, `enrollment_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "speaker_not_found", "message": "speaker 'spk_01k73a9x8w7v6u5t4s3r2q1p0n' 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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "deleteSpeaker", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Speaker ID.", "schema": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" } } ] } }, "/v1/speakers/{id}/enrollments": { "post": { "summary": "Add an enrollment", "description": "Add one clip of this speaker. The model turns it into a speaker embedding, which is stored; the audio is not. A speaker's profile combines all of its enrollments, so several clips from different recordings make it sturdier. Synchronous: the response is the new enrollment and the updated speaker.", "responses": { "201": { "description": "Enrolled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SpeakerEnrollment" }, { "type": "object", "properties": { "speaker": { "$ref": "#/components/schemas/EnrolledSpeaker" } } } ] }, "example": { "id": "enr_01k73b5f1h2j3k4m5n6p7q8r9s", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 15.42, "consistency": 0.712, "created_at": "2026-10-08T18:04:52.015Z", "speaker": { "id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "object": "speaker", "name": "Ana Garc\u00eda", "metadata": { "employee_id": "E-1042" }, "model": "aircaps-speaker-id-v1", "num_enrollments": 2, "enrolled_duration": 27.9, "enrollments": [ { "id": "enr_01k73b2c4d5e6f7g8h9j0k1m2n", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 12.48, "consistency": 0.712, "created_at": "2026-10-08T18:03:11.402Z" }, { "id": "enr_01k73b5f1h2j3k4m5n6p7q8r9s", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "audio_duration": 15.42, "consistency": 0.712, "created_at": "2026-10-08T18:04:52.015Z" } ], "created_at": "2026-10-08T18:02:40.118Z", "updated_at": "2026-10-08T18:04:52.015Z" } } } } }, "400": { "description": "The clip or request is not usable. Codes: `invalid_request`, `invalid_audio`, `audio_too_short`, `audio_too_long`, `unsupported_model`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "audio_too_short", "message": "the clip is 0.62 s long; it must be at least 1 s", "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 AirCaps Speaker ID-v1. To get access, talk to sales at https://aircaps.ai/contact.", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "404": { "description": "Not found. Codes: `speaker_not_found`, `enrollment_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "speaker_not_found", "message": "speaker 'spk_01k73a9x8w7v6u5t4s3r2q1p0n' not found", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "409": { "description": "The speaker has the maximum number of enrollments. Codes: `enrollment_limit_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "enrollment_limit_reached", "message": "a speaker can have at most 20 enrollments; delete one first", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "413": { "description": "Larger than 100 MB. Codes: `file_too_large`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "clips are limited to 100 MB", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } } }, "429": { "description": "More requests in the last minute than the account allows. Codes: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "more than 600 requests in the last minute", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "addEnrollment", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Speaker ID.", "schema": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" } }, { "name": "model", "in": "query", "required": false, "description": "Optional: `aircaps-speaker-id-v1`. Any other value returns `400 unsupported_model`.", "schema": { "type": "string", "enum": [ "aircaps-speaker-id-v1" ] } } ], "requestBody": { "required": true, "description": "The clip's raw audio bytes (any common audio or video format; channels are mixed down and audio is resampled to 16 kHz). Not multipart form data. The whole clip is used as given: crop it to one person's speech first.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "audio/*": { "schema": { "type": "string", "format": "binary" } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.aircaps.com/v1/speakers/spk_01k73a9x8w7v6u5t4s3r2q1p0n/enrollments\" \\\n -H \"Authorization: Bearer $AIRCAPS_API_KEY\" \\\n -H \"Content-Type: audio/wav\" \\\n --data-binary @ana_intro.wav" }, { "lang": "python", "label": "Python", "source": "import os, requests\n\nwith open(\"ana_intro.wav\", \"rb\") as f:\n r = requests.post(\"https://api.aircaps.com/v1/speakers/spk_01k73a9x8w7v6u5t4s3r2q1p0n/enrollments\",\n headers={\"Authorization\": f\"Bearer {os.environ['AIRCAPS_API_KEY']}\", \"Content-Type\": \"audio/wav\"},\n data=f)\nprint(r.json()[\"consistency\"])" } ] } }, "/v1/speakers/{id}/enrollments/{enrollment_id}": { "delete": { "summary": "Delete an enrollment", "description": "Removes one enrollment's embedding, immediately and permanently. The speaker's profile is recomputed from the rest.", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "speaker_enrollment" ] }, "speaker_id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } } }, "example": { "id": "enr_01k73b2c4d5e6f7g8h9j0k1m2n", "object": "speaker_enrollment", "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "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: `speaker_not_found`, `enrollment_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "speaker_not_found", "message": "speaker 'spk_01k73a9x8w7v6u5t4s3r2q1p0n' 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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Speakers" ], "operationId": "deleteEnrollment", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Speaker ID.", "schema": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" } }, { "name": "enrollment_id", "in": "path", "required": true, "description": "Enrollment ID.", "schema": { "type": "string", "example": "enr_01k73b2c4d5e6f7g8h9j0k1m2n" } } ] } }, "/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 upload. Codes: `account_suspended`, `account_disabled`, `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://aircaps.ai/contact.", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Files" ], "operationId": "createUploadUrl" } }, "/v1/files": { "post": { "summary": "Upload a file", "description": "Upload up to 1 GB in the request body. For larger files (up to 5 GB), use an upload URL. An upload that takes longer than about 2.5 minutes is answered with a 303 redirect to its result: follow redirects (most HTTP clients do by default).", "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": "Empty request body. Codes: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "empty request body; send the audio bytes as the body", "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 upload. Codes: `account_suspended`, `account_disabled`, `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://aircaps.ai/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 for larger files (up to 5 GB)", "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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Files" ], "operationId": "uploadFile", "requestBody": { "required": true, "description": "The raw file bytes (any audio 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-small-v2-streaming", "object": "model", "name": "A5S Small V2 Streaming", "type": "streaming", "languages": [ "en" ], "endpoint": "/v1/realtime" }, { "id": "aircaps-diarization-v1", "object": "model", "name": "AirCaps Diarization-v1", "type": "async", "task": "diarization", "endpoint": "/v1/diarizations", "access": "by_request" }, { "id": "aircaps-speaker-id-v1", "object": "model", "name": "AirCaps Speaker ID-v1", "type": "sync", "task": "speaker_identification", "endpoint": "/v1/speakers", "access": "by_request" } ] } } } } }, "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://aircaps.ai/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-small-v2-streaming": { "name": "A5S Small V2 Streaming", "type": "streaming", "enabled": true, "max_concurrent_sessions": 5, "max_session_seconds": 1800 }, "aircaps-diarization-v1": { "name": "AirCaps Diarization-v1", "type": "async", "enabled": false, "max_concurrent_jobs": 5, "max_queued_jobs": 2000, "max_requests_per_minute": 600, "max_audio_duration_seconds": 21600, "retention_days": 30 }, "aircaps-speaker-id-v1": { "name": "AirCaps Speaker ID-v1", "type": "sync", "enabled": false, "max_requests_per_minute": 600, "max_clip_duration_seconds": 120, "max_speakers": 1000, "max_enrollments_per_speaker": 20, "speakers": 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 is disabled. Codes: `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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "tags": [ "Account" ], "operationId": "getAccount" } }, "/v1/usage": { "get": { "summary": "Get usage", "description": "Daily usage of each model your account can use.", "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-small-v2-streaming", "name": "A5S Small 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 query parameter (`param` names it). Codes: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_request", "message": "Input should be greater than or equal to 10", "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 is disabled. Codes: `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" } } } } }, "503": { "description": "Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "service_unavailable", "message": "temporarily unavailable; please retry", "param": null, "request_id": "req_01k6z3m4q8w7e5r2t1y0u9i8o7" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "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." } } } }, "diarization": { "post": { "summary": "Diarization finished", "description": "Sent to `webhook_url` when a diarization completes or fails. Signed like every webhook. Reply 2xx within 15 s.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "diarization.completed", "id": "dia_01k72p0x9h6t3b8r1n4m7q2w5e", "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": "An uploaded file, usable by any number of transcripts for 24 hours after upload. 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 English code (`en-US`, `en-GB`, `en-IN`, ...); for best results use the one that matches the speakers' locale or accent. The transcript reports `en`. Any other value returns `400 unsupported_language`. Multilingual support is planned.", "example": "en" }, "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 } }, "speaker_identification": { "oneOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/SpeakerIdentificationOptions" } ], "description": "Name the transcript's speakers from your [enrolled speakers](/guides/speaker-id) with AirCaps Speaker ID-v1 (enabled per account; `403 model_access_denied` otherwise). `true` uses the defaults; an object sets `threshold` and `speaker_ids`. See [Speaker names](/guides/async-transcription#speaker-names).", "example": { "threshold": 0.6 } }, "timing_mode": { "type": "string", "enum": [ "phrase", "region" ], "default": "phrase", "description": "Timestamp style for `words` and `utterances`." }, "keyterms": { "type": "array", "maxItems": 60, "items": { "type": "string", "maxLength": 50 }, "description": "Key terms: up to 60 words or short phrases that may be spoken in the audio, such as names, products and jargon (each at most 6 words and 50 characters), to help the model recognize them. The text stays lowercase with numbers spelled out, so a key term appears as spoken: \"GPT-4\" as \"gpt four\". See [Key terms](/guides/async-transcription#key-terms).", "example": [ "AirCaps", "Dr. Patel", "GPT-4" ] }, "large_meeting": { "type": "boolean", "default": false, "description": "Set to `true` for recordings with many active speakers, typically more than 7 to 9, such as large team meetings, panels, town halls and hearings. Improves speaker attribution for these recordings and may take a little longer to process. Leave it off for typical meetings and conversations. See [Large meetings](/guides/async-transcription#large-meetings)." } } }, "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", "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": { "type": [ "string", "null" ], "enum": [ "pending", "delivered", "failed", null ], "description": "Webhook delivery state, if `webhook_url` was set." }, "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/TranscriptSpeaker" }, "description": "Completed only. With `speaker_identification`, each speaker also has `speaker_id`, `name`, `score`, `matches` and `compared_duration`." }, "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." }, "timing_mode": { "type": "string", "enum": [ "phrase", "region" ], "description": "The `timing_mode` used." }, "keyterms": { "type": "array", "items": { "type": "string" }, "description": "Only when the transcript was created with `keyterms`: the list used (duplicates removed)." }, "large_meeting": { "type": "boolean", "description": "Only when the transcript was created with `large_meeting: true`." }, "speaker_identification": { "$ref": "#/components/schemas/TranscriptSpeakerIdentification", "description": "Only when the transcript was created with `speaker_identification`: its settings and outcome." } } }, "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", "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": { "type": [ "string", "null" ], "enum": [ "pending", "delivered", "failed", null ], "description": "Webhook delivery state, if `webhook_url` was set." }, "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." } } }, "CreateDiarizationRequest": { "type": "object", "additionalProperties": false, "description": "Provide exactly one of `audio_url` or `file_id`.", "properties": { "model": { "type": "string", "enum": [ "aircaps-diarization-v1" ], "default": "aircaps-diarization-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": "An uploaded file, usable by any number of jobs for 24 hours after upload. ID from [Create an upload URL](/api-reference/upload-url) or [Upload a file](/api-reference/upload-file)." }, "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 diarization and in webhooks.", "example": { "meeting_id": 42 } } } }, "Diarization": { "type": "object", "required": [ "id", "object", "status", "created_at", "started_at", "completed_at", "audio_url", "file_id", "model", "audio_duration", "metadata", "webhook_url", "webhook_status", "webhook_status_code", "error" ], "properties": { "id": { "type": "string", "description": "Diarization ID.", "example": "dia_01k72p0x9h6t3b8r1n4m7q2w5e" }, "object": { "type": "string", "enum": [ "diarization" ], "example": "diarization" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "error" ], "description": "`queued`: waiting for a processing slot. `processing`: being diarized. `completed`: result fields present. `error`: see `error`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the diarization 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." }, "model": { "type": "string", "enum": [ "aircaps-diarization-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": { "type": [ "string", "null" ], "enum": [ "pending", "delivered", "failed", null ], "description": "Webhook delivery state, if `webhook_url` was set." }, "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`." }, "num_speakers": { "type": "integer", "description": "Completed only. Number of speakers found.", "example": 3 }, "speakers": { "type": "array", "items": { "$ref": "#/components/schemas/Speaker" }, "description": "Completed only. Every speaker, with their speaking time." }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" }, "description": "Completed only. Who spoke when, in time order. Overlapping speech appears as overlapping segments of different speakers." }, "speech_duration": { "type": "number", "description": "Completed only. Seconds in which anyone speaks.", "example": 1498.27 }, "overlap_duration": { "type": "number", "description": "Completed only. Seconds in which two or more people speak at once.", "example": 61.44 } } }, "DiarizationSummary": { "type": "object", "required": [ "id", "object", "status", "created_at", "started_at", "completed_at", "audio_url", "file_id", "model", "audio_duration", "metadata", "webhook_url", "webhook_status", "webhook_status_code", "error" ], "description": "A diarization without its result fields.", "properties": { "id": { "type": "string", "description": "Diarization ID.", "example": "dia_01k72p0x9h6t3b8r1n4m7q2w5e" }, "object": { "type": "string", "enum": [ "diarization" ], "example": "diarization" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "error" ], "description": "`queued`: waiting for a processing slot. `processing`: being diarized. `completed`: result fields present. `error`: see `error`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the diarization 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." }, "model": { "type": "string", "enum": [ "aircaps-diarization-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": { "type": [ "string", "null" ], "enum": [ "pending", "delivered", "failed", null ], "description": "Webhook delivery state, if `webhook_url` was set." }, "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`." } } }, "DiarizationList": { "type": "object", "required": [ "object", "data", "has_more", "next_before" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DiarizationSummary" } }, "has_more": { "type": "boolean" }, "next_before": { "type": [ "string", "null" ], "description": "Pass as `before` for the next page." } } }, "Segment": { "type": "object", "required": [ "speaker", "start", "end" ], "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 } } }, "CreateSpeakerRequest": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string", "enum": [ "aircaps-speaker-id-v1" ], "description": "Optional. Any other value returns `400 unsupported_model`." }, "name": { "type": [ "string", "null" ], "maxLength": 200, "description": "Your label for the speaker (whitespace is collapsed). Optional.", "example": "Ana Garc\u00eda" }, "metadata": { "type": [ "object", "null" ], "description": "Any JSON object up to 16 KB.", "example": { "employee_id": "E-1042" } } } }, "UpdateSpeakerRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ], "maxLength": 200 }, "metadata": { "type": [ "object", "null" ], "description": "Replaces the metadata (up to 16 KB)." } } }, "EnrolledSpeaker": { "type": "object", "required": [ "id", "object", "name", "metadata", "model", "num_enrollments", "enrolled_duration", "enrollments", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Speaker ID.", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" }, "object": { "type": "string", "enum": [ "speaker" ] }, "name": { "type": [ "string", "null" ], "description": "Your label for the speaker.", "example": "Ana Garc\u00eda" }, "metadata": { "type": [ "object", "null" ], "description": "Your `metadata`.", "example": { "employee_id": "E-1042" } }, "model": { "type": "string", "enum": [ "aircaps-speaker-id-v1" ] }, "num_enrollments": { "type": "integer", "example": 2 }, "enrolled_duration": { "type": "number", "description": "Seconds of enrollment audio in total.", "example": 27.9 }, "enrollments": { "type": "array", "items": { "$ref": "#/components/schemas/SpeakerEnrollment" }, "description": "Oldest first. Only embeddings are stored, never the audio." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last change to the name, metadata or enrollments." } } }, "SpeakerEnrollment": { "type": "object", "required": [ "id", "object", "speaker_id", "audio_duration", "consistency", "created_at" ], "properties": { "id": { "type": "string", "description": "Enrollment ID.", "example": "enr_01k73b2c4d5e6f7g8h9j0k1m2n" }, "object": { "type": "string", "enum": [ "speaker_enrollment" ] }, "speaker_id": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" }, "audio_duration": { "type": "number", "description": "Seconds of audio in the enrollment clip.", "example": 12.48 }, "consistency": { "type": [ "number", "null" ], "description": "How well this enrollment matches the speaker's other enrollments (-1 to 1). `null` when it is the only one. A value much lower than the speaker's other enrollments suggests a clip of someone else or a poor recording.", "example": 0.712 }, "created_at": { "type": "string", "format": "date-time" } } }, "SpeakerIdentification": { "type": "object", "required": [ "id", "object", "model", "created_at", "audio_duration", "speakers_compared", "margin", "results" ], "properties": { "id": { "type": "string", "description": "Identification ID (identifies the request; identifications are not stored).", "example": "sid_01k73c0q9w8e7r6t5y4u3i2o1p" }, "object": { "type": "string", "enum": [ "speaker_identification" ] }, "model": { "type": "string", "enum": [ "aircaps-speaker-id-v1" ] }, "created_at": { "type": "string", "format": "date-time" }, "audio_duration": { "type": "number", "description": "Seconds of audio in the clip.", "example": 4.21 }, "speakers_compared": { "type": "integer", "description": "Speakers the clip was scored against (before `top_k`).", "example": 3 }, "margin": { "type": [ "number", "null" ], "description": "Best `score` minus the second best. `null` with one speaker.", "example": 0.476 }, "results": { "type": "array", "description": "Best first (ties by speaker ID).", "items": { "type": "object", "required": [ "speaker_id", "name", "score", "enrollment_scores" ], "properties": { "speaker_id": { "type": "string", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" }, "name": { "type": [ "string", "null" ], "example": "Ana Garc\u00eda" }, "score": { "type": "number", "description": "Similarity (-1 to 1) between the clip and the speaker's profile, which combines all of their enrollments. Higher means more alike. Not a probability, and no threshold is applied.", "example": 0.684 }, "enrollment_scores": { "type": "array", "description": "The clip against each enrollment on its own, in enrollment order.", "items": { "type": "object", "properties": { "enrollment_id": { "type": "string" }, "score": { "type": "number", "example": 0.661 } } } } } } } } }, "EnrolledSpeakerList": { "type": "object", "required": [ "object", "data", "has_more", "next_before" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnrolledSpeaker" } }, "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" }, "speaker_name": { "type": [ "string", "null" ], "description": "Only with `speaker_identification`: the name of the enrolled speaker this speaker was matched with, or `null`.", "example": "Ana Garc\u00eda" }, "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 } } }, "TranscriptSpeaker": { "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 }, "speaker_id": { "type": [ "string", "null" ], "description": "Only with `speaker_identification`: the enrolled speaker matched with this speaker (its best score reached `threshold`), or `null`. Two speakers can match the same enrolled speaker when one person was split in two.", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" }, "name": { "type": [ "string", "null" ], "description": "Only with `speaker_identification`: the matched enrolled speaker's name.", "example": "Ana Garc\u00eda" }, "score": { "type": [ "number", "null" ], "description": "Only with `speaker_identification`: the matched enrolled speaker's score, or `null`.", "example": 0.781 }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/SpeakerMatch" }, "description": "Only with `speaker_identification`: the 3 best-scoring enrolled speakers, best first, whether or not they reached `threshold`. Empty when the speaker had too little speech to compare." }, "compared_duration": { "type": "number", "description": "Only with `speaker_identification`: seconds of this speaker's audio that were compared.", "example": 60.0 } } }, "SpeakerMatch": { "type": "object", "required": [ "speaker_id", "name", "score" ], "properties": { "speaker_id": { "type": "string", "description": "Enrolled speaker ID.", "example": "spk_01k73a9x8w7v6u5t4s3r2q1p0n" }, "name": { "type": [ "string", "null" ], "description": "The enrolled speaker's name.", "example": "Ana Garc\u00eda" }, "score": { "type": "number", "description": "Similarity of this speaker's voice to the enrolled speaker (-1 to 1).", "example": 0.781 } } }, "SpeakerIdentificationOptions": { "type": "object", "additionalProperties": false, "properties": { "speaker_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 1000, "description": "Compare with these enrolled speakers only, for example the people invited to the meeting. Each must exist and have an enrollment. Default: every enrolled speaker of the account.", "example": [ "spk_01k73a9x8w7v6u5t4s3r2q1p0n", "spk_01k73a7m6n5b4v3c2x1z0l9k8j" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.6, "description": "A speaker gets an enrolled speaker's name when that is their best match and the score is at least this. 0.5 names a few more speakers when everyone who may speak is enrolled.", "example": 0.6 } } }, "TranscriptSpeakerIdentification": { "type": "object", "required": [ "model", "status", "threshold", "speaker_ids", "speakers_compared", "speakers_identified", "error" ], "properties": { "model": { "type": "string", "enum": [ "aircaps-speaker-id-v1" ] }, "status": { "type": "string", "enum": [ "pending", "completed", "failed", "skipped" ], "description": "`pending`: the transcript is not finished. `completed`: matched (possibly nobody). `failed`: speaker identification was unavailable; the transcript is complete without names (see `error`). `skipped`: the transcript failed." }, "threshold": { "type": "number", "example": 0.6 }, "speaker_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The requested `speaker_ids`, or `null` for every enrolled speaker." }, "speakers_compared": { "type": [ "integer", "null" ], "description": "Enrolled speakers compared (those that existed and had enrollments when the transcript was processed).", "example": 12 }, "speakers_identified": { "type": [ "integer", "null" ], "description": "Transcript speakers that got a name.", "example": 2 }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "speaker_identification_failed" ] }, "message": { "type": "string" } } } } }, "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": "Usable until this time (24 hours after upload); the file is deleted within the following 24 hours, or right away when a transcript that used it is deleted." } } }, "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": "Usable until this time (24 hours after upload); the file is deleted within the following 24 hours, or right away when a transcript that used it is deleted." }, "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-small-v2-streaming", "aircaps-diarization-v1", "aircaps-speaker-id-v1" ] }, "object": { "type": "string", "enum": [ "model" ] }, "name": { "type": "string", "example": "A5S Async v1" }, "type": { "type": "string", "enum": [ "async", "streaming", "sync" ], "description": "`sync`: the result is the response (AirCaps Speaker ID-v1)." }, "task": { "type": "string", "enum": [ "diarization", "speaker_identification" ], "description": "Models that do not transcribe: speaker diarization (AirCaps Diarization-v1) or speaker identification (AirCaps Speaker ID-v1)." }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ], "description": "Transcription models only." }, "endpoint": { "type": "string", "example": "/v1/transcripts" }, "access": { "type": "string", "enum": [ "by_request" ], "description": "Present when the model is enabled per account on request." } } }, "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 all models (5 hours free). To raise it, [talk to sales](https://aircaps.ai/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-small-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" } } }, "aircaps-diarization-v1": { "type": "object", "description": "Shares the asynchronous job limits with A5S Async v1.", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "async" ] }, "enabled": { "type": "boolean", "description": "Whether this account may use the model (enabled on request)." }, "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" } } }, "aircaps-speaker-id-v1": { "type": "object", "description": "Synchronous: one clip per request.", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "sync" ] }, "enabled": { "type": "boolean", "description": "Whether this account may use the model (enabled on request)." }, "max_requests_per_minute": { "type": "integer", "description": "Enrollments and identifications together." }, "max_clip_duration_seconds": { "type": "integer", "example": 120 }, "max_speakers": { "type": "integer", "example": 1000 }, "max_enrollments_per_speaker": { "type": "integer", "example": 20 }, "speakers": { "type": "integer", "description": "Speakers the account has now." } } } } } } }, "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": { "allOf": [ { "type": "object", "properties": { "requests": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "audio_seconds": { "type": "number" } } }, { "type": "object", "properties": { "avg_turnaround_seconds": { "type": [ "number", "null" ], "description": "A5S Async v1 only." } } } ] }, "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", "null" ], "description": "Also in the `x-request-id` header. Include it when contacting support. `null` on 502/504 from the edge." } } } } }, "WebhookEvent": { "type": "object", "required": [ "event", "id", "status" ], "properties": { "event": { "type": "string", "enum": [ "transcript.completed", "transcript.failed", "diarization.completed", "diarization.failed" ] }, "id": { "type": "string", "description": "Transcript or diarization ID." }, "status": { "type": "string", "enum": [ "completed", "error" ] }, "metadata": { "type": [ "object", "null" ], "description": "Your `metadata`." } } } } } }