For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see For full documentation content, see For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at

Topic Detection

Label topics that are mentioned in your audio file

For the complete documentation index, see llms.txt

cURL quickstart — Topic Detection (IAB Taxonomy)

bash

# Step 1: Submit transcription with iab_categories enabled
curl  \
  --header "Authorization: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "audio_url": "",
    "speech_models": ["universal-3-pro", "universal-2"],
    "language_detection": true,
    "iab_categories": true
  }'

# Step 2: Poll for result (replace TRANSCRIPT_ID)
curl  \
  --header "Authorization: YOUR_API_KEY"

The response includes iab_categories_result with per-segment topics, relevance scores, and a summary.

US & EU

The Topic Detection model lets you identify different topics in the transcript. The model uses the IAB Content Taxonomy, a standardized language for content description which consists of 698 comprehensive topics.

Quickstart

Enable Topic Detection by setting iab_categories to true in the JSON payload.

python

import requests
import time

base_url = ""

headers = {
    "authorization": "<YOUR_API_KEY>"
}

with open("./local_file.mp3", "rb") as f:
    response = requests.post(base_url + "/v2/upload",
                            headers=headers,
                            data=f)

upload_url = response.json()["upload_url"]

data = {
    "audio_url": upload_url, # You can also use a URL to an audio or video file on the web
    "speech_models": ["universal-3-pro", "universal-2"],
    "language_detection": True,
    "iab_categories": True
}

url = base_url + "/v2/transcript"
response = requests.post(url, json=data, headers=headers)

transcript_id = response.json()['id']
polling_endpoint = base_url + "/v2/transcript/" + transcript_id

print(f"Transcript ID: {transcript_id}")

while True:
    transcription_result = requests.get(polling_endpoint, headers=headers).json()

    if transcription_result['status'] == 'completed':
      # Get the parts of the transcript that were tagged with topics
      for result in transcription_result['iab_categories_result']['results']:
        print(result['text'])
        print(f"Timestamp: {result['timestamp']['start']} - {result['timestamp']['end']}")

        for label in result['labels']:
          print(f"{label['label']} ({label['relevance']})")

      # Get a summary of all topics in the transcript
      for topic, relevance in transcription_result['iab_categories_result']['summary'].items():
        print(f"Audio is {relevance * 100}% relevant to {topic}")
      break
    elif transcription_result['status'] == 'error':
        raise RuntimeError(f"Transcription failed: {transcription_result['error']}")
    else:
        time.sleep(3)

Enable Topic Detection by setting iab_categories to True in the transcription parameters.

python

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

# audio_file = "./local_file.mp3"
audio_file = ""

config = aai.TranscriptionConfig(
    speech_models=["universal-3-pro", "universal-2"],
    language_detection=True,
    iab_categories=True
)

transcript = aai.Transcriber().transcribe(audio_file, config)
print(f"Transcript ID: {transcript.id}")

# Get the parts of the transcript that were tagged with topics
for result in transcript.iab_categories.results:
    print(result.text)
    print(f"Timestamp: {result.timestamp.start} - {result.timestamp.end}")
    for label in result.labels:
        print(f"{label.label} ({label.relevance})")

# Get a summary of all topics in the transcript
for topic, relevance in transcript.iab_categories.summary.items():
    print(f"Audio is {relevance * 100}% relevant to {topic}")

Enable Topic Detection by setting iab_categories to true in the JSON payload.

javascript

import fs from "fs-extra";

const baseUrl = "";

const headers = {
  authorization: "<YOUR_API_KEY>",
};

const path = "./my-audio.mp3";
const audioData = await fs.readFile(path);
let res = await fetch(`${baseUrl}/v2/upload`, {
  method: "POST",
  headers,
  body: audioData,
});
if (!res.ok) throw new Error(`Error: ${res.status}`);
const uploadResponse = await res.json();
const uploadUrl = uploadResponse.upload_url;

const data = {
  audio_url: uploadUrl, // You can also use a URL to an audio or video file on the web
  speech_models: ["universal-3-pro", "universal-2"],
  language_detection: true,
  iab_categories: true,
};

const url = `${baseUrl}/v2/transcript`;
res = await fetch(url, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(data),
});
if (!res.ok) throw new Error(`Error: ${res.status}`);
const response = await res.json();

const transcriptId = response.id;
console.log("Transcript ID: ", transcriptId);

