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:For image inputs, the SDK does not support images yet, so the image examples use
requests: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: one or more typed questions, each with a name, a type, and instructions. Choice and Score questions also take criteria that define the options or levels. You can ask multiple questions in the same call, and the model evaluates them all at once.
- Images (optional): images to evaluate alongside the state. Pass them in the top-level
imagesarray. See Image Inputs for the request format and examples.
- cURL
- Python
- TypeScript
answers.is_complaint.noul: The probability that the answer is “yes.” Here,0.999means a 0.999 probability that this is a complaint.usage.output_tokens: Always0. Decision models do not generate tokens.usage.input_tokens: The total input tokens across all questions, including image tokens when images are provided. Each question is charged for its text and all supplied images.
confidence value.
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.9995 means the model places nearly all weight on the top level.
- cURL
- Python
- TypeScript
answers field):
Combining All Three Primitives
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):
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.
Vision is available through the Liquid API with the paid
d1 model. d1:free is text-only.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.
If a request returns
The model `d1:free` does not accept images., use d1. If the same error names d1, image input is not available for that model on the endpoint you called.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. Image tokens also count toward each question’s input token limit. usage.output_tokens remains 0.