AIaircaps
Diarizations

Create a diarization

Find who spoke when with AirCaps Diarization-v1 (enabled per account). The job runs asynchronously: poll Get a diarization or pass webhook_url.

post/v1/diarizations

Request

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

Headers

Idempotency-Keystring

Up to 255 characters. Makes retries safe: the same key and body return the original job.

Request body

model'aircaps-diarization-v1'

The model. Any other value returns 400 unsupported_model.

audio_urlstring uri

An http(s) URL to download the audio from (public or presigned), up to 5 GB, resolving to a public address.

file_idstring

An uploaded file, usable by any number of jobs for 24 hours after upload. ID from Create an upload URL or Upload a file.

webhook_urlstring uri

Called with a webhook event when the job finishes.

webhook_auth_header_namestring

Name of a header to add to webhook requests. Requires webhook_url.

webhook_auth_header_valuestring

Value of that header.

metadataobject

Any JSON object up to 16 KB; echoed on the diarization and in webhooks.

Example request

{
  "audio_url": "https://example.com/meeting.mp3",
  "webhook_auth_header_name": "Authorization",
  "metadata": {
    "meeting_id": 42
  }
}

Response

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

idstring 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_atstring date-time required

When the diarization was created (UTC).

started_atstring date-time nullable required

When processing started.

completed_atstring date-time nullable required

When the job finished (completed or error).

audio_urlstring nullable required

The submitted audio_url, if any.

file_idstring nullable required

The submitted file_id, if any.

model'aircaps-diarization-v1' required
audio_durationnumber nullable required

Audio duration in seconds, once known.

metadataobject nullable required

Your metadata, echoed back.

webhook_urlstring nullable required

Webhook target, if any.

webhook_status'pending' | 'delivered' | 'failed' | 'null' nullable required

Webhook delivery state, if webhook_url was set.

webhook_status_codeinteger nullable required

HTTP status of the last webhook delivery.

num_speakersinteger

Completed only. Number of speakers found.

speech_durationnumber

Completed only. Seconds in which anyone speaks.

overlap_durationnumber

Completed only. Seconds in which two or more people speak at once.

Example response

{
  "id": "dia_01k72p0x9h6t3b8r1n4m7q2w5e",
  "object": "diarization",
  "audio_duration": 3600.512,
  "num_speakers": 3,
  "speakers": [
    {
      "id": "speaker_0",
      "speaking_time": 1402.11
    }
  ],
  "segments": [
    {
      "speaker": "speaker_0",
      "start": 0.48,
      "end": 6.12
    }
  ],
  "speech_duration": 1498.27,
  "overlap_duration": 61.44
}

Changes

No recorded changes to this operation across all 1 revision of this API.