HeyGen Decision 1: Power-User Guide to the Decisions API, Limits and Pricing

Last updated: November 18, 2026

HeyGen Decision 1 is a HeyGen API model that turns text, images and video into structured decisions. You send content and up to 400 named yes/no, choice or score questions to POST /v3/models/decisions, and it returns an answer with probabilities for each one in a single synchronous response, with no generated text.

Contents

What HeyGen Decision 1 is

HeyGen is best known for AI avatar video, but its newest API model does not generate anything. The HeyGen Decision documentation describes a model that classifies text, images and video, evaluates yes/no questions and scores content against criteria you write. You can use the answers to route a request, rank a result or decide when a person should review it.

OpenRouter’s model page lists heygen-decision-1 as released on November 13, 2026, with HeyGen as its only provider. The Turbo listing carries the same date. HeyGen describes Turbo as a preview that opens to all API keys soon.

Models, limits and pricing

The table below combines the limits in HeyGen’s documentation with the prices OpenRouter publishes. HeyGen’s own Decision page does not list a price.

Item heygen-decision-1 heygen-decision-1-turbo (preview)
Endpoint POST https://api.heygen.com/v3/models/decisions (synchronous HTTP 200; no polling or webhook)
Context budget per model read 131,072 tokens 262,144 tokens
Images per request 50 100
Videos per request 10, up to 60 s each 10, up to 60 s each
Questions per request 1 to 400 1 to 400
Options in total per request 4,096 4,096
JSON request body 16 MiB 16 MiB
OpenRouter price (input / output) $0.14 / $0 per 1M tokens $0.09 / $0 per 1M tokens

Authentication uses an X-Api-Key header with the assets:write scope. Trial API keys and OAuth are not supported. The default rate limit is 50 requests per second, shared by API keys owned by the same user in the same workspace. The usage.output_tokens field is always 0.

How to make your first decision

These steps follow the official HeyGen Decision guide:

  1. Create an API key on the HeyGen API keys page with the assets:write scope, and store it as HEYGEN_API_KEY.
  2. Put the material to judge in state: a string, a JSON object or a JSON array. Name the parts, such as message and policy.
  3. Add images or videos under assets.images or assets.videos if the decision depends on what something looks like.
  4. Write each question under questions with a type (noul, choice or score), clear instructions and, where needed, criteria.
  5. Send the request with "model": "heygen-decision-1", for example: curl -X POST https://api.heygen.com/v3/models/decisions -H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: application/json" -d @request.json
  6. Read each result under data.answers by question name, and keep data.request_id for troubleshooting.

HeyGen notes that unknown fields are rejected, and there is no top-level prompt, temperature or max_tokens parameter.

Question types and answers

You can mix all three question types in one request. Questions share the same state and run independently, so one answer never feeds into another. When a question depends on an earlier answer, ask it in a later request.

Type Use it for Criteria What comes back
noul A yes/no question or a statement to test Optional true and false descriptions Estimated probability of true, from 0 to 1
choice Picking one category you define Required, 1 to 255 named options Top option, a probability for every option and confidence
score Rating against ordered levels Required, 1 to 10 levels from low to high Probability-weighted score, per-level probabilities, a legend and confidence

A score is an average, not a percentage. HeyGen’s example returns 1.75 on a three-level scale from probabilities of 0.05, 0.15 and 0.8. The docs warn that different distributions can produce the same score, so check the probabilities too.

A choice with only one option, or a score with only one level, is answered without a model read. A request made up only of such fixed questions reports zero tokens.

Working with images and video

Each image or video input is keyed by a name you choose and can use one of three sources: an asset_id from HeyGen’s upload API, a public HTTPS URL that serves the file directly, or inline base64. The model reads images first, then videos, then state. Names are not shown to the model, so describe each input by its position in state.

The video documentation adds an important point: video is read as sampled frames, and those frames add to usage.input_tokens. To judge speech, put the transcript in state. A video longer than 60 seconds returns a 400 error and is not charged.

Size limits are 32 MiB per image URL download, 5 MiB per decoded base64 image, 50 MiB per video URL download and 16 MiB per decoded base64 video. For larger videos, HeyGen points to its direct upload flow, which accepts files up to 200 MB, and an asset_id.

Power-user tips and limitations

  • Confidence is not accuracy. HeyGen states that confidence is not a calibrated probability that the answer is correct. Choose thresholds from labeled examples, and treat any warning field as a reason to review.
  • Add an escape option. The model only picks from the options you supply, so add a choice such as other if none may fit.
  • Watch token counts. Shared state can be counted more than once across questions, so usage.input_tokens can exceed the per-read context limit. Budget from the returned count, not the length of your state.
  • Retry with care. There is no idempotency key, so a retry may run the request again. Back off on 429, 502, 503 and 504 errors; a 402 means you need more credit.
  • Paste content, not links. URLs inside state are read as text. Media is fetched only from assets.

HeyGen Decision 1 vs. Gemini Decision 1

HeyGen’s release arrived two days after Google’s. The Gemini Decision 1 model page describes the same noul, choice and score pattern with zero output tokens. Our Gemini Decision 1 guide covers it in detail.

Feature HeyGen Decision 1 Gemini Decision 1
Questions per request 1 to 400 Up to 1,000
Context 131,072 tokens per model read (262,144 on Turbo) 262,144 input tokens
Inputs Text, images and video (sampled frames) Text, image, audio, video and PDF
Output tokens 0 0

Other decision models take different routes. See our guides to Perplexity Decider v1.3, Liquid AI d1.2 and the self-hosted /v1/decisions endpoint in vLLM 0.33. If you want to create video rather than judge it, our answer on whether Claude can generate videos covers the options.

Frequently asked questions

What is HeyGen Decision 1?

HeyGen Decision 1 (heygen-decision-1) is a HeyGen API model that answers named yes/no, choice and score questions about text, images and video in one synchronous call to POST /v3/models/decisions. It returns probabilities instead of generated text.

How much does HeyGen Decision 1 cost?

OpenRouter lists heygen-decision-1 at $0.14 per million input tokens and $0 for output, and the Turbo preview at $0.09 per million input tokens. HeyGen’s Decision documentation page does not list a price.

Can HeyGen Decision 1 hear the audio in a video?

No. HeyGen’s documentation says the model reads video as sampled frames. To judge what is said, put a transcript in the state field.

How many questions can one request ask?

Between 1 and 400 named questions, with no more than 4,096 options in total. Each noul question counts as two options, and the 131,072-token context budget per model read also applies.

Is the confidence value the chance that an answer is correct?

No. HeyGen says confidence is derived from the returned distribution and is not a calibrated probability of correctness. Test thresholds on labeled examples from your own use case.

Can I use a trial API key?

No. The documentation says trial API keys and OAuth are not supported. You need an X-Api-Key from the API keys page with the assets:write scope.

Sources

Image: HeyGen logo, public domain (trademarked), via Wikimedia Commons.

Related answers

Leave a Comment