For coding agents

This page gives a coding agent what it needs to build with the Audio Decisions API: what the API does, one complete request and response, and the rules that code most often gets wrong. Point your agent to this page before it writes code that calls the API.

Set up your agent

Add this to your project’s agent instructions, such as CLAUDE.md or AGENTS.md:

Before writing code that calls the Audio Decisions API, read https://dev.hume.ai/audio-decisions/docs/for-coding-agents.md. For any other Audio Decisions page, find it in https://dev.hume.ai/audio-decisions/llms.txt and fetch its Markdown by adding .md to the page URL.

What the API does

1. A request sends one audio file and your questions about it, written in plain language. All the questions in a request are answered in one model inference.
2. Each answer is numbers, not text. A noul, choice or score answer gives probabilities that estimate the share of human raters who would give each answer. A span answer gives the times where an event may occur. There is no transcript, reply or explanation, so the calling code makes the decision.
3. The API is HTTP only, with one file per request. To evaluate many recordings, send one request per file. To evaluate live audio, send short clips as they are captured.

Make a request

A request is a multipart/form-data POST to https://api.cloud.hume.ai/v0/decisions/file, with the API key in the X-Hume-Api-Key header and two parts, sent in this order:

1. request: a JSON object with questions, each keyed by an ID you choose, and an optional context string that describes the recording.
2. file: one audio file, MP3 or WAV.

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

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

{
  "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
  }
}

Question types

Each question’s type names its primitive, which sets the criteria it takes and the fields of its answer. One request can mix types.

Rules for calling code

Questions

1. Ask each question for one judgment a listener could make from the audio, and combine the answers in code. For a broad decision such as “Did the agent handle the call well?”, ask about the agent’s tone, the caller’s frustration and whether the caller asks to cancel, then combine those answers. If a person listening to the audio would find a question hard to answer, the model is likely to find it hard too.
2. List the possible answers instead of asking an open question. Answers are probabilities over the options you give, or time spans. To find why someone called, ask a choice question that lists the reasons.
3. Give every choice question a neutral option and an option for audio that fits none of the others. Add “neutral” to emotions such as angry, fearful and sad, “unsure” to yes and no, and “none of these” to any list that might not cover every recording.
4. Make choice options distinct categories, not narrow number ranges. Ask for “slow”, “normal” or “fast” rather than ranges of words per minute.
5. Expect span answers to be most reliable for vocal bursts and sound events, such as laughs, sighs, coughs or a phone ringing. For other events, such as a word being spoken, check the spans against audio where you know the answer before relying on them.
6. Do not ask questions that need musical understanding, such as where the chorus starts. See Questions the model does not answer well.
7. Send the same questions in the same order for every recording you compare. An answer can change when other questions in the request are added, removed or reordered, so a threshold holds only for the request it was set on.
8. Put the text a question depends on in context, such as a script or the requested speaking style. Every question in a request shares one context, so questions that need different context go in separate requests.
9. Name the speaker a question is about, such as “the agent” or “the caller”, and describe each speaker in context.

Answers

1. A probability is the estimated share of raters, not the model’s certainty. A noul of 0.5 means raters would split, and a noul of 0.6 means 60% would answer yes, not “somewhat yes”.
2. Read score levels through legend. Level indices start at 0, so on a scale labeled “Not at all”, “2”, “3”, “4”, “Extremely”, index 1 is the level labeled “2”. score is the mean level index, not a label.
3. Choose thresholds from labeled audio. The API sets no threshold. Compare answers with the known answers for recordings of the kind you will judge.
4. Send each request once. The same request with the same file returns the same answers, so averaging repeats adds nothing. Answers can change when the model is updated.
5. Store each answer with its run_id and the questions that produced it. The run endpoints return a run’s status and request, but not its answers.

Audio

1. Send the whole conversation as one file, and name the speaker each question is about. To judge one person apart from the others, send that person’s audio as its own file. The model hears audio as one channel at 16 kHz and does not hear which side or channel a sound comes from.
2. Send 5 seconds to 5 minutes of audio, in a request body of at most 25,000,000 bytes. Shorter audio is rejected with audio_too_short and longer audio with audio_too_long. Split long recordings into one request per part, and convert large WAV files to 16 kHz mono, since a higher sample rate or a second channel does not improve answers. See Limits.
3. Skip silent or nearly silent files. The model can answer silence with high confidence.

Requests and errors

1. Keep the API key on a server you control. To use the API from a browser, relay the audio through your server.
2. Send only documented fields. Requests are validated strictly and an unrecognized field is rejected. In responses, ignore unrecognized fields, and treat an answer with an unrecognized type as unknown rather than as an error.
3. Branch on the error’s code, and on the status when there is no code. The gateway’s 401, 429 and 404 for a path or method the API does not serve carry no code.
4. Retry 429 and 503 after the seconds in the Retry-After header, and retry 500. Both SDKs do this, retrying a request twice. Fix a 400, 413 or 415 before resending, since the same request fails again. The rate limit is 60 requests per minute, shared by every API key in the organization. See Errors.

Where to go next