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
- Models, limits and pricing
- How to make your first decision
- Question types and answers
- Working with images and video
- Power-user tips and limitations
- HeyGen Decision 1 vs. Gemini Decision 1
- Frequently asked questions
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:
- Create an API key on the HeyGen API keys page with the assets:write scope, and store it as
HEYGEN_API_KEY. - Put the material to judge in
state: a string, a JSON object or a JSON array. Name the parts, such asmessageandpolicy. - Add images or videos under
assets.imagesorassets.videosif the decision depends on what something looks like. - Write each question under
questionswith atype(noul, choice or score), clearinstructionsand, where needed,criteria. - 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 - Read each result under
data.answersby question name, and keepdata.request_idfor 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
warningfield as a reason to review. - Add an escape option. The model only picks from the options you supply, so add a choice such as
otherif none may fit. - Watch token counts. Shared state can be counted more than once across questions, so
usage.input_tokenscan 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
stateare read as text. Media is fetched only fromassets.
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
- HeyGen Developers: HeyGen Decision
- HeyGen Developers: Decision from video
- OpenRouter: HeyGen Decision (heygen-decision-1)
- OpenRouter: HeyGen Decision Turbo (heygen-decision-1-turbo)
- Google AI Studio: Gemini Decision 1
Image: HeyGen logo, public domain (trademarked), via Wikimedia Commons.