By default, every EyeQuant analysis returns an attention heatmap — but the API supports several prediction types, and you can request more than one in a single call. By including a predictions object in your request body, you can ask for attention, clarity, and excitingness outputs simultaneously, receiving all results together once processing completes rather than making multiple separate requests.
The predictions field
The predictions field is an optional top-level object in your request body. Each key corresponds to a prediction type (for example, attention or clarity), and its value is a configuration object with an outputs array that specifies exactly which output artifacts you want. If you omit predictions entirely, EyeQuant falls back to the default behaviour and returns only an attention heatmap.
Example: requesting attention and clarity together
The following request analyzes a Base64-encoded image and asks for both an attention map and a perception map from the attention model, plus a clarity score and clarity map from the clarity model — all in one call.
curl \
-X POST \
-H "Authorization: Bearer $apikey" \
-H "Content-Type: application/json" \
-d '{
"input": {
"type": "image",
"content": "iVBORw0KGgoAAAANSUhE....FTkSuQmCC",
"medium": "desktopWeb",
"title": "Example"
},
"predictions": {
"attention": {
"outputs": ["attentionMap", "perceptionMap"]
},
"clarity": {
"outputs": ["score", "map"]
}
}
}' \
https://api.eyequant.com/v2/analyses
location URL and processing completes, the response body contains a unified outputs object with results from every requested prediction type:
{
"id": "611457618c1d4283a830d10a9ad4f8ae",
"status": "success",
"outputs": {
"attention": {
"attentionMap": "https://s3.amazonaws.com/api-eyequant/attentionHeatmap.png",
"perceptionMap": "https://s3.amazonaws.com/api-eyequant/perceptionMap.png"
},
"clarity": {
"score": 87,
"map": "https://s3.amazonaws.com/api-eyequant/clarityMap.png"
}
}
}
Available prediction types and outputs
EyeQuant currently supports three prediction types. Include any combination of them in the predictions object:
| Prediction type | Available outputs |
|---|
attention | attentionMap, perceptionMap, hotspotsMap |
clarity | score, map |
excitingness | score |
attentionMap is a heatmap overlay, perceptionMap shows predicted visual perception across the design, and hotspotsMap highlights the individual hot spots as discrete regions.
Clarity measures how visually clear and structured the design appears. The score is a numeric value from 0–100 and map is a spatial clarity heatmap.
Excitingness predicts the emotional arousal a design is likely to trigger. It returns a single numeric score.
Example: requesting all three prediction types
curl \
-X POST \
-H "Authorization: Bearer $apikey" \
-H "Content-Type: application/json" \
-d '{
"input": {
"type": "image",
"content": "iVBORw0KGgoAAAANSUhE....FTkSuQmCC",
"medium": "desktopWeb",
"title": "Example"
},
"predictions": {
"attention": {
"outputs": ["attentionMap", "perceptionMap", "hotspotsMap"]
},
"clarity": {
"outputs": ["score", "map"]
},
"excitingness": {
"outputs": ["score"]
}
}
}' \
https://api.eyequant.com/v2/analyses
Default configurations
If you include a prediction type in the predictions object but pass an empty configuration — for example, "attention": {} — EyeQuant uses that prediction’s default outputs. You don’t need to enumerate every output name if you’re happy with the defaults.
Currently, all available outputs for a given prediction type are returned regardless of which specific outputs you list in the outputs array. The array is accepted but not yet enforced. This behaviour may change in a future API version, so you should still pass the outputs you intend to use.
