> This page is for Audio Decisions.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# Audio Decisions API

**Send an audio file with questions written in plain language, and get back probabilities that your code can threshold, rank or combine.** For example, ask "How natural does the voice sound?" on a five-point scale, and the answer gives the probability of each level.

#### [Build with a coding agent](/audio-decisions/docs/for-coding-agents)

Point your coding agent to the request format and calling rules for this API.

## A decision model for audio

**The Audio Decisions API runs a decision model for audio.** The model takes a recording and your questions as input, and answers each question with probabilities instead of text. It returns no transcript, reply or explanation; your code does the reasoning with the numbers.

Because the model takes the audio itself as input, a question can be about:

1. **How speech sounds**, such as a caller's frustration or a voice agent's naturalness.
2. **What is said**, such as when a caller asks to cancel their service.
3. **Other sounds**, such as background noise or a phone ringing.

Use it where people would otherwise listen to recordings to label them, or where a transcript would lose how something was said: evaluating text-to-speech output, testing voice agents, reviewing support calls and labeling speech corpora.

#### [Introducing the Audio Decisions API](https://www.hume.ai/blog/introducing-hume-audio-decision-api)

Why Hume built a decision layer for speech and sound, and how human judgments ground its answers.

## How a request works

A request is a `multipart/form-data` `POST` with your credential in a header and two parts, sent in this order:

<table>
  <thead>
    <tr>
      <th width="25%">
        Field
      </th>

      <th>
        Contains
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `X-Hume-Api-Key`

         header
      </td>

      <td>
        Your API key. See 

        [Authentication](/audio-decisions/docs/authentication)

        .
      </td>
    </tr>

    <tr>
      <td>
        `request`

         part
      </td>

      <td>
        A JSON object with your 

        `questions`

        , each keyed by an ID you choose, and an optional 

        `context`

         that describes the recording, such as the setting or who is speaking.
      </td>
    </tr>

    <tr>
      <td>
        `file`

         part
      </td>

      <td>
        One audio file, MP3 or WAV, 5 seconds to 5 minutes long. To evaluate several recordings, send one request per file.
      </td>
    </tr>
  </tbody>
</table>

This request evaluates a simulated call with a voice AI agent. It asks two questions about the same audio: whether the agent talks over the caller, and how natural the agent sounds on a five-point scale.

#### cURL

```bash maxLines={0}
curl https://api.cloud.hume.ai/v0/decisions/file \
  -H "X-Hume-Api-Key: $HUME_API_KEY" \
  -F 'request={
    "context": "A simulated test call in which a voice AI agent helps a caller reschedule an appointment. Both voices are synthetic, and the agent speaks first.",
    "questions": {
      "talks_over_caller": {
        "type": "noul",
        "instructions": "Does the agent talk over the caller?"
      },
      "agent_naturalness": {
        "type": "score",
        "instructions": "How natural does the agent sound?",
        "criteria": ["Not at all", "2", "3", "4", "Extremely"]
      }
    }
  };type=application/json' \
  -F file=@test_call.wav
```

#### Python

```python maxLines={0}
from hume_audio_decisions import (
    DecisionsClient,
    DecisionsRequest,
    Question_Noul,
    Question_Score,
)

client = DecisionsClient()

request = DecisionsRequest(
    context=(
        "A simulated test call in which a voice AI agent helps a "
        "caller reschedule an appointment. Both voices are "
        "synthetic, and the agent speaks first."
    ),
    questions={
        "talks_over_caller": Question_Noul(
            instructions="Does the agent talk over the caller?",
        ),
        "agent_naturalness": Question_Score(
            instructions="How natural does the agent sound?",
            criteria=["Not at all", "2", "3", "4", "Extremely"],
        ),
    },
)

with open("test_call.wav", "rb") as audio:
    response = client.decisions.create(
        file=("test_call.wav", audio, "audio/wav"),
        request=request,
    )

print(response.model_dump_json(indent=2))
```

#### TypeScript

