---
title: "Analyze Audio"
method: POST
path: "/v3/audio/analysis"
tags: ["Audio"]
---

# Analyze Audio

`POST /v3/audio/analysis`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/audio/analysis`
- Auth: API key in header `x-api-key`

Find the beats, bar starts and sections of a piece of audio, or describe it, with a Gemini model. The request waits for the answer and returns it. Every time is in seconds from the start of the uploaded WAV and is the model's own estimate, no finer than `time_resolution_seconds`. A capability the model could not answer is left out of the response. Each request is priced at the model's cost for the audio's length plus an allowance for the answer. A request the workspace's API credits cannot cover is refused with 402 `insufficient_credit` before the model runs. The credits are charged before the model runs, and failures are refunded before being recorded. Upload PCM WAV through the asset upload API and pass its asset_id. Send an `Idempotency-Key` header with every request: it is required. Repeating a request with the same key and body returns the original answer without charging again, a duplicate sent while the original is still running gets 409 `request_in_progress`, and the same key with a different body gets 409 `conflict`. Failed requests replay their stored error; use a new key for a new attempt. A pending job older than 30 minutes is refunded on replay, then failed. Recovery requires a later replay; it is not scheduled automatically.

## Headers

- `Idempotency-Key` string, required

## Request body

- AudioAnalysisRequest: The JSON body referencing a finalized audio asset.
  - `version` 1, required: Contract version. Only 1 exists.
  - `capabilities` string[], required: What to analyze: any of `beats`, `downbeats`, `sections`, `describe`, each at most once.
  - `audio` AssetId, required: Asset input via HeyGen asset ID from the asset upload endpoint.
    - `type` 'asset_id', required: Input type discriminator
    - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint

## Response `200`

What the model answered.

- object
  - `data` AudioAnalysisResponse
    - `version` 1, required: Contract version.
    - `source` string, required: The model that answered.
    - `time_resolution_seconds` number, required: The audio frame the model hears. Its times are estimates no finer than this, and usually coarser; snap them to a measured beat grid before cutting to them.
    - `beats` AudioAnalysisTimes
      - `times` number[], required: Times in seconds from the start of the uploaded audio, ascending.
    - `downbeats` AudioAnalysisDownbeats
      - `times` number[], required: Times of the first beat of each bar, in seconds from the start of the uploaded audio, ascending.
      - `meter` integer, nullable: Beats per bar, when the model named one.
    - `sections` AudioAnalysisSections
      - `spans` AudioAnalysisSpan[], required: Sections in order of their start.
        - `start` number, required: Start of the section, in seconds from the start of the uploaded audio.
        - `end` number, required: End of the section, in seconds from the start of the uploaded audio.
        - `label` string, required: What the section is, as the model named it, e.g. `intro`, `verse`, `chorus`.
    - `describe` AudioAnalysisDescribe
      - `text` string, nullable: One or two sentences describing the audio.
      - `tags` AudioAnalysisTag[], required: Tags, strongest first.
        - `label` string, required: A short tag, e.g. a genre, a mood or an instrument.
        - `score` number, required: How strongly the model holds the tag, from 0 to 1. The model's own estimate, not a calibrated probability.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `402`: Insufficient credit
- `403`: Forbidden
- `409`: Conflict — `error.code` is one of: `request_in_progress`, `conflict`.
- `429`: Rate limit exceeded
- `502`: Upstream dependency failed — the request did not complete and is safe to retry.
- `504`: Upstream dependency timed out — the request did not complete and is safe to retry.

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/audio/analysis/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)