The Neurons AI API allows businesses to analyze images and videos for predictive insights at scale as part of their own system. This guide provides a step-by-step overview to help users set up their API access and start integrating Neurons AI analysis into your own workflows.
Get Your API Key
To begin using the Neurons AI API, you need an API key. This unique key is required to authenticate and authorize all your API requests.
- If you are a new user and do not have an API key, contact your Customer Success Manager or email support@neuronsinc.com.
- Once you receive the key, keep it secure. If you misplace it, contact Neurons support immediately to request a new one.
Authentication
All requests to the API must include your API key in the request headers:
X-API-Key: YOUR_API_KEY
This key verifies your access and ensures secure communication with the Neurons servers. Your CSM can help you set up a new authentication or update your current one.
Uploading Media for Analysis
The API supports both images and videos for AI-driven predictions.
Uploading an Image
Use the image upload endpoint to upload and start the prediction. The prediction runs straight away and no other interventions are required.
Uploading a Video
Video uploads require an extra step due to file size:
- Initiate the upload – The API will provide a "resumable URL."
- Upload the video in chunks using the provided URL.
- Finalize the upload – Once complete, send a request to start processing.
Results will be available once the AI prediction process finishes.
Get Notified via Webhooks (Optional)
If you want to receive automatic notifications when your media has been processed, you can set up webhooks. This requires contacting Neurons support to configure the webhook URL.
When processing is complete, the webhook will send a JSON response containing:
- The media type (image, video, or AOI).
- The status (done/failed).
- Results URLs (heatmaps, metrics, etc.).
Retrieving AI Predictions
Once your media has been analyzed, you can retrieve the results using the Get Media endpoint. The API will return URLs with various insights, such as:
- Heatmaps – Showing attention distribution.
- Fog maps – Indicating focus elements.
- Metrics – Data-driven insights on attention, emotion, cognition and memory.
If processing is still in progress, the API will return a "pending" status.
You can read more about our heatmap and fog maps interpretations in the Neurons AI heatmaps and interpretation article.
Managing Your Media
You can also:
- List all uploaded images/videos.
- Delete media once it's no longer needed.
- Set Areas of Interest (AOIs) on images and videos for targeted analysis.
AOIs define specific regions within an image where attention or engagement should be measured.
For a detailed description on our AOI feature, please see this article.
Rate limits
The Neurons AI API employs rate limiting to control the number of requests a user can make over a specified time frame. This ensures the API remains reliable and efficient for all users. Each request is monitored by rate limit headers included in the API response, helping users check their remaining allowed requests (X-RateLimit-Remaining) and understand when the limit resets (X-RateLimit-Reset). If the allowed limit is exceeded, subsequent requests will return an error until the rate limit resets. Users should integrate rate limits into their applications to manage usage effectively and avoid interruptions. A complete overview of the rate limits is found in this document.
Account management
The GET endpoints for account management both have a rate limit of 200 requests per 10 seconds, over which the server will respond with a 429 status.
Fetching media list and individual media results
The GET endpoints for fetching list of media as well as individual media results they all have a rate limit of 200 requests per 10 seconds, over which the server will respond with a 429 status.
Deleting media
The media deletion endpoint has a rate limit of 50 requests per 10 seconds, over which the server will respond with a 429 status.
Image prediction
Image prediction is limited to 100 images per 10 seconds, over which the server will respond with a 429 status.
Image AOI prediction
Image AOI detection and calculation have a rate limit of 100 requests per 10 seconds, over which the server will respond with a 429 status.
Video prediction
Video prediction is limited to 50 videos per 10 seconds, over which the server will respond with a 429 status.
Video AOI prediction
Video AOI detection has a rate limit of 50 requests per 10 seconds, over which the server will respond with a 429 status
Conclusion
The Neurons AI API is a powerful tool for predictive media analysis. By obtaining an API key, authenticating requests, uploading media, and retrieving results, businesses can gain deep insights into their content’s effectiveness.
For further assistance, refer to the full API documentation: Neurons API Docs (Welcome!) (Video prediction) (Get Media).