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

# Create a speaker

`POST /v1/speakers`

## Request

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

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

## Request body

- CreateSpeakerRequest
  - `model` 'aircaps-speaker-id-v1': Optional. Any other value returns `400 unsupported_model`.
  - `name` string, nullable: Your label for the speaker (whitespace is collapsed). Optional.
  - `metadata` object, nullable: Any JSON object up to 16 KB.

## Response `201`

Created.

- EnrolledSpeaker
  - `id` string, required: Speaker ID.
  - `object` 'speaker', required
  - `name` string, nullable, required: Your label for the speaker.
  - `metadata` object, nullable, required: Your `metadata`.
  - `model` 'aircaps-speaker-id-v1', required
  - `num_enrollments` integer, required
  - `enrolled_duration` number, required: Seconds of enrollment audio in total.
  - `enrollments` SpeakerEnrollment[], required: Oldest first. Only embeddings are stored, never the audio.
    - `id` string, required: Enrollment ID.
    - `object` 'speaker_enrollment', required
    - `speaker_id` string, required
    - `audio_duration` number, required: Seconds of audio in the enrollment clip.
    - `consistency` number, nullable, required: 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.
    - `created_at` string, date-time, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required: Last change to the name, metadata or enrollments.

## Other responses

- `400`: Invalid request. Codes: `invalid_request`, `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`.
- `409`: The account has the maximum number of speakers. Codes: `speaker_limit_reached`.
- `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)