Audio Reconstruction | Hume API

The audio reconstruction feature allows you to listen to past conversations by stitching together all audio snippets from a Chat—including both user inputs and EVI’s responses—into a single audio file. This can be useful for reviewing interactions, quality assurance, or integrating playback functionality into your application.

If data retention is disabled, Chat history will not be recorded, and previous Chat data and audio reconstruction will not be retrievable.

How audio reconstruction works

The audio reconstruction process combines individual audio clips into a continuous file. Here are some important considerations:

• Storage duration: Reconstructed audio files are stored indefinitely.
• Signed URL expiration: The signed_audio_url expires after 60 minutes. If it expires before you download the file, you can generate a new URL by making another API request.
• No merging of Chats: The API does not support combining multiple Chats within a Chat Group into a single audio file.
• Asynchronous process: Audio reconstruction is performed in the background. The time required depends on the conversation’s length and system load.

Audio reconstruction statuses

The status of an audio reconstruction request will indicate its progress:

• QUEUED: The reconstruction job is waiting to be processed.
• IN_PROGRESS: The reconstruction is currently being processed.
• COMPLETE: The audio reconstruction is finished and ready for download.
• ERROR: An error occurred during the reconstruction process.
• CANCELED: The reconstruction job has been canceled.

Fetching reconstructed audio for a Chat

To fetch the reconstructed audio for a specific Chat, use the following endpoint: /chats/{chat_id}/audio.

cURLTypeScriptPython

# Replace {chat_id} with your Chat ID
# Ensure your API key is set in the HUME_API_KEY environment variable
curl -X GET "https://api.hume.ai/v0/evi/chats/{chat_id}/audio" \
    -H "X-Hume-Api-Key: $HUME_API_KEY" \
    -H "Accept: application/json"

Example response (audio reconstruction initiated):

{
  "id": "470a49f6-1dec-4afe-8b61-035d3b2d63b0",
  "user_id": "e6235940-cfda-3988-9147-ff531627cf42",
  "status": "QUEUED",
  "filename": null,
  "modified_at": 1729875432555,
  "signed_audio_url": null,
  "signed_url_expiration_timestamp_millis": null
}

If audio reconstruction for a Chat or Chat Group hasn’t already occurred, calling the respective endpoint will automatically add the audio reconstruction process to our job queue.

Fetching reconstructed audio for a Chat Group

To fetch a paginated list of reconstructed audio for Chats within a Chat Group, use the following endpoint: /chat_groups/{chat_group_id}/audio.

cURLTypeScriptPython

# Replace {chat_group_id} with your Chat Group ID
# Include pagination parameters as needed
# Ensure your API key is set in the HUME_API_KEY environment variable
curl -X GET "https://api.hume.ai/v0/evi/chat_groups/{chat_group_id}/audio?page_number=1&page_size=10&ascending_order=false" \
    -H "X-Hume-Api-Key: $HUME_API_KEY" \
    -H "Accept: application/json"

{
  "id": "369846cf-6ad5-404d-905e-a8acb5cdfc78",
  "user_id": "e6235940-cfda-3988-9147-ff531627cf42",
  "num_chats": 1,
  "page_number": 0,
  "page_size": 10,
  "total_pages": 1,
  "pagination_direction": "DESC",
  "audio_reconstructions_page": [
    {
      "id": "470a49f6-1dec-4afe-8b61-035d3b2d63b0",
      "user_id": "e6235940-cfda-3988-9147-ff531627cf42",
      "status": "QUEUED",
      "filename": null,
      "modified_at": 1729875432555,
      "signed_audio_url": null,
      "signed_url_expiration_timestamp_millis": null
    }
  ]
}

Polling for completion

Since the reconstruction process is asynchronous, you can poll the endpoint to check the status field until it changes to COMPLETE. Once the status is COMPLETE, the signed_audio_url and signed_url_expiration fields will be populated.

{
  "id": "470a49f6-1dec-4afe-8b61-035d3b2d63b0",
  "user_id": "e6235940-cfda-3988-9147-ff531627cf42",
  "status": "COMPLETE",
  "filename": "e6235940-cfda-3988-9147-ff531627cf42/470a49f6-1dec-4afe-8b61-035d3b2d63b0/reconstructed_audio.mp4",
  "modified_at": 1729875432555,
  "signed_audio_url": "https://storage.googleapis.com/...etc.",
  "signed_url_expiration_timestamp_millis": 1730232816964
}

Downloading the audio file

After the reconstruction is complete, you can download the audio file using the signed_audio_url. The following cURL command saves the audio file using the original filename provided by the server:

# Replace {signed_audio_url} with the URL from the API response
curl -O "{signed_audio_url}"