AssemblyAI Getting Started: Quickstart Guide (2026)

Getting started overview

This guide outlines the process for new users to begin utilizing the AssemblyAI API for speech-to-text transcription and audio intelligence features. It covers account creation, API key management, and the execution of a basic asynchronous transcription request. AssemblyAI supports various programming languages through official SDKs, including Python and Node.js, and offers direct HTTP API access for other environments. The platform provides a free tier for initial development and testing, allowing users to process up to 3 hours of audio per month without charge.

The core process for initiating development with AssemblyAI involves:

1. Account Creation: Registering for a free AssemblyAI account.
2. API Key Retrieval: Locating your unique API key in the developer dashboard.
3. First API Call: Submitting an audio file for transcription using an SDK or direct HTTP request.
4. Result Retrieval: Polling for the transcription results.

AssemblyAI's documentation details the range of features available, from basic transcription to advanced audio intelligence capabilities like summarization, sentiment analysis, and speaker diarization. Developers can use the AssemblyAI API reference for specific endpoint details and request/response structures.

Create an account and get keys

To access the AssemblyAI API, you must first create an account and obtain an API key. This key authenticates your requests and links them to your usage allowance.

Account Registration

1. Navigate to the AssemblyAI homepage.
2. Click the 'Sign up' or 'Get Started for Free' button.
3. Complete the registration form, providing a valid email address and creating a password.
4. Verify your email address, if prompted, by following the instructions in the confirmation email.

API Key Retrieval

After successfully creating and logging into your account, your API key will be accessible from your developer dashboard:

1. Log in to your AssemblyAI dashboard.
2. Your API key is typically displayed prominently on the dashboard's main page or within a 'Developer Settings' or 'API Keys' section.
3. Copy this key. It is a unique string that must be included in the Authorization header of every API request you make. Treat your API key as sensitive information; do not expose it in client-side code or public repositories. For server-side applications, use environment variables or a secure configuration management system to store the key, following practices similar to those outlined in Google Cloud API key best practices.

AssemblyAI provides a free tier that includes 3 hours of transcription per month. Exceeding this limit will incur charges based on the pay-as-you-go model. Review the pricing page for detailed information on costs for standard transcription, real-time transcription, and audio intelligence features.

Your first request

This section demonstrates how to make your first asynchronous transcription request using a publicly accessible audio file. We will provide examples in both Python and Node.js, which are among AssemblyAI's primary language examples.

Asynchronous Transcription Overview

AssemblyAI's asynchronous transcription process typically involves two main steps:

1. Upload/Submit: Send your audio file (or a URL to an audio file) to the AssemblyAI API. The API responds immediately with an ID for the transcription job.
2. Poll for Results: Periodically check the status of the transcription job using the provided ID until it completes. Once complete, the results, including the transcript and any requested audio intelligence features, are returned.

Example: Python SDK

First, install the AssemblyAI Python SDK:

pip install assemblyai

Then, use the following Python code to submit an audio file for transcription and retrieve the results:

import assemblyai as aai
import os
import time

# Your API key is available in your AssemblyAI dashboard
aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY") # Recommended to use environment variable

# Or directly set it for testing purposes (not recommended for production)
# aai.settings.api_key = "YOUR_ASSEMBLYAI_API_KEY"

# URL of the audio file to transcribe
audio_url = "https://storage.googleapis.com/aai-web-samples/5_9_2024_W_C_U_R1_C1.mp3"

print(f"Submitting audio for transcription: {audio_url}")

transcriber = aai.Transcriber()

# Configure transcription request (optional, can add more features)
config = aai.TranscriptionConfig(
    speaker_labels=True,
    sentiment_analysis=True
)

# Submit the audio file
# This method handles polling internally for simplicity
transcript = transcriber.transcribe(audio_url, config)

if transcript.status == aai.TranscriptStatus.error:
    print(f"Error: {transcript.error}")
else:
    print(f"Transcript: {transcript.text}")
    if transcript.sentiment_analysis_results:
        print("Sentiment Analysis Results:")
        for result in transcript.sentiment_analysis_results:
            print(f" - Text: '{result.text}' | Sentiment: {result.sentiment} | Confidence: {result.confidence:.2f}")
    if transcript.utterances:
        print("Speaker Labels (Utterances):")
        for utterance in transcript.utterances:
            print(f" - Speaker {utterance.speaker}: {utterance.text}")

Example: Node.js SDK

First, install the AssemblyAI Node.js SDK:

npm install assemblyai

Then, use the following Node.js code:

const assemblyai = require("assemblyai");

