> 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.

# Estimate input tokens

POST https://api.cloud.hume.ai/v0/decisions/file/input_tokens
Content-Type: application/json

Estimates the input tokens of a decisions request from its questions and the duration of its audio. The body takes the same `context` and `questions` as the `request` part of a `POST /v0/decisions/file` request, plus `audio_duration_ms`, the duration of the audio file in milliseconds.

Reference: https://dev.hume.ai/audio-decisions/reference/decisions/input-tokens

## Authentication

- `X-Hume-Api-Key` header (required) — API Key authentication via header

## Request

### Body (application/json)

This endpoint expects an InputTokensRequest.

- `audio_duration_ms` (integer, required) — The duration of the audio file the decisions request would send, in milliseconds. A duration under 5 seconds is rejected with `audio_too_short`, and one over 5 minutes with `audio_too_long`.
- `questions` (map from string to Question, required) — The questions to answer: at most 20 `noul`, `choice` and `score` questions together, and at most 5 `span` questions. Each key is a question ID you choose, such as `agent_tone`, and can be any non-empty string of up to 256 characters. The response returns each answer under the same ID.
- `context` (string, optional) — Background information the model considers alongside the audio, such as the setting or who is speaking.

## Response

### 200

The estimated number of input tokens for the request.

- `estimated_input_tokens` (integer, required) — The estimated number of input tokens for the request: what `POST /v0/decisions/file` would bill it, as its response's `received.input_tokens`. The estimate counts the audio from its duration rather than the file, so it can differ slightly.

## Errors

### 400 Bad Request Error

Something in the request needs correcting. `code` says which.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

### 401 Unauthorized Error

The request carried no valid credential. Check the API key you sent.

- `message` (string, required) — A description of the problem for a person.
- `request_id` (string, optional) — The ID of the request. A `401` carries it only when an API key was rejected, and a `429` never does.

### 403 Forbidden Error

The credential does not grant access to this API, or the organization is not permitted to use it. Contact support to request access.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

### 413 Content Too Large Error

The request body is larger than 25,000,000 bytes.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

### 415 Unsupported Media Type Error

The request body is not `application/json`.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

### 429 Too Many Requests Error

The request exceeds a rate limit for the account. Hume's API gateway answers it before the request reaches the service, so its body has no `code`. Retry after the number of seconds in the `Retry-After` header.

- `message` (string, required) — A description of the problem for a person.
- `request_id` (string, optional) — The ID of the request. A `401` carries it only when an API key was rejected, and a `429` never does.

### 500 Internal Server Error

An unexpected error occurred on the server. Retry the request, and if it keeps failing, contact support with the `request_id`.

- `type` ("error", required) — The type of the object. Always `error`.
- `code` (enum, required) — What went wrong, grouped by the HTTP status it is returned with. **`400 Bad Request`**: something in the request needs correcting. - `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`. - `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options. - `audio_decode_failed`: the audio file could not be decoded. - `audio_format_unsupported`: the audio file is not MP3 or WAV. - `audio_too_short`: the audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000. - `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000. - `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only. **`402 Payment Required`** - `payment_required`: the organization has no payment method on file, or has an unpaid invoice. **`403 Forbidden`** - `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it. **`404 Not Found`** - `not_found`: no run with this ID exists in your organization. **`413 Content Too Large`** - `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. **`415 Unsupported Media Type`** - `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request. **`500 Internal Server Error`** - `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`. **`503 Service Unavailable`** - `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.
  - Allowed values: `message_invalid`, `question_invalid`, `audio_decode_failed`, `audio_format_unsupported`, `audio_too_short`, `audio_too_long`, `invalid_request`, `payment_required`, `forbidden`, `not_found`, `payload_too_large`, `unsupported_media_type`, `internal_error`, `server_busy`
- `message` (string, required) — A description of the problem for a person. Its wording may change, so switch on `code`.
- `request_id` (string, required) — The ID of the request that failed. Quote it when contacting support.
- `param` (string, optional) — Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request.

## Types

### Question

A question. `type` names its primitive, which determines the question's options and the structure of its answer.

- `type`: `noul` (noul question)
  - `instructions` (string, required) — The question, written in natural language.
  - `criteria` (NoulCriteria, optional) — Guidance on what counts as a yes or a no answer. The model reads it along with the question.
- `type`: `choice` (choice question)
  - `criteria` (list of Criterion, required) — The options, presented to the model in the order listed. A question with fewer than two options or more than 20, or with duplicate names, is rejected with `question_invalid`.
  - `instructions` (string, required) — The question, written in natural language.
- `type`: `score` (score question)
  - `criteria` (list of string, required) — The levels, ordered from lowest to highest and numbered from 0. The model reads each level's text, and the answer's `legend` returns it. A question with fewer than two levels or more than 10, or with duplicate levels, is rejected with `question_invalid`.
  - `instructions` (string, required) — The question, written in natural language.
- `type`: `span` (span question)
  - `instructions` (string, required) — The question, written in natural language.

### NoulCriteria

Guidance on what counts as a yes or a no answer. The model reads it along with the question.

- `true` (string, optional) — What counts as a yes answer.
- `false` (string, optional) — What counts as a no answer.

### Criterion

One option of a `choice` question. The model reads the option's `name` and, when it has one, its `description`. Answers are keyed by `name`.

- `name` (string, required) — The option, unique within the question. The model reads it and answers are keyed by it, so make it short and self-explanatory.
- `description` (string, optional) — More detail on when the option applies, which the model reads along with the name.

## Examples

**Request**

```json
{
  "audio_duration_ms": 135000,
  "questions": {
    "agent_glitches": {
      "type": "span",
      "instructions": "Where does the agent glitch, slur or sound robotic?"
    },
    "agent_naturalness": {
      "type": "score",
      "criteria": [
        "Not at all",
        "2",
        "3",
        "4",
        "Extremely"
      ],
      "instructions": "How natural does the agent sound?"
    },
    "agent_tone": {
      "type": "choice",
      "criteria": [
        {
          "name": "warm",
          "description": "Warm and friendly toward the caller"
        },
        {
          "name": "neutral",
          "description": "Polite but impersonal"
        },
        {
          "name": "curt",
          "description": "Short or dismissive with the caller"
        }
      ],
      "instructions": "Which best describes the tone of the agent?"
    },
    "talks_over_caller": {
      "type": "noul",
      "instructions": "Does the agent talk over the caller?"
    }
  },
  "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."
}
```

**Response**

```json
{
  "estimated_input_tokens": 11683
}
```