- Read a value (
text,number,date): a value from the input, with the characters it was read from, or “not found”. - Find every passage (
spans): every passage of a kind in a text, such as each piece of personal data. - Locate objects (
box,boxes): a box around one object in a picture, or around every instance with a count. - Estimate a number (
numberwith arange): a best guess with a likely range, such as the number of people in a photo. - Pick several options (
choicewithmultiple): every option that applies, each with its own probability.
Models
Pick the hosted model with themodel field. Both models use the same endpoint, question types, and response format.
The input limit counts a question with the state, images, and audio. Each question is also limited to 250,000 bytes of text, which text in Chinese, Japanese, or Korean can reach before the token limit.
The examples below use
d1.2. Replace it with d1.2-ultra for harder decisions.
d1.1, d1-ultra, and the earlier d1 are deprecated. They still answer Noul, Choice, and Score questions, but not the new tasks or audio. To migrate, change model to d1.2 (from d1 or d1.1) or d1.2-ultra (from d1-ultra). The request and response format is unchanged. See Deprecations.Pricing
Both models are billed on input tokens only, and output is free. A request is billed its state, images, and audio once, however many questions it asks. Each question then adds its own tokens. A question’s tokens include its instructions, its options, and its answer slots, so aspans or boxes question costs more as max grows: about 250 and 415 tokens at the default of 16. See Image Token Usage and Audio Token Usage.
See the Liquid AI pricing page for current prices and available credits.
Setup
- Go to console.liquid.ai. If you don’t have an account yet, register and join an organization.
- Navigate to Dashboard > API Keys.
- Create a new key and copy it. Keys are prefixed with
liquid_.
- Python
- TypeScript
For text-only inputs:Use the SDK for Noul, Choice, and Score questions on text. For typed answers, image inputs, and audio inputs, the examples call the endpoint with
requests:Agent Skills
The Liquid d1 agent skill helps coding agents find opportunities for d1 and integrate it into an application. It can inspect an existing codebase, recommend structured replacements for prompt-and-parse LLM calls, and help design effective Choice, Score, and Noul questions. Choose one installation method for the coding agent you use:- Claude Code
- Codex
- Other agents
LIQUID_API_KEY in your environment instead of including it in a prompt.
Your First Call
A single API call contains the following fields:- Model: which decision model to use.
- State: the context the model should evaluate. This can be plain text (a customer message, an email, a log entry) or a JSON object with structured fields.
- Questions: up to 128 questions, each with a name, a type, and instructions. Choice and Score questions also take criteria that define the options or levels. The model evaluates all the questions of a call at once.
- Images (optional): images to evaluate alongside the state, in the top-level
imagesarray. See Image Inputs. - Audio (optional): audio clips to evaluate alongside the state, in the top-level
audioarray. See Audio Inputs.
- cURL
- Python
- TypeScript
answers.is_complaint.noul: The probability that the answer is “yes.” Here,0.989means a 0.989 probability that this is a complaint.usage.output_tokens: Always0. Decision models do not generate tokens.usage.input_tokens: The input tokens billed for the request: the state, images, and audio once, plus the tokens of each question.
confidence value. Typed answers have their own fields.
Usage Examples
Noul
A Noul question returns a single probability between 0 and 1. Your code receives a float that you can threshold to make a binary decision, use as a weight, or pass directly to downstream logic. Values near 0 or 1 express a clear answer; values near 0.5 express genuine uncertainty.- cURL
- Python
- TypeScript
answers field):
Choice
A Choice question returns the selected option, a probability distribution over all options, and aconfidence value. confidence summarizes how clear-cut the answer is: high when one option clearly wins, lower when the probability is spread across several options. The distribution tells you not just the top pick but how much probability mass sits on the runner-up, which is useful for flagging ambiguous cases or routing to a fallback.
- cURL
- Python
- TypeScript
answers field):
Score
A Score question returns a continuous value across an ordered rubric you define, plus the probability distribution over each level. The value is the probability-weighted position on the scale: if you define four levels (0 through 3), a score of2.994 means the model places nearly all weight on the top level.
- cURL
- Python
- TypeScript
answers field):
Combining Question Types
You can ask multiple questions of different types in the same call. The model evaluates all of them at once against the same state, so you get a complete decision in one round trip. This is useful when a single piece of input needs to be classified, routed, and prioritized together.- cURL
- Python
- TypeScript
answers field):
Typed Answers
d1.2 and d1.2-ultra answer five more tasks with the same endpoint and request format. Every question has atype and instructions, and every answer repeats its type. Earlier models return 422 on these questions.
The TypeSafe SDKs can’t read these answers yet: they drop them from the response, and a multiple-choice question makes the call fail. The examples below call the endpoint directly. The Python examples after the first one reuse its imports (
os and requests).
Read a Value
Atext, number, or date question reads one value from the state and returns it with the characters it came from. span holds the start and end positions of those characters in the state. When the value isn’t in the state, found is low and the value is null, so the model says “not found” instead of guessing.
- cURL
- Python
answers field):
1 234,50 EUR reads as 1234.5 with the unit EUR, and the date follows the format the invoice states. A value that is found but can’t be parsed keeps its text and span, and the value is null.
Find Every Passage
Aspans question returns every passage of a kind in the state, each with its text and position. Use it for redaction, for example to find every piece of personal data before a note is stored.
answers field, presence shortened):
max passages (16 by default). presence holds the probability of each of these slots, in order, and spans keeps those of at least 0.5. at_least is true when every slot was used, so the state may hold more passages than count: raise max to read them.
Pick Several Options
Achoice question with "multiple": true answers each option yes or no on its own. choices lists every option with a probability of at least 0.5.
answers field):
Estimate a Number
Anumber question with a range estimates a quantity instead of reading it. The model returns its median estimate and an interval from the 10th to the 90th percentile. It reads values step apart between low and high, up to 128 of them. When step would give more than 128 values, it reads 128 evenly spaced values instead, so the answer may fall between steps. Round it if you need whole numbers. Estimates are reliable on counts and scores, less so on free quantities. They have no found.
answers field):
Locate Objects
Abox question returns a box around one object in a picture. A boxes question returns a box around every instance, ordered by left edge and then top, with a count. Box edges are fractions of the picture’s height (top, bottom) and width (left, right), from its top-left corner. A request with a box or boxes question must have exactly one image.
answers field, shortened):
found is the probability that the object is in the picture, and confidence how sure the model is of the box itself. A box is missing when found is under 0.5, and box is then null. Here at_least is true because all four slots of max were used: the photo holds more faces.
Typed Answer Tips
- Read from text: reads and spans point into the text of the state. A value that only appears in an image is not found, so send the document’s text (from a PDF’s text layer or from OCR) as the state.
- Positions:
spancounts Unicode code points of the state, end excluded. - JSON states: when
stateis a JSON object (not a string), positions count the state as rendered with 2-space indentation, and each value read also has apath, the JSON Pointer of the string it lies in, such as/customer/phone. - Ask spans on their own: a
spansquestion asked in the same request as other question types can return fewer passages. Send it in its own request for the best recall. - Thresholds: calibrate any decision threshold on
found,presence, or a probability on data from your own use.
Image Inputs
Send images to the decision model through the same/decisions/v1/systemone endpoint used for text decisions. Add an images array alongside model, state, and questions. The question types and response format stay the same. Images also enable the box and boxes questions.
Each image can be a Base64 data URL or an object with content_type and base64 fields. Remote image URLs are not accepted. If an image is hosted online, download it and encode its contents before sending the request.
Single Image Input
Pass a single image as a Base64 data URL in theimages array. The model evaluates it alongside the text state.
- cURL
- Python
- TypeScript
answers field):
content_type and base64 fields without the data: prefix:
Multi-Image Input
All questions in a request receive all images. The order of the images matters. Refer to images by position in the state or question instructions.- cURL
- Python
- TypeScript
answers field):
Image Requirements
Base64 encoding increases the request size compared with the original files. Resize or compress images before encoding them if the request is too large, and use the media type that matches each file.
Image Token Usage
Each image is billed at 1.5 input tokens per 32 × 32 pixel patch, rounded up per image:usage.input_tokens and charged at the model’s input token rate. Every question reads all the images, so image tokens count toward each question’s input limit. usage.output_tokens remains 0.
Audio Inputs
d1.2 and d1.2-ultra also take audio. A clip can be what you ask about, such as a call, a voice message, or a recording to check for a siren. Questions are always written as text.Recordings to Decide On
Pass clips in the top-levelaudio array. Each clip is a Base64 data: URL, such as data:audio/wav;base64,..., or an object with content_type and base64. WAV, MP3, FLAC, and OGG are supported, and the content type must match the file. The clips come before the state, which can be null when the clips are all the model needs. Every question hears every clip, and the answers have the same format as for text.
- cURL
- Python
Audio Requirements
The 4.5 MB request limit usually binds first for uncompressed WAV, which fits about 100 seconds of 16-bit mono PCM audio at 16 kHz. Send MP3, FLAC, or OGG as is to fit longer recordings, up to the 300-second limit.
If a request returns an error saying the model does not accept audio, audio input is not available for that model. Use
d1.2 or d1.2-ultra.Audio Token Usage
Audio is billed by length, at 10 input tokens per second, rounded up per clip:audio are billed once per request, like images, and count toward each question’s input limit. Audio tokens are charged at the model’s input token rate.