How do I get my Hume AI API key?

After creating and verifying your Hume AI account, log in to your developer dashboard. Navigate to the 'API Keys' or 'Settings' section to generate and retrieve your unique API key. Ensure you store it securely.

Is there a free tier for Hume AI?

Yes, Hume AI offers a free tier that allows developers to begin exploring its capabilities without an upfront cost. Specific usage limits apply to the free tier.

What authentication method does Hume AI use?

Hume AI primarily uses API keys for authentication. Your API key is passed in the 'X-Hume-Api-Key' HTTP header with each request to authenticate your application.

Which programming languages are supported by Hume AI SDKs?

Hume AI provides official SDKs for Python and JavaScript, which simplify interaction with their APIs and handle underlying HTTP requests and authentication.

How do I troubleshoot a 401 Unauthorized error with Hume AI?

A 401 error typically indicates an issue with your API key. Verify that your 'X-Hume-Api-Key' header contains the correct and complete API key, without any typos or extraneous characters. Also, confirm the key is active in your Hume AI dashboard.

Where can I find the official Hume AI API reference documentation?

The official API reference documentation, including details for the Empathic Voice Interface and Expression Measurement APIs, is available on the Hume AI documentation portal, specifically at their Empathic Voice Interface API reference page.

Does Hume AI support real-time processing or only batch processing?

Hume AI supports both batch processing (e.g., for Expression Measurement API media analysis) and real-time interfaces, particularly with its Empathic Voice Interface (EVI), which is designed for live conversational AI applications.

Hume AI Getting Started: API Keys & First Request (2026)

Getting started overview

This guide outlines the process for developers to initiate work with the Hume AI platform, focusing on account creation, credential management, and executing an initial API request. Hume AI provides programmatic access to its emotion AI capabilities through distinct APIs, including the Expression Measurement API for analyzing facial and vocal expressions, and the Empathic Voice Interface (EVI) for real-time empathetic AI interactions. Understanding the prerequisites and authentication mechanisms is fundamental for successful integration.

The initial setup involves registering a Hume AI account, generating API keys, and configuring a development environment. Subsequent steps detail how to construct and send a basic request, demonstrating successful communication with the Hume AI endpoints. This page focuses on direct API interaction, though official Hume AI documentation provides resources for Python and JavaScript SDKs. Completion of these steps establishes a foundational understanding for further development with Hume AI's services.

Quick reference steps

Step	What to do	Where
1. Account Creation	Register for a Hume AI account.	Hume AI pricing page or sign-up flow
2. API Key Generation	Generate your API key(s) from the dashboard.	Hume AI developer dashboard (post-login)
3. Environment Setup	Install necessary tools (e.g., cURL, Python, Node.js).	Local development environment
4. First Request	Send an authenticated request to a Hume AI endpoint.	Terminal or code editor
5. Verify Response	Confirm a successful response from the API.	Terminal or code editor output

Create an account and get keys

Access to Hume AI's APIs requires an active account and valid API credentials. The process for obtaining these involves registration and then navigating the developer dashboard.

Account registration

Navigate to the Hume AI website: Open your web browser and go to the official Hume AI homepage.
Initiate sign-up: Look for a "Sign Up" or "Get Started" button, typically located in the top right corner or prominent on the Hume AI pricing page. The Hume AI platform offers a free tier, allowing initial exploration without immediate financial commitment.
Complete registration form: Provide the requested information, which typically includes your email address, a secure password, and agreement to the terms of service. Account verification, often via email, may be required.

API key generation

Log in to the dashboard: After successful registration and verification, log in to your Hume AI developer dashboard using your newly created credentials.
Locate API key section: Within the dashboard, identify a section labeled "API Keys," "Developers," or "Settings." The exact navigation path may vary based on dashboard updates.
Generate a new key: Select the option to generate a new API key. It is common practice to assign a descriptive name to your key (e.g., "Development Environment Key") to aid in management, particularly when multiple keys are in use for different applications or environments. Hume AI API keys are typically long, alphanumeric strings.
Securely store your key: Once generated, the API key will be displayed. Copy this key immediately and store it securely. Best practices recommend using environment variables or a secure secrets management system rather than hardcoding keys directly into your application's source code. For example, Google's API key best practices recommend restricting API key usage and avoiding direct exposure.

Your first request

To confirm that your API key is correctly configured and that you can communicate with the Hume AI platform, perform a simple test request. This example uses cURL for its universality, demonstrating a request to the Expression Measurement API for processing. The Expression Measurement API allows for the analysis of audio, video, or image data to extract emotional expressions.

Prerequisites

cURL: Ensure cURL is installed on your system. Most Unix-like operating systems include cURL by default. For Windows, it can be downloaded and installed.
Hume AI API Key: Your generated API key from the previous step.
Sample Media: For the Expression Measurement API, you will need a small audio file (e.g., a .wav or .mp3) or an image file (e.g., .jpg, .png) to send for analysis. For this example, assume you have an audio file named sample_audio.wav in the same directory where you execute the cURL command.