// Your API key is available in your AssemblyAI dashboard
const client = new assemblyai.AssemblyAI({
  apiKey: process.env.ASSEMBLYAI_API_KEY, // Recommended to use environment variable
  // Or directly set it for testing purposes (not recommended for production)
  // apiKey: "YOUR_ASSEMBLYAI_API_KEY",
});

const audioUrl = "https://storage.googleapis.com/aai-web-samples/5_9_2024_W_C_U_R1_C1.mp3";

async function transcribeAudio() {
  try {
    console.log(`Submitting audio for transcription: ${audioUrl}`);

    // Configure transcription request
    const config = {
      speakerLabels: true,
      sentimentAnalysis: true,
    };

    // Submit the audio file
    // The transcribe() method handles polling internally
    const transcript = await client.transcripts.transcribe(audioUrl, config);

    if (transcript.status === "error") {
      console.error(`Error: ${transcript.error}`);
    } else {
      console.log(`Transcript: ${transcript.text}`);
      if (transcript.sentimentAnalysisResults) {
        console.log("Sentiment Analysis Results:");
        transcript.sentimentAnalysisResults.forEach(result => {
          console.log(` - Text: '${result.text}' | Sentiment: ${result.sentiment} | Confidence: ${result.confidence.toFixed(2)}`);
        });
      }
      if (transcript.utterances) {
        console.log("Speaker Labels (Utterances):");
        transcript.utterances.forEach(utterance => {
          console.log(` - Speaker ${utterance.speaker}: ${utterance.text}`);
        });
      }
    }
  } catch (error) {
    console.error(`Transcription failed: ${error.message}`);
  }
}

transcribeAudio();

Replace YOUR_ASSEMBLYAI_API_KEY with your actual API key, or preferably, set it as an environment variable named ASSEMBLYAI_API_KEY.

Common next steps

After successfully performing your first transcription, consider exploring the following aspects of the AssemblyAI platform:

• Local File Upload: Instead of using a public URL, learn how to upload local audio files directly to AssemblyAI for transcription. This is essential for handling sensitive or proprietary audio data.
• Real-time Transcription: Investigate AssemblyAI's real-time streaming transcription API for applications requiring immediate speech-to-text conversion, such as live call centers or voice assistants.
• Audio Intelligence Features: Experiment with additional audio intelligence models beyond basic transcription, such as summarization, content moderation, topic detection, and entity detection. These features can be enabled via configuration parameters in your transcription requests. Consult the AssemblyAI Audio Intelligence documentation for a full list of capabilities.
• Webhook Callbacks: For asynchronous tasks, use webhooks to receive notifications when a transcription job is complete, rather than continuously polling the API. This can improve efficiency and reduce API calls.
• Error Handling: Implement robust error handling in your application to manage API rate limits, invalid requests, and other potential issues.
• SDK Exploration: If you are working in a different language, explore the other available SDKs for Ruby, Go, Java, and C#.
• Security Best Practices: Review security guidelines for managing API keys and handling sensitive audio data, aligning with general API security recommendations like those from Twilio's API security overview.

Troubleshooting the first call

When making your initial API call, several common issues can arise. Here are some troubleshooting steps:

• Invalid API Key: Ensure your API key is correctly copied and included in the Authorization header. A common mistake is including extra spaces or incorrect characters. Verify it matches the key in your AssemblyAI dashboard exactly.
• Missing API Key: Confirm that the Authorization header is present in your request. Without it, the API will reject your call.
• Incorrect Endpoint: Double-check that you are sending requests to the correct AssemblyAI API endpoint for asynchronous transcription, typically https://api.assemblyai.com/v2/transcript. Refer to the API documentation for exact endpoint URLs.
• Audio File Accessibility (HTTP URLs): If using an audio file URL, ensure that the URL is publicly accessible and directly points to an audio file (e.g., .mp3, .wav). The URL should not require authentication or present a CAPTCHA. Test the URL in a browser or with curl to confirm direct access.
• Audio File Format/Size: Verify that your audio file adheres to AssemblyAI's supported audio formats and size limits. Extremely large files or unsupported formats can cause errors.
• Network Issues: Check your internet connection. Temporary network interruptions can prevent successful API calls.
• Rate Limiting: While less common for a first call, if you are making many rapid requests, you might encounter rate limiting. The AssemblyAI rate limit documentation provides details on these limits.
• SDK Specific Errors: If using an SDK, consult the specific SDK's documentation or error messages. Ensure the SDK is up-to-date.
• Server-side Logs: If you have access to your server logs, check for any error messages related to the API call.
• AssemblyAI Status Page: Check the AssemblyAI status page for any ongoing service disruptions or outages.