---
title: "Create a diarization"
method: POST
path: "/v1/diarizations"
tags: ["Diarizations"]
---

# Create a diarization

`POST /v1/diarizations`

## Request

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

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

## Headers

- `Idempotency-Key` string

## Request body

- CreateDiarizationRequest: Provide exactly one of `audio_url` or `file_id`.
  - `model` 'aircaps-diarization-v1': The model. Any other value returns `400 unsupported_model`.
  - `audio_url` string, uri: An http(s) URL to download the audio from (public or presigned), up to 5 GB, resolving to a public address.
  - `file_id` string: 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` string, uri: Called with a [webhook event](/api-reference/objects/webhook-event) when the job finishes.
  - `webhook_auth_header_name` string: Name of a header to add to webhook requests. Requires `webhook_url`.
  - `webhook_auth_header_value` string: Value of that header.
  - `metadata` object: Any JSON object up to 16 KB; echoed on the diarization and in webhooks.

## Response `201`

Created. A retried request with the same `Idempotency-Key` returns the original diarization with `200`.

- Diarization
  - `id` string, required: Diarization ID.
  - `object` 'diarization', required
  - `status` 'queued' | 'processing' | 'completed' | 'error', required: `queued`: waiting for a processing slot. `processing`: being diarized. `completed`: result fields present. `error`: see `error`.
  - `created_at` string, date-time, required: When the diarization was created (UTC).
  - `started_at` string, date-time, nullable, required: When processing started.
  - `completed_at` string, date-time, nullable, required: When the job finished (completed or error).
  - `audio_url` string, nullable, required: The submitted `audio_url`, if any.
  - `file_id` string, nullable, required: The submitted `file_id`, if any.
  - `model` 'aircaps-diarization-v1', required
  - `audio_duration` number, nullable, required: Audio duration in seconds, once known.
  - `metadata` object, nullable, required: Your `metadata`, echoed back.
  - `webhook_url` string, nullable, required: Webhook target, if any.
  - `webhook_status` 'pending' | 'delivered' | 'failed' | 'null', nullable, required: Webhook delivery state, if `webhook_url` was set.
  - `webhook_status_code` integer, nullable, required: HTTP status of the last webhook delivery.
  - `error` JobError, required
    - `code` 'invalid_audio' | 'audio_too_long' | 'file_too_large' | 'download_failed' | 'file_not_found' | 'usage_limit_reached' | 'internal_error' | 'canceled', required: Why the job failed. Failed jobs never count toward usage.
    - `message` string, required: Human-readable detail.
  - `num_speakers` integer: Completed only. Number of speakers found.
  - `speakers` Speaker[]: Completed only. Every speaker, with their speaking time.
    - `id` string, required
    - `speaking_time` number, required: Seconds this speaker talks.
  - `segments` Segment[]: Completed only. Who spoke when, in time order. Overlapping speech appears as overlapping segments of different speakers.
    - `speaker` string, required: Speaker label (`speaker_0`, `speaker_1`, … in order of first speech).
    - `start` number, required: Start time in seconds.
    - `end` number, required: End time in seconds.
  - `speech_duration` number: Completed only. Seconds in which anyone speaks.
  - `overlap_duration` number: Completed only. Seconds in which two or more people speak at once.

## 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`.
- `404`: Not found. Codes: `file_not_found`.
- `409`: Idempotency key reused with a different body. Codes: `idempotency_conflict`.
- `429`: Rate or queue limit reached. Codes: `rate_limited`, `queue_full`.
- `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)