> ## Documentation Index > Fetch the complete documentation index at: https://aircaps.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Identify a speaker > 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). ## OpenAPI ````yaml POST /v1/speakers/identify openapi: 3.1.0 info: title: AirCaps AI API version: 1.0.0 description: >- Speech-to-text: A5S Async v1 (REST; English, Spanish, French, German, Portuguese, Hindi, Japanese, Korean and Chinese) and A5S Small V2 Streaming (WebSocket; English). 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/speakers/identify: post: tags: - Speakers 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). operationId: identifySpeaker 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 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ía 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 x-codeSamples: - lang: bash label: cURL source: |- curl "https://api.aircaps.com/v1/speakers/identify" \ -H "Authorization: Bearer $AIRCAPS_API_KEY" \ -H "Content-Type: audio/wav" \ --data-binary @clip.wav - lang: python label: Python source: |- import os, requests with open("clip.wav", "rb") as f: r = requests.post("https://api.aircaps.com/v1/speakers/identify", headers={"Authorization": f"Bearer {os.environ['AIRCAPS_API_KEY']}", "Content-Type": "audio/wav"}, data=f) print(r.json()["results"][0]) components: schemas: 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ía 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 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. securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key: `Authorization: Bearer aircaps_sk_...`' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.