const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`;

while (true) {
  res = await fetch(pollingEndpoint, { headers });
  if (!res.ok) throw new Error(`Error: ${res.status}`);
  const transcriptionResult = await res.json();

  if (transcriptionResult.status === "completed") {
    // Get the parts of the transcript that were tagged with topics
    for (const result of transcriptionResult.iab_categories_result.results) {
      console.log(result.text);
      console.log(
        `Timestamp: ${result.timestamp.start} - ${result.timestamp.end}`
      );

      for (const label of result.labels) {
        console.log(`${label.label} (${label.relevance})`);
      }
    }
    // Get a summary of all topics in the transcript
    for (const [topic, relevance] of Object.entries(
      transcriptionResult.iab_categories_result.summary
    )) {
      console.log(`Audio is ${relevance * 100} relevant to ${topic}`);
    }
    break;
  } else if (transcriptionResult.status === "error") {
    throw new Error(`Transcription failed: ${transcriptionResult.error}`);
  } else {
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

Enable Topic Detection by setting iab_categories to true in the transcription config.

javascript

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({
  apiKey: "<YOUR_API_KEY>",
});

// const audioFile = './local_file.mp3'
const audioFile = "";

const params = {
  audio: audioFile,
  speech_models: ["universal-3-pro", "universal-2"],
  language_detection: true,
  iab_categories: true,
};

const run = async () => {
  const transcript = await client.transcripts.transcribe(params);
  console.log("Transcript ID: ", transcript.id);

  // Get the parts of the transcript that were tagged with topics
  for (const result of transcript.iab_categories_result.results) {
    console.log(result.text);
    console.log(
      `Timestamp: ${result.timestamp?.start} - ${result.timestamp?.end}`
    );
    for (const label of result.labels) {
      console.log(`${label.label} (${label.relevance})`);
    }
  }

  // Get a summary of all topics in the transcript
  for (const [topic, relevance] of Object.entries(
    transcript.iab_categories_result.summary
  )) {
    console.log(`Audio is ${relevance * 100} relevant to ${topic}`);
  }
};

run();

Example output

plain

Smoke from hundreds of wildfires in Canada is triggering air quality alerts throughout the US. Skylines...
Timestamp: 250 - 28920
Home&Garden>IndoorEnvironmentalQuality (0.9881)
NewsAndPolitics>Weather (0.5561)
MedicalHealth>DiseasesAndConditions>LungAndRespiratoryHealth (0.0042)
...
Audio is 100.0% relevant to NewsAndPolitics>Weather
Audio is 93.78% relevant to Home&Garden>IndoorEnvironmentalQuality
...

Check out this cookbook Custom Topic Tags for an example of how to use LLM Gateway to create custom topic tags.

API reference

Request

bash

curl  \
--header "Authorization: <YOUR_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "audio_url": "YOUR_AUDIO_URL",
  "iab_categories": true
}'

Key	Type	Description
`iab_categories`	boolean	Enable Topic Detection.

Response

Key	Type	Description
`iab_categories_result`	object	The result of the Topic Detection model.
`iab_categories_result.status`	string	Is either `success`, or `unavailable` in the rare case that the Topic Detection model failed.
`iab_categories_result.results`	array	An array of the Topic Detection results.
`iab_categories_result.results[i].text`	string	The text in the transcript in which the i-th instance of a detected topic occurs.
`iab_categories_result.results[i].labels[j].relevance`	number	How relevant the j-th detected topic is in the i-th instance of a detected topic.
`iab_categories_result.results[i].labels[j].label`	string	The IAB taxonomical label for the j-th label of the i-th instance of a detected topic, where `>` denotes supertopic/subtopic relationship.
`iab_categories_result.results[i].timestamp.start`	number	The starting time in the audio file at which the i-th detected topic instance is discussed.
`iab_categories_result.results[i].timestamp.end`	number	The ending time in the audio file at which the i-th detected topic instance is discussed.
`iab_categories_result.summary`	object	Summary where each property is a detected topic.
`iab_categories_result.summary.topic`	number	The overall relevance of topic to the entire audio file.

The response also includes the request parameters used to generate the transcript.

Frequently asked questions

The Topic Detection model uses natural language processing and machine learning to identify related words and phrases even if they are misspelled or unrecognized. However, the accuracy of the detection may depend on the severity of the misspelling or the obscurity of the word.

No, the Topic Detection model can only identify entities that are part of the IAB Taxonomy. The model is optimized for contextual targeting use cases, so using the predefined IAB categories ensures the most accurate results.

There could be several reasons why you aren't getting any topic predictions for your audio file. One possible reason is that the audio file doesn't contain enough relevant content for the model to analyze. Additionally, the accuracy of the predictions may be affected by factors such as background noise, low-quality audio, or a low confidence threshold for topic detection. It's recommended to review and adjust the model's configuration parameters and to provide high-quality, relevant audio files for analysis.

There could be several reasons why you're getting inaccurate or irrelevant topic predictions for your audio file. One possible reason is that the audio file contains background noise or other non-relevant content that's interfering with the model's analysis. Additionally, the accuracy of the predictions may be affected by factors such as low-quality audio, a low confidence threshold for topic detection, or insufficient training data. It's recommended to review and adjust the model's configuration parameters, to provide high-quality, relevant audio files for analysis, and to consider adding additional training data to the model.

As of 2023, AssemblyAI is a partner with the Interactive Advertising Bureau (IAB), a certification and community for advertising across the internet. AssemblyAI built Topic Detection using the IAB Taxonomy, which is a blueprint of the approximately 700 topics used to categorize ads.

Topic Detection ​

Quickstart ​

Example output ​

API reference ​

Request ​

Response ​