```typescript maxLines={0}
import { DecisionsClient } from "@humeai/audio-decisions";

const client = new DecisionsClient();

const response = await client.decisions.create({
  file: {
    path: "test_call.wav",
    contentType: "audio/wav",
  },
  request: {
    context:
      "A simulated test call in which a voice AI agent helps a " +
      "caller reschedule an appointment. Both voices are " +
      "synthetic, and the agent speaks first.",
    questions: {
      talks_over_caller: {
        type: "noul",
        instructions: "Does the agent talk over the caller?",
      },
      agent_naturalness: {
        type: "score",
        instructions: "How natural does the agent sound?",
        criteria: ["Not at all", "2", "3", "4", "Extremely"],
      },
    },
  },
});

console.log(JSON.stringify(response, null, 2));
```

The response keys each answer by the ID of its question. It also carries the `run_id` of the model run that produced the answers, and `received`, which holds the input tokens the request is billed:

#### 200 OK

```json
{
  "run_id": "019a1f3c-7d2e-7b41-9c58-2e6f4a1d8b03",
  "answers": {
    "talks_over_caller": {
      "type": "noul",
      "noul": 0.1274
    },
    "agent_naturalness": {
      "type": "score",
      "score": 2.7195,
      "confidence": 0.4229,
      "probabilities": {
        "0": 0.0218,
        "1": 0.0874,
        "2": 0.2463,
        "3": 0.4385,
        "4": 0.206
      },
      "legend": {
        "0": "Not at all",
        "1": "2",
        "2": "3",
        "3": "4",
        "4": "Extremely"
      }
    }
  },
  "received": {
    "input_tokens": 11234
  }
}
```

The `noul` answer estimates that 13% of raters would say the agent talks over the caller. The `score` answer gives the probability of each level, with "4" the most likely, and its `score` of 2.72 is the mean level, between "3" and "4". `legend` maps each level index to the text you gave it.

A probability estimates the share of human raters who would give that answer, so a value near 0.5 means raters would split on the audio, not that the model is unsure.

#### [API reference](/audio-decisions/reference/decisions/create)

Every parameter and field of the decisions endpoint.

## Primitives

Each question's `type` names its primitive, which sets the `criteria` the question takes and the form of its answer. One request can mix primitives.

