---
title: "Identify a speaker"
method: POST
path: "/v1/speakers/identify"
tags: ["Speakers"]
---

# Identify a speaker

`POST /v1/speakers/identify`

## Request

- Base URL: `https://api.aircaps.com`
- URL: `https://api.aircaps.com/v1/speakers/identify`
- Auth: HTTP bearer

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).

## Query parameters

- `speaker_ids` string
- `top_k` integer
- `model` 'aircaps-speaker-id-v1'

## Headers

- `Content-Type` string

## Request body `application/octet-stream`

- string, binary

## Response `200`

The scores.

- SpeakerIdentification
  - `id` string, required: Identification ID (identifies the request; identifications are not stored).
  - `object` 'speaker_identification', required
  - `model` 'aircaps-speaker-id-v1', required
  - `created_at` string, date-time, required
  - `audio_duration` number, required: Seconds of audio in the clip.
  - `speakers_compared` integer, required: Speakers the clip was scored against (before `top_k`).
  - `margin` number, nullable, required: Best `score` minus the second best. `null` with one speaker.
  - `results` object[], required: Best first (ties by speaker ID).
    - `speaker_id` string, required
    - `name` string, nullable, required
    - `score` number, required: 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.
    - `enrollment_scores` object[], required: The clip against each enrollment on its own, in enrollment order.
      - `enrollment_id` string
      - `score` number

## Other responses

- `400`: 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`.
- `401`: Missing or invalid API key. Codes: `unauthorized`.
- `403`: The account may not do this. Codes: `account_suspended`, `account_disabled`, `usage_limit_reached`, `model_access_denied`.
- `404`: A speaker in `speaker_ids` was not found. Codes: `speaker_not_found`.
- `413`: Larger than 100 MB. Codes: `file_too_large`.
- `429`: More requests in the last minute than the account allows. Codes: `rate_limited`.
- `500`: Server error. Safe to retry (use the same Idempotency-Key). Codes: `internal_error`.
- `503`: Temporarily unavailable. Retry after the Retry-After interval. Codes: `service_unavailable`.

---

[API](https://skmtc.dev/aircaps/apis/aircaps-api.md) - [All operations](https://skmtc.dev/aircaps/apis/aircaps-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aircaps/apis/aircaps-api/revisions/442d566f9827?raw)