HTTP API Documentation
Integrate attention prediction directly into your applications with our RESTful API
API Overview
Access the RealEye Attention Predictor programmatically via HTTP API for seamless integration into web applications, automated workflows, and custom tools.
Endpoint
https://api.realeye.io/v1/predict_attention
Example endpoint - actual URL provided with API access
Authentication
Authorization: Bearer YOUR_API_KEY
Secure API key authentication required for all requests
Request Format
Send image data via HTTP POST request. Supported formats include JPEG, PNG, and WebP.
JSON Input Example
{
"image_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAAAAAAAD/2wBDAAYEBQYFBAY..."
}cURL Example
curl -X POST \
https://api.realeye.io/v1/predict_attention \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: image/jpeg" \
--data-binary "@path/to/your_image.jpg"Response Format
The API returns comprehensive attention prediction data in JSON format, including matrices for VAI, Hold, Speed, and Reach components across different time ranges.
JSON Response Structure
{
"image_id": "user_provided_or_generated_id",
"dimensions": {
"width": 224, // Matrix width (number of columns)
"height": 224 // Matrix height (number of rows)
},
"attention_matrices": {
"hold_500ms": [
[0.001, 0.002, 0.003, ...], // Row 0 (224 values)
[0.004, 0.005, 0.006, ...], // Row 1 (224 values)
... // 224 total rows
],
"speed_500ms": [
[0.15, 0.22, 0.18, ...], // Higher values typical for Speed
[0.31, 0.28, 0.25, ...],
...
],
"reach_500ms": [
[0.12, 0.19, 0.16, ...], // Similar range to Speed
[0.24, 0.31, 0.28, ...],
...
],
"vai_500ms": [
[0.09, 0.15, 0.12, ...], // Composite of above three
[0.20, 0.21, 0.20, ...],
...
],
"hold_1000ms": [[...], [...], ...],
"speed_1000ms": [[...], [...], ...],
"reach_1000ms": [[...], [...], ...],
"vai_1000ms": [[...], [...], ...],
// Additional time ranges: 3000ms, 5000ms, 10000ms
}
}Matrix Data
2D arrays representing Cell Attention Scores, normalized between 0.0 and 1.0 for easy visualization and analysis.
Multiple Metrics
Hold, Speed, and Reach predictions across different time intervals (500ms, 1000ms, 3000ms, etc.), with VAI calculated as a composite.
Flexible Output
Generate heatmaps, calculate AOI statistics, or integrate with analytics tools using the numerical data.
Attention Matrix Dimensions
Understanding the structure and dimensions of the attention matrices is crucial for proper integration and data processing.
Matrix Structure
Each attention matrix is a 2D array where each cell represents a spatial location on the input image. The matrix dimensions correspond to the processed image resolution.
Standard Dimensions
Matrices are 224×224 cells, providing high-resolution spatial attention mapping. The exact dimensions are always provided in the dimensions field of the API response.
Coordinate System
Matrix coordinates follow standard image conventions: [row][column] indexing, where [0][0] represents the top-left corner of the image.
Matrix Access Example
// Access attention score at specific coordinates
const matrix = response.attention_matrices.vai_500ms;
const topLeftScore = matrix[0][0]; // Top-left corner
const centerScore = matrix[112][112]; // Center (for 224x224 matrix)
const bottomRightScore = matrix[223][223]; // Bottom-right corner
// Matrix dimensions
const height = matrix.length; // Number of rows (224)
const width = matrix[0].length; // Number of columns (224)
// Alternative: Use dimensions from response
const { width, height } = response.dimensions;Cell Values
Range: 0.0 to 1.0 (float32)
Meaning: Higher values indicate stronger predicted attention
Terminology: Individual values are called "Cell Attention Scores"
Spatial Resolution
Each matrix cell represents a small spatial region of the input image. For a 224×224 matrix, each cell covers approximately 1/224th of the image width and height.
Processing Guidelines
Matrices are ready for direct use in heatmap generation, statistical analysis, or AOI calculations. No additional normalization is required.
Value Characteristics
Hold matrices: Typically show "hills" with peaks around 0.03
Speed/Reach matrices: Show broader patterns with higher peak values
VAI matrices: Composite averaging of the three components
AOI Statistics API (Proposed)
Calculate Area of Interest (AOI) attention statistics for custom reporting and analysis. This proposed endpoint would enable developers to create comprehensive AOI reports similar to our internal reporting system.
Endpoint
POST /v1/calculate_aoi_statistics
Calculate attention statistics for defined Areas of Interest
Use Cases
- Custom reporting dashboards
- A/B testing analysis
- Design performance metrics
- Scan path optimization
Request Format
{
"image_id": "your_prediction_image_id",
"aois": [
{
"id": "header-logo",
"name": "Header Logo",
"coordinates": {
"x": 20,
"y": 10,
"width": 150,
"height": 60
}
},
{
"id": "cta-button",
"name": "Call to Action Button",
"coordinates": {
"x": 300,
"y": 400,
"width": 200,
"height": 50
}
}
],
"metrics": ["vai", "speed", "reach", "hold"],
"time_ranges": ["500ms", "1000ms", "3000ms", "5000ms", "10000ms"]
}Response Format
{
"image_id": "your_prediction_image_id",
"dimensions": {
"width": 224,
"height": 224
},
"aoi_statistics": {
"header-logo": {
"name": "Header Logo",
"coordinates": {
"x": 20,
"y": 10,
"width": 150,
"height": 60
},
"metrics": {
"vai": {
"500ms": {
"aoi_score": 15.3, // AOI Attention Score (%)
"average": 0.153, // Average cell value
"max": 0.421, // Maximum cell value
"min": 0.002, // Minimum cell value
"std_dev": 0.087, // Standard deviation
"total_attention": 0.023 // Sum of all cell values
},
"1000ms": { "aoi_score": 18.7, ... },
// ... other time ranges
},
"speed": {
"500ms": {
"aoi_score": 22.1, // Speed: average × 100%
"average": 0.221,
"max": 0.654,
"min": 0.001,
"std_dev": 0.132,
"total_attention": 0.034
},
// ... other time ranges
},
"reach": {
"500ms": {
"aoi_score": 19.8, // Reach: average × 100%
"average": 0.198,
"max": 0.587,
"min": 0.003,
"std_dev": 0.098,
"total_attention": 0.031
},
// ... other time ranges
},
"hold": {
"500ms": {
"aoi_score": 4.1, // Hold: percentage of total attention
"average": 0.041,
"max": 0.089,
"min": 0.001,
"std_dev": 0.019,
"total_attention": 0.006
},
// ... other time ranges
}
}
},
"cta-button": {
"name": "Call to Action Button",
// ... similar structure for each AOI
}
},
"summary": {
"best_performers": {
"vai": {
"aoi_id": "cta-button",
"aoi_name": "Call to Action Button",
"average_score": 28.4
},
"speed": { "aoi_id": "header-logo", ... },
"reach": { "aoi_id": "cta-button", ... },
"hold": { "aoi_id": "header-logo", ... }
},
"scan_path_order": [
{
"rank": 1,
"aoi_id": "header-logo",
"aoi_name": "Header Logo",
"speed_score": 22.1
},
{
"rank": 2,
"aoi_id": "cta-button",
"aoi_name": "Call to Action Button",
"speed_score": 18.7
}
]
}
}AOI Score Calculations
Speed & Reach: Average cell values × 100
Hold: Percentage of total image attention
VAI: Average of Speed, Reach, and Hold AOI scores
Statistical Metrics
Each AOI provides comprehensive statistics including average, maximum, minimum, standard deviation, and total attention values for thorough analysis.
Scan Path Analysis
Automatically generates predicted viewing order based on Speed scores, helping optimize design layouts for natural attention flow.
Multi-Metric Comparison
Compare AOI performance across all attention components (VAI, Speed, Reach, Hold) and time ranges for comprehensive insights.
Ready to Start Building?
Get your API credentials and start integrating attention prediction into your applications today
Always refer to the official API documentation for the most current endpoints, authentication, and rate limits.