<table>
  <thead>
    <tr>
      <th width="15%">
        Primitive
      </th>

      <th width="40%">
        Asks
      </th>

      <th>
        The answer gives
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        [`noul`](/audio-decisions/docs/primitives#noul)
      </td>

      <td>
        Whether something is true of the audio.
      </td>

      <td>
        The probability of yes.
      </td>
    </tr>

    <tr>
      <td>
        [`choice`](/audio-decisions/docs/primitives#choice)
      </td>

      <td>
        Which of several options applies.
      </td>

      <td>
        The probability of each option, and the most likely one.
      </td>
    </tr>

    <tr>
      <td>
        [`score`](/audio-decisions/docs/primitives#score)
      </td>

      <td>
        Where the audio falls on an ordered scale.
      </td>

      <td>
        The probability of each level, and the probability-weighted mean level.
      </td>
    </tr>

    <tr>
      <td>
        [`span`](/audio-decisions/docs/primitives#span)
      </td>

      <td>
        When an event occurs.
      </td>

      <td>
        The time spans where the event may occur.
      </td>
    </tr>
  </tbody>
</table>

#### [Primitives](/audio-decisions/docs/primitives)

Learn what each question type asks and what its answer contains.

## Combine answers in code

Ask each question for one focused judgment, and combine the answers in your code. "Did the agent handle the call well?" depends on several things, so ask about each one: the agent's tone, how frustrated the caller sounds and whether the caller asks to cancel.

Send all the questions about a recording in one request, and send the same questions in the same order for every recording you compare, since an answer can change when the other questions change. Then combine the answers with thresholds and weights you choose, such as flagging a call for review when the probability that the agent is curt crosses a threshold.

#### [Writing questions](/audio-decisions/docs/writing-questions)

Learn how to write questions that get useful answers, and which questions to avoid.

#### [Interpreting answers](/audio-decisions/docs/interpreting-answers)

Learn how to read each answer and set thresholds for acting on it.

## Endpoints

Every endpoint is served from `https://api.cloud.hume.ai`.

<table>
  <thead>
    <tr>
      <th>
        Endpoint
      </th>

      <th>
        Request
      </th>

      <th>
        Returns
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        [Decisions](/audio-decisions/reference/decisions/create)
      </td>

      <td>
        `POST /v0/decisions/file`
      </td>

      <td>
        Answers and the 

        `run_id`
      </td>
    </tr>

    <tr>
      <td>
        [Estimate input tokens](/audio-decisions/reference/decisions/input-tokens)
      </td>

      <td>
        `POST /v0/decisions/file/input_tokens`
      </td>

      <td>
        Estimated input tokens
      </td>
    </tr>

    <tr>
      <td>
        [List runs](/audio-decisions/reference/runs/list)
      </td>

      <td>
        `GET /v0/decisions/run`
      </td>

      <td>
        Runs, newest first
      </td>
    </tr>

    <tr>
      <td>
        [Get run](/audio-decisions/reference/runs/get)
      </td>

      <td>
        `GET /v0/decisions/run/{run_id}`
      </td>

      <td>
        One run's status and request
      </td>
    </tr>
  </tbody>
</table>

Each request that reaches the model is recorded as a run, which can take a moment to appear. Under heavy load a run may not be recorded. The run endpoints return a run's status and the request it evaluated, but not its answers, so store the `run_id` and answers you need.

#### [Runs](/audio-decisions/docs/runs)

Look up the status and request of past decisions requests.

## SDKs

The Python and TypeScript SDKs cover every endpoint with typed requests and responses. They read your API key from `HUME_API_KEY`, retry requests that are rate limited or fail on the server, and include audio helpers that split recordings longer than 5 minutes and send one request per part.

#### [Python quickstart](/audio-decisions/docs/quickstart/python)

Score text-to-speech output or label a speech corpus from a script or notebook.

#### [TypeScript quickstart](/audio-decisions/docs/quickstart/typescript)

Act on answers in a backend service, such as flagging calls for review.

## Compatibility

The API version is the path prefix, `/v0/`. Within a version:

1. **The server may add fields to the responses it sends.** Ignore fields you do not recognize.
2. **New answer types may be added.** Treat an answer with an unrecognized `type` as unknown, not as an error.
3. **Requests are validated strictly.** An unrecognized field is rejected with `question_invalid` inside a question, and with `message_invalid` elsewhere in the `request` part.
4. **The model can be updated without a change to the API.** Answers for the same audio and questions can change after an update.

## Next steps

#### [Use cases](/audio-decisions/docs/use-cases)

Learn which decisions the API fits, from evaluating text-to-speech output to labeling speech corpora.

#### [Writing questions](/audio-decisions/docs/writing-questions)

Learn how to write questions that get useful answers, and which questions to avoid.
Field	Contains
`X-Hume-Api-Key` header	Your API key. See [Authentication](/audio-decisions/docs/authentication) .
`request` part	A JSON object with your `questions` , each keyed by an ID you choose, and an optional `context` that describes the recording, such as the setting or who is speaking.
`file` part	One audio file, MP3 or WAV, 5 seconds to 5 minutes long. To evaluate several recordings, send one request per file.
Primitive	Asks	The answer gives
[`noul`](/audio-decisions/docs/primitives#noul)	Whether something is true of the audio.	The probability of yes.
[`choice`](/audio-decisions/docs/primitives#choice)	Which of several options applies.	The probability of each option, and the most likely one.
[`score`](/audio-decisions/docs/primitives#score)	Where the audio falls on an ordered scale.	The probability of each level, and the probability-weighted mean level.
[`span`](/audio-decisions/docs/primitives#span)	When an event occurs.	The time spans where the event may occur.
Endpoint	Request	Returns
[Decisions](/audio-decisions/reference/decisions/create)	`POST /v0/decisions/file`	Answers and the `run_id`
[Estimate input tokens](/audio-decisions/reference/decisions/input-tokens)	`POST /v0/decisions/file/input_tokens`	Estimated input tokens
[List runs](/audio-decisions/reference/runs/list)	`GET /v0/decisions/run`	Runs, newest first
[Get run](/audio-decisions/reference/runs/get)	`GET /v0/decisions/run/{run_id}`	One run's status and request