I would stop asking AI to write a paragraph when the software only needs a routing label. But I would not mistake a neatly returned label for a correct or authorized decision. Liquid AI’s d1-ultra makes that distinction useful: choosing among known answers and composing new text are different jobs.
Available through Liquid’s API and partner gateways, d1-ultra evaluates text and images for bounded decisions. Vercel’s October 15 announcement documents its arrival on AI Gateway. This guide explains the output contract, image billing and review policy a beginner should understand before moving a classifier into a live workflow.
- Known answer choices suit a decision model; a newly written response remains a generative task.
- Typed output reduces formatting work, not semantic mistakes.
- Images are charged again for each question, even when questions share one request.
- Validate probabilities on your data and keep action permissions separate.
Start with what the application needs back
A classifier assigns an input to a category. A router uses that category to choose a next destination. An enum is simply a software list of allowed values. If the allowed outputs are billing, technical and other, the application needs one of those values—not a new essay explaining customer service.
Liquid’s decision-model overview describes models that return structured decisions without generating text tokens. By contrast, a generative language model composes a sequence of tokens that can become a reply, report or program. Both can appear in one system: classify the request first, then let a generative model draft a response for review.
Read Figure 1: compare the output contract of each branch. Arrow length does not represent elapsed time.
Suppose a fictional repair desk receives a message and a photo of a scratched device. Routing it to an inspection queue is a bounded decision. Writing a considerate explanation of warranty options is a separate task. Issuing a replacement is a third task with its own authority. Keeping those three jobs apart makes failures easier to diagnose.
Choose the primitive that matches the question
A primitive is a basic supported question type. d1-ultra uses the same hosted question contracts as d1. Liquid documents Noul for a yes/no probability, Choice for named unordered options, and Score for a probability-weighted position on an ordered rubric. See the hosted API reference.
Read Figure 2: the numbers are constructed examples. Each primitive answers a different kind of question.
For the repair desk, Noul could ask whether visible damage is present; Choice could select the next team; Score could rate urgency using carefully defined levels. These are three distinct questions, not three names for certainty. A rubric is a list of descriptions that explains what each level means. In the zero-indexed example, levels 0, 1 and 2 weighted by 0.10, 0.20 and 0.70 give 0×0.10 + 1×0.20 + 2×0.70 = 1.60.
Do not treat a Score of 1.60 as a 160% probability. Likewise, Choice’s separate confidence field summarizes how clear-cut the answer is; do not assume it equals the top option’s probability. Keep field names and meanings explicit in your integration.
A bounded answer can still be the wrong answer
The migration guide recommends decision models when possible answers are known beforehand. That condition deserves more attention than the API call. A category list is a model of your business process. If an important category is absent, a response can satisfy the format while failing the real task.
Read Figure 3: the shipping request has no appropriate destination in the supplied choices.
My proposed schema review asks three things: are the options distinguishable, is the evidence sufficient, and where should an unfamiliar request go? Include an out-of-scope category when appropriate, then give it a real review path. Adding other alone is not a guarantee that every novel case will be recognized. Use examples of mixed topics, unreadable photos and requests outside your service to test that boundary.
Restricted outputs remove one source of text-format drift. They do not make damage assessments infallible, turn an ambiguous image into evidence, or prevent errors caused by bad question wording. Maintain ordinary response, transport and business-rule checks around the model.
Count questions as well as pixels
Liquid bills the hosted models on input tokens; output generation contributes zero tokens. Its image rule uses 32×32-pixel patches at 1.5 tokens per patch, with rounding per image. Each question is charged for its own text and all supplied images again. The image token accounting section is the source for that contract.
For a 1,024×1,024 image, ceil(1024/32) × ceil(1024/32) = 1,024 patches and ceil(1024×1.5) = 1,536 image tokens per question. For other dimensions, round the patch counts up rather than treating partial edge patches as free.
Read Figure 4: assume 200 additional text tokens per question, including the relevant prompt material. Three questions repeat the image charge.
The Liquid price page, checked October 17, lists d1-ultra at $0.042 per million input tokens; cached input has the same listed rate. Using that rate, the assumed three-question request has 3 × (1,536 + 200) = 5,208 input tokens. Estimated inference cost is 5,208 × $0.042 / 1,000,000 = $0.000218736. At 100,000 identical requests that is $21.8736, before retries, additional questions, downstream models, review work, taxes or credits.
One network call can reduce round trips without reducing the count of billable questions. A useful cost log therefore records input usage, question count, retry count and the final outcome. Compare total cost per correctly handled request, not just a cheap model call. This example is arithmetic under stated assumptions; actual token usage comes from the endpoint’s usage report.
Confirm the endpoint, limits and data path
An API endpoint is the address and contract used to call a service. Liquid’s reference uses /decisions/v1/systemone and selects d1-ultra in the model field; OpenRouter uses its Decisions interface and the model ID liquid/d1-ultra. These are decision interfaces, so do not assume an ordinary chat-completion request is interchangeable.
Vercel’s model catalog specifies a 32,768-token context window and shows an input price of $0.04/M, while Liquid and OpenRouter list $0.042/M. The worked estimate above uses Liquid’s explicit rate; check the exact billing route rather than silently treating differently displayed prices as identical invoices.
Liquid’s image documentation currently requires encoded image content, not a remote image URL, on its direct API. Gateway wrappers can expose different request shapes. Verify image support and request-size limits for the path you actually use. On October 17, OpenRouter’s catalog also states that this model is not available through EU in-region routing. A gateway’s general compliance capabilities are not proof of this model’s availability in a particular region.
Liquid describes a single-call decision path and Vercel describes a single forward pass. That avoids generating a text sequence, but it does not make network, queue or input-processing time constant. Measure end-to-end latency at representative input sizes and load; no universal sub-second service guarantee is established here.
Test the probability before turning it into policy
Accuracy asks how often the chosen category matches a checked answer. Calibration asks whether predicted probabilities agree with observed frequencies across comparable cases. A classifier can choose the right label often but be too certain when it is wrong. Liquid describes its outputs as calibrated; the deployment question is whether that remains true on your own inputs.
Read Figure 5: the dashed diagonal is an ideal reference. You must supply actual held-out observations.
Build a held-out set of labeled cases not used to tune the questions. Group cases by predicted category probability, then compare mean probability with the fraction correctly classified. Retain the sample count and inspect results by category and image quality. A group near 0.90 should be about 90% correct only when calibration holds there; a few examples cannot establish that reliability.
For the repair desk, a wrong queue assignment may be cheaply corrected while an unauthorized replacement may be costly. Choose thresholds and review rules from those error costs and validated performance. Copying generic cutoffs such as 0.95 for automatic execution would turn an arbitrary number into policy.
Keep a separate gate for action
Read Figure 6: eligibility and evidence lead to a routing decision; they do not grant new permissions.
- Freeze the task. Record the question wording, options, rubric, model, endpoint and preprocessing. Change one variable at a time.
- Run in shadow mode. Produce a proposed route alongside the existing process without executing it. Compare with reviewed labels, including mixed-topic and out-of-scope requests.
- Separate error types. Count misroutes, missed review cases, transport failures and prohibited actions. Record latency and total work cost alongside accuracy.
- Promote a narrow workflow. Start with a reversible queue assignment if validation supports it. Keep hard rules and approval for external messages, refunds or writes.
- Monitor and recheck. Log policy versions and reviewed overrides, protect sensitive evidence, and rerun the held-out test after model or schema changes.
My adoption rule is simple: move a bounded task only when its answer set is sound, the probabilities are useful on matched data, and the full workflow improves. Keep a generative model where the output really needs to be written. Less text generation is a design choice, not a substitute for judgment.
Practical questions
Does zero generated tokens mean the response is empty?
No. The service returns structured decision values through its API. “Generated tokens” refers to composing a text sequence, not the absence of response data.
Can a valid category still be a hallucination-like mistake?
It can still be wrong or unsupported by the evidence. The category constraint governs format; the input, taxonomy and validation determine whether that category is useful.
Should I replace every classification prompt immediately?
No. Evaluate a matched sample and the surrounding workflow first. Existing structured-output language models may already meet your needs; measure the benefit of changing the contract and integration.