AIaircaps
Transcripts

Create a transcript

Start transcribing audio with A5S Async v1. The job runs asynchronously: poll Get a transcript or pass webhook_url.

post/v1/transcripts

Request

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

Query parameters

waitnumber

Seconds to wait for the transcript to finish before answering (0 to 120). Answers as soon as it finishes, or with its current state when the time is up.

Headers

Idempotency-Keystring

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

Request body

model'a5s-async-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 transcripts for 24 hours after upload. ID from Create an upload URL or Upload a file.

language_codestring

Language of the audio. English only today: en or a regional English code (en-US, en-GB, en-IN, ...); for best results use the one that matches the speakers' locale or accent. The transcript reports en. Any other value returns 400 unsupported_language. Multilingual support is planned.

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 transcript and in webhooks.

timing_mode'phrase' | 'region'

Timestamp style for words and utterances.

keytermsstring[]

Key terms: up to 60 words or short phrases that may be spoken in the audio, such as names, products and jargon (each at most 6 words and 50 characters), to help the model recognize them. The text stays lowercase with numbers spelled out, so a key term appears as spoken: "GPT-4" as "gpt four". See Key terms.

large_meetingboolean

Set to true for recordings with many active speakers, typically more than 7 to 9, such as large team meetings, panels, town halls and hearings. Improves speaker attribution for these recordings and may take a little longer to process. Leave it off for typical meetings and conversations. See Large meetings.

Example request

{
  "audio_url": "https://example.com/meeting.mp3",
  "language_code": "en",
  "webhook_auth_header_name": "Authorization",
  "metadata": {
    "meeting_id": 42
  },
  "speaker_identification": {
    "speaker_ids": [
      "spk_01k73a9x8w7v6u5t4s3r2q1p0n",
      "spk_01k73a7m6n5b4v3c2x1z0l9k8j"
    ],
    "threshold": 0.6
  },
  "keyterms": [
    "AirCaps",
    "Dr. Patel",
    "GPT-4"
  ]
}

Response

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

idstring required

Transcript ID.

object'transcript' required
status'queued' | 'processing' | 'completed' | 'error' required

queued: waiting for a processing slot. processing: being transcribed. completed: result fields present. error: see error.

created_atstring date-time required

When the transcript 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.

language_code'en' required

Language of the transcript (normalised).

model'a5s-async-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.

textstring

Completed only. Full transcript: verbatim, lowercase, no punctuation.

timing_mode'phrase' | 'region'

The timing_mode used.

keytermsstring[]

Only when the transcript was created with keyterms: the list used (duplicates removed).

large_meetingboolean

Only when the transcript was created with large_meeting: true.

Example response

{
  "id": "tr_01k6z3m4q8w7e5r2t1y0u9i8o7",
  "object": "transcript",
  "audio_duration": 3600.512,
  "speakers": [
    {
      "id": "speaker_0",
      "speaking_time": 1402.11,
      "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n",
      "name": "Ana García",
      "score": 0.781,
      "matches": [
        {
          "speaker_id": "spk_01k73a9x8w7v6u5t4s3r2q1p0n",
          "name": "Ana García",
          "score": 0.781
        }
      ],
      "compared_duration": 60
    }
  ],
  "utterances": [
    {
      "speaker": "speaker_0",
      "speaker_name": "Ana García",
      "start": 0.48,
      "end": 6.12,
      "text": "hey good afternoon everybody",
      "words": [
        {
          "text": "hey",
          "start": 0.48,
          "end": 0.71,
          "speaker": "speaker_0"
        }
      ]
    }
  ],
  "words": [
    {
      "text": "hey",
      "start": 0.48,
      "end": 0.71,
      "speaker": "speaker_0"
    }
  ],
  "speaker_identification": {
    "threshold": 0.6,
    "speakers_compared": 12,
    "speakers_identified": 2
  }
}

Changes

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