Hume AI Python SDK

Paginated requests return a SyncPager or AsyncPager. You can iterate over the items directly (which handles pagination automatically), iterate page-by-page, or manually control the next page.

from hume.client import HumeClient

client = HumeClient(api_key="YOUR_API_KEY")

# 1. Automatic iteration (generator over items)
for tool in client.empathic_voice.tools.list_tools():
    print(tool)

# 2. Page-by-page iteration
for page in client.empathic_voice.tools.list_tools().iter_pages():
    print(page.items)

# 3. Manual pagination
pager = client.empathic_voice.tools.list_tools()
print(pager.items) # First page
pager = pager.next_page()
print(pager.items) # Next page

To interact with Hume APIs, initialize a HumeClient with your API key. The SDK uses namespaces to organize different product APIs like empathic_voice and tts.

from hume.client import HumeClient

client = HumeClient(api_key="YOUR_API_KEY")
# Access specific APIs via namespaces
client.empathic_voice.configs.list_configs()
client.tts. # APIs specific to Text-to-speech

You can install the hume package using pip, poetry, or uv.

pip install hume
# or
poetry add hume
# or
uv add hume

The ChatsClient (and its asynchronous counterpart AsyncChatsClient) allows you to retrieve historical chat records, individual chat events, and reconstructed audio from previous Empathic Voice conversations.

Key capabilities include:

• Listing Chats: Retrieve a paginated list of all chats, optionally filtered by config_id or status.
• Listing Chat Events: Retrieve a paginated list of specific events within a single chat using its UUID.
• Retrieving Audio: Fetch the reconstructed audio for a specific chat session.

Both clients support pagination via page_number (zero-indexed) and page_size (1-100).

from hume import HumeClient

client = HumeClient(api_key="YOUR_API_KEY")
# Access the chats client via the empathic_voice namespace
chats = client.empathic_voice.chats

The ToolsClient (and its asynchronous counterpart AsyncToolsClient) provides a programmatic interface to manage tools used by Empathic Voice Interface (EVI). Tools can be built-in or user-defined and are used for function calling within EVI configurations.

Key capabilities include:

• Creating new tools with JSON schema parameters.
• Listing existing tools and their specific versions.
• Updating tool names, descriptions, or creating new versions.
• Deleting tools and specific versions.

Note: Tools, Configs, Custom Voices, and Prompts are versioned to support iterative development.

from hume import HumeClient

client = HumeClient(api_key="YOUR_API_KEY")
# Access tools via the empathic_voice namespace
tools = client.empathic_voice.tools

The ConfigsClient (synchronous) and AsyncConfigsClient (asynchronous) allow you to manage Empathic Voice configurations. You can create new configurations, manage multiple versions of a configuration, list existing configs, and delete them.

Configs are versioned, supporting iterative development. Each update to a configuration increments its version number. Supported EVI versions for creating configurations are 3 and 4-mini.

from hume import HumeClient

client = HumeClient(api_key="YOUR_API_KEY")
# Access the configs client via the empathic_voice namespace
configs = client.empathic_voice.configs

The HumeClient and AsyncHumeClient allow you to specify the target server using either a base_url string or a HumeClientEnvironment object.

Using base_url: Providing a base_url automatically generates a HumeClientEnvironment. The SDK handles protocol conversion:

• http:// becomes ws:// for EVI, TTS, and Stream endpoints.
• https:// becomes wss:// for EVI, TTS, and Stream endpoints.
• Hostnames without a protocol default to https://.

Using environment: If you have a specific HumeClientEnvironment object (e.g., from hume.environment), you can pass it directly to the environment parameter.

Constraint: You must use either base_url or environment, not both.

Configs, Prompts, Custom Voices, and Tools in the Empathic Voice (EVI) ecosystem are versioned.

• Versioning System: Supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed.
• Version Numbers: Represented as integer values. Each update to a Config increments its version number.
• Granularity: You can manage the entire Config (via delete_config) or target specific versions (via delete_config_version, get_config_version, or update_config_description).

Hume uses a versioning system for Tools, Configs, Custom Voices, and Prompts.

• Purpose: Supports iterative development, allowing you to progressively refine assets and revert to previous versions if needed.
• Mechanism: Version numbers are integer values representing different iterations. Each update to an asset increments its version number.
• Usage: When calling methods like get_tool_version, delete_tool_version, or update_tool_description, you must specify both the id (UUID) and the specific version (int) you wish to act upon.

A Chat is a single session from opening to closing a WebSocket connection. A Chat Group is a series of resumed Chats that represent a single conversation spanning multiple sessions.

To preserve context across sessions (e.g., after a network disconnection or at a later time), you must use the resumed_chat_group_id parameter in the connect() method.

You can obtain a chat_group_id in three ways:

1. Chat Metadata: Received via a message upon establishing a WebSocket connection.
2. List Chats endpoint: Using the GET /v0/evi/chats endpoint.
3. List Chat Groups endpoint: Using the GET /v0/evi/chat_groups endpoint.

The ChatGroupsClient (and its async counterpart AsyncChatGroupsClient) provides methods to manage and retrieve information about Empathic Voice (EVI) chat groups. You can list available chat groups, retrieve specific group details including associated chats, fetch audio reconstructions for chats within a group, and list chat events.

Both sync and async clients support pagination using page_number (zero-indexed) and page_size (1-100).

from hume import HumeClient

client = HumeClient(api_key="YOUR_API_KEY")
# Access chat groups via the empathic_voice namespace
chat_groups = client.empathic_voice.chat_groups