Example Expression Measurement API request with cURL

This example demonstrates how to upload an audio file for analysis using the Expression Measurement API. Replace YOUR_HUME_AI_API_KEY with your actual API key and ensure sample_audio.wav exists.

curl -X POST "https://api.hume.ai/v0/batch/jobs" \
  -H "X-Hume-Api-Key: YOUR_HUME_AI_API_KEY" \
  -F "json={""models"": {""face"":{}, ""prosody"":{}}, ""job_details"": {""callback_url"": null}}" \
  -F "media=@sample_audio.wav" \
  -H "Content-Type: multipart/form-data"

Explanation of parameters:

-X POST: Specifies the HTTP POST method.
"https://api.hume.ai/v0/batch/jobs": The endpoint for submitting batch jobs to the Expression Measurement API. Note that Hume AI's APIs often use asynchronous processing for media analysis, returning a job ID that you can query later for results.
-H "X-Hume-Api-Key: YOUR_HUME_AI_API_KEY": Sets the X-Hume-Api-Key header for authentication. This is where your API key is passed.
-F "json={...}": Provides a JSON payload as part of a multipart form. This specifies which models (e.g., face for facial expressions, prosody for vocal expressions) to apply and any job-specific details.
-F "media=@sample_audio.wav": Attaches the sample_audio.wav file as part of the multipart form data. The @ prefix tells cURL to read the file from the specified path.
-H "Content-Type: multipart/form-data": Specifies the content type for the request body, essential for file uploads.

Expected response

A successful request to the batch jobs endpoint will typically return a JSON response containing a job_id. This ID is crucial for subsequently retrieving the analysis results, as the processing is asynchronous. An example successful response might look like this:

{
  "job_id": "your-unique-job-id-12345",
  "status": "CREATED"
}

You would then use this job_id to poll another endpoint (e.g., GET /v0/batch/jobs/{job_id}) to check the status and retrieve the completed analysis results once available. Refer to the Hume AI Empathic Voice Interface API reference for specific polling instructions and response structures.

Common next steps

After successfully making your first API call, consider these common next steps to further your integration with Hume AI:

Explore additional API endpoints: Hume AI offers various endpoints beyond batch processing, including real-time interfaces for the Empathic Voice Interface (EVI). Review the Hume AI Empathic Voice Interface API reference for comprehensive details on available services, request formats, and response data structures.
Integrate an SDK: For developers working with Python or JavaScript, utilizing the official Hume AI SDKs can streamline development by abstracting HTTP requests and handling authentication. The SDKs provide idiomatic ways to interact with the API, reducing boilerplate code.
Implement error handling: Develop robust error handling mechanisms in your application to gracefully manage API rate limits, invalid requests, authentication failures, and other potential issues. Understanding HTTP status codes and API-specific error messages is crucial.
Manage API keys securely: Reinforce practices for securing your API keys. Avoid embedding them directly into client-side code or public repositories. Use environment variables, secure configuration files, or a dedicated secrets management service.
Monitor usage and billing: Regularly monitor your API usage through the Hume AI dashboard to stay within your plan's limits and manage costs effectively. Understand the Hume AI pricing structure for various services.
Explore advanced features: Investigate Hume AI's more advanced features, such as custom model configurations, specific emotion detection parameters, or integration with other AI services for comprehensive applications. The Hume AI documentation portal is the primary resource for these details.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting steps:

Check API Key: Ensure your X-Hume-Api-Key header contains the exact API key generated from your Hume AI dashboard. Verify there are no leading or trailing spaces, and that the key has not been truncated.
Verify Endpoint URL: Confirm that the API endpoint URL (e.g., https://api.hume.ai/v0/batch/jobs) is correct and matches the latest Hume AI API reference. Typos in the URL can lead to 404 Not Found errors.
Inspect Request Headers: Ensure all required headers, such as Content-Type: multipart/form-data for file uploads, are correctly set. Missing or malformed headers can result in 400 Bad Request errors.
Review Request Body/Payload: If sending a JSON payload, verify it is well-formed and adheres to the API's schema. Incorrect JSON syntax or missing required fields will cause errors. For multipart requests, confirm the file path (e.g., @sample_audio.wav) is correct and the file exists at that location.
Internet Connectivity: Confirm your development machine has an active internet connection and is not blocked by a firewall from reaching Hume AI's servers.
Check Hume AI Status Page: Occasionally, API issues might stem from service outages. Check the official Hume AI status page (if available, typically linked from their main site or docs) for any reported incidents.
Consult Documentation: Refer to the specific Hume AI documentation for the endpoint you are calling. The documentation provides detailed expected parameters, error codes, and example requests/responses.
Rate Limiting: If you are making many requests in a short period, you might encounter rate limiting (e.g., 429 Too Many Requests). Implement exponential backoff for retries if your application requires frequent calls.
Contact Support: If you have exhausted troubleshooting steps, gather relevant information (request body, headers, full error message, job_id if applicable) and contact Hume AI support for assistance.