> ## 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. # Create a diarization > 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`. ## OpenAPI ````yaml POST /v1/diarizations 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/diarizations: post: tags: - Diarizations 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`. 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 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 components: schemas: 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 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. 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. 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 Segment: type: object required: - speaker - start - end properties: speaker: type: string description: >- Speaker label (`speaker_0`, `speaker_1`, … 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 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.