Welcome to the Postman documentation for the Neurolabs API. This guide is designed to provide a detailed overview of the API functionalities, empowering you with the knowledge to seamlessly integrate and effectively utilize our cutting-edge synthetic image recognition services. Learn more at neurolabs.ai
\nThe Neurolabs API offers robust solutions for image recognition, enabling seamless integration and utilization of advanced AI capabilities.
\nAccess the Open API documentation at Neurolabs API v2 Docs and find additional resources at Neurolabs Documentation.
\nFamiliarize yourself with key terms used in this documentation:
\nIR Result): The output of an image recognition request, detailing the identified items.IR Task): A job created for processing images for recognition.Onboard catalogs and create image recognition tasks efficiently:
\nOnboard Catalog & Create IR Task
\nStep 1: Initiate catalog onboarding by iterating over your source of truth and sending catalog details via POST /catalog-items.
Zia-Capture will automatically pull details, setting Status: Processing.Zia-Capture, the status remains Ready until updated to Capture Needed.Step 2: Retrieve all catalog items using GET /catalog-items and select a list of relevant ones for image recognition.
Step 3: Create an IR task with selected catalog_items via POST /image-recognition/tasks.
Updating Catalog & IR Tasks
Regularly update both the catalog and IR tasks to maintain accuracy and efficiency. This is a process often used to match to the customer image capture workflows, i.e sending images from different geographies, field reps, customers.
/image-recognition/tasks/{task_uuid}.IR Results, in which case you can exclude items from an IR task such that it's not processed by the image recognition process.Congratulations, you are ready for detecting items!
\nDive into the core of image recognition with these workflows:
\nIR Task ID (task_uuid)./image-recognition/tasks/{task_uuid}/urls. Provide images as publicly accessible URLs.IR Result. Image recognition can take longer, depending on the amount of images you're sending and the SLAs agreed upon./v2/image-recognition/tasks/{task_uuid}/results/{result_uuid}.callback URL in the payload triggers an HTTP POST request with the IR result to that URL once each prediction is complete./image-recognition/tasks/{task_uuid}/images with multipart/form-data encoding.\"IR Task (task_uuid)./image-recognition/tasks/{task_uuid}/sync-image. Upload images directly for immediate processing. If the image processing takes longer than the timeout, the response will be returned with empty IR Results and a 408 status code. However, the processing will continue running in the background.IR Results using GET /image-recognition/tasks/{task_uuid}/results/{result_uuid}.Obtain detailed IR Results for comprehensive analysis and utilization:
\n/image-recognition/tasks/{task_uuid}/results/ to fetch results for an entire IR Task or specific images.A sample response for IR Results can be found below
\n{\n\"uuid\": \"123455ab-123\",\n\"task_uuid\": \"5454ad-123\",\n\"image_url\": \"https://storage.googleapis.com/nlb-dev/public/demo.jpeg\",\n\"duration\": 3.5,\n\"created_at\": \"2024-01-01T12:00:00.000Z\",\n\"updated_at\": \"2024-01-01T12:00:00.000Z\",\n\"postprocessing_results\": {\n \"realogram\": [...],\n \"shares\": [...]\n},\n\"coco\": {...},\n\"confidence_score\": 0.98\n}\n\nMaintain the integrity and accuracy of your image recognition system:
\nImprove Accuracy window, where you can add them as real reference crops for such that the image recognition process learns & improves./catalog-items/{item_uuid}/reference-images. Both of these workflows have been designed to enhance the capabilities of the image labelling process.Set the limit of Items you want to Retrieve
\n","type":"text/plain"},"key":"limit","value":"5"},{"disabled":true,"description":{"content":"Retrieve all Items with the given Catalog Name (Optional)
\n","type":"text/plain"},"key":"name","value":""},{"disabled":true,"description":{"content":"Retrieve all Items by the Custom ID field (Optional)
\n","type":"text/plain"},"key":"custom_id","value":""},{"disabled":true,"description":{"content":"Set the position in the dataset for where you want to start retrieval of Items (Optional)
\n","type":"text/plain"},"key":"offset","value":"0"},{"disabled":true,"description":{"content":"Retrieve all items by the Barcode/UPC field
\n","type":"text/plain"},"key":"barcode","value":""}],"variable":[]}},"response":[],"_postman_id":"fffa4138-2ed9-4e5d-b51b-3d25f8c4d2fc"},{"name":"Create Catalog Item","id":"69c3071f-1aab-4029-ad04-58e74a7335e1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"thumbnail","description":"Thumbnail Image (Required)
\n","type":"file","src":"postman-cloud:///1eee644e-d84c-44d0-844e-543ca07d4642"},{"key":"name","value":"UPC Name","description":"Product Name (Required)
\n","type":"text"},{"key":"barcode","value":"","description":"UPC number (Optional)
\n","type":"text","disabled":true},{"key":"custom_id","value":"","description":"Custom ID from Customer Database (Optional)
\n","type":"text","disabled":true},{"key":"brand","value":"","description":"Brand name (Optional)
\n","type":"text","disabled":true},{"key":"container_type","value":"","description":"Type of container (Optional)
\n","type":"text","disabled":true},{"key":"tags","value":"","description":"Comma separated tags (Optional)
\n","type":"text","disabled":true},{"key":"size","value":"","description":"Size of container (Optional)
\n","type":"text","disabled":true},{"key":"height","value":"","description":"Height of Product Item (Optional)
\n","type":"text","disabled":true},{"key":"width","value":"","description":"Width of Product Item (Optional)
\n","type":"text","disabled":true},{"key":"depth","value":"","description":"Depth of Product Item (Optional)
\n","type":"text","disabled":true}]},"url":"https://api.neurolabs.ai/v2/catalog-items","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{api-key}}"}]},"isInherited":true,"source":{"_postman_id":"98d11c1c-4cc4-4bfc-b4b3-7bbc64d29058","id":"98d11c1c-4cc4-4bfc-b4b3-7bbc64d29058","name":"Item Catalog","type":"folder"}},"urlObject":{"path":["catalog-items"],"host":["https://api.neurolabs.ai/v2"],"query":[],"variable":[]}},"response":[],"_postman_id":"69c3071f-1aab-4029-ad04-58e74a7335e1"},{"name":"Upload Reference Images for a catalog item","id":"74272f53-c112-4506-9393-78e30997d4fb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"images","description":"Images to add as real references for an Item
\n","type":"file","src":"postman-cloud:///1eee63a3-56aa-4fe0-9e44-82ad60d9ac08"},{"key":"images","description":"Images to add as real references for an Item
\n","type":"file","src":"postman-cloud:///1eee63a3-56aa-4fe0-9e44-82ad60d9ac08"}]},"url":"https://api.neurolabs.ai/v2/catalog-items/{{item_uuid}}/reference-images","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{api-key}}"}]},"isInherited":true,"source":{"_postman_id":"98d11c1c-4cc4-4bfc-b4b3-7bbc64d29058","id":"98d11c1c-4cc4-4bfc-b4b3-7bbc64d29058","name":"Item Catalog","type":"folder"}},"urlObject":{"path":["catalog-items","{{item_uuid}}","reference-images"],"host":["https://api.neurolabs.ai/v2"],"query":[],"variable":[]}},"response":[],"_postman_id":"74272f53-c112-4506-9393-78e30997d4fb"},{"name":"Create a one-faced asset request","id":"1a21abac-589a-49b0-9d8b-211cd7878a2c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"image","description":"Image to add for one-faced 3D asset
\n","type":"file","src":"postman-cloud:///1eee63a3-56aa-4fe0-9e44-82ad60d9ac08"}]},"url":"https://api.neurolabs.ai/v2/catalog-items/{{item_uuid}}/asset-requests/one-faced-asset","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{api-key}}"}]},"isInherited":true,"source":{"_postman_id":"98d11c1c-4cc4-4bfc-b4b3-7bbc64d29058","id":"98d11c1c-4cc4-4bfc-b4b3-7bbc64d29058","name":"Item Catalog","type":"folder"}},"urlObject":{"path":["catalog-items","{{item_uuid}}","asset-requests","one-faced-asset"],"host":["https://api.neurolabs.ai/v2"],"query":[],"variable":[]}},"response":[],"_postman_id":"1a21abac-589a-49b0-9d8b-211cd7878a2c"}],"id":"98d11c1c-4cc4-4bfc-b4b3-7bbc64d29058","description":"Items are the atomic unit for Neurolabs ZIA Product.
\nThe Neurolabs ZIA API & web application allow you to create, read, update, and delete Items in your catalog. You can also list all available Items and upload 3D assets, digital artwork data, and real reference images to Items.
Thumbnails and names are mandatory and are used to better identify new Items.
\n3D assets are an important part of the Item Catalog as they provide the data necessary to train accurate Computer Vision models that are used within IR Tasks.
Ocassionally, we might want to create a one-faced 3D asset in the case of detecting POS displays, to further enhance our computer vision models.
\nReal Reference Images can be added to the Item Catalog to automatically enhance the performance of the Computer Vision models that power the IR Tasks. These usually come from either Zia-Capture or shelf data cropped items.
Page size limit (Optional)
\n","type":"text/plain"},"key":"limit","value":"50"},{"disabled":true,"description":{"content":"Page offset (Optional)
\n","type":"text/plain"},"key":"offset","value":"0"}],"variable":[]}},"response":[],"_postman_id":"b6ad42a3-143c-4e6d-91ee-b4ccda23eedc"},{"name":"Retrieve single image recognition task","id":"f273c323-573d-4fb6-9c87-fed2d3fa52b8","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"accept":true,"user-agent":true,"accept-encoding":true,"connection":true}},"request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://api.neurolabs.ai/v2/image-recognition/tasks/{{task_uuid}}","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{api-key}}"}]},"isInherited":true,"source":{"_postman_id":"a2dfc610-294c-4122-ae06-d9228e3e778f","id":"a2dfc610-294c-4122-ae06-d9228e3e778f","name":"Task Management","type":"folder"}},"urlObject":{"path":["image-recognition","tasks","{{task_uuid}}"],"host":["https://api.neurolabs.ai/v2"],"query":[],"variable":[]}},"response":[],"_postman_id":"f273c323-573d-4fb6-9c87-fed2d3fa52b8"},{"name":"Create new image recognition task","id":"6e802b5d-9bed-45bb-b8e0-97599dbf5f86","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": {{name}},\n \"catalog_items\": {{catalog_items}},\n \"compute_realogram\": false,\n \"compute_shares\": false\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.neurolabs.ai/v2/image-recognition/tasks","description":"To create a new task, you will need to make a request with the following parameters:
\nname: a string that will be used to identify the task.catalog_items: an array of strings representing the uuids of the items that the task should detect. If no item is selected, the task will only do localisation of the objects present in the image, assigning all detected bounding boxes to the generic object category.realogram: this optional field can be used in case you want to retrieve the placement of items on the shelf, for further analysis.share of shelf: this optional field can be used in case you want to retrieve the share of shelf of each item in your catalog, which can be used for for further analysis.These endpoints allow you to create, read, update, and delete IR Tasks, as well as list all available tasks in your account.
Send Image to a task to analyse
\n","type":"file","value":null}]},"url":"https://api.neurolabs.ai/v2/image-recognition/tasks/{{task_uuid}}/sync-image","description":"This endpoint will start image recognition with existing IR task.
A single image needs to be uploaded using the multipart/form-data encoding method. This endpoint works synchronously, and a new IR Result object will be created and returned in the response when recognition is finished.
If the image recognition takes longer than the timeout, the response will be returned with empty results and a 408 status code. However, the recognition will continue running in the background. To get an update on its status, use the /v2/image-recognition/tasks/{task_uuid}/results/{result_uuid} endpoint.
Send Image to an IR task to label
\n","type":"file","src":"postman-cloud:///1eee644e-d84c-44d0-844e-543ca07d4642"}]},"url":"https://api.neurolabs.ai/v2/image-recognition/tasks/{{task_uuid}}/images","description":"This endpoint will start image recognition with existing image recognition IR Task.
Images need to be uploaded using the multipart/form-data encoding method.
\nA separate IR Result will be created for each specified image and a list of result_uuid will be returned as the response. This endpoint works asynchronously, so returning the actual IR Results will take longer, depending on SLA agreements.
You can track status via /v2/image-recognition/tasks/{task_uuid}/results/{result_uuid} endpoint.
If you provide a value for the callback field in the original payload, after recognition is ready, an HTTP POST request will be sent to the specified url with the IR result as a payload. A callback request will be sent for each IR Result independently as soon as it is ready.
This endpoint will start image recognition using existing IR Task
Images need to be provided in form of publicly accessible http(s) urls or be made accessible for a certain period of time.
\nA separate IR Result will be created for each specified image and a list of result_uuid will be returned as the response. This endpoint works asynchronously, so returning the actual IR Results will take longer, depending on SLA agreements.
You can track status via /v2/image-recognition/tasks/{task_uuid}/results/{result_uuid} endpoint.
If you provide a value for the callback field in the original payload, after recognition is ready, an HTTP POST request will be sent to the specified url with the IR result as a payload. A callback request will be sent for each IR Result independently as soon as it is ready.
These two endpoints provide synchronous and asynchronous ways to start image recognition with existing IR Task configuration.
Maxinum number of image recognition results to return
\n","type":"text/plain"},"key":"limit","value":"50"},{"key":"offset","value":"50"}],"variable":[]}},"response":[],"_postman_id":"d1007c6d-7610-4b7b-a242-ca548446ed6b"},{"name":"Retrieve specific image predictions from a Task","id":"6959e7fb-1587-46e5-9aaf-95eb09631e9f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.neurolabs.ai/v2/image-recognition/tasks/{{task_uuid}}/results/{{result_uuid}}","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"X-API-Key"},{"key":"value","value":"{{api-key}}"}]},"isInherited":true,"source":{"_postman_id":"cfe420bf-55dc-416c-9955-aa8068c6011a","id":"cfe420bf-55dc-416c-9955-aa8068c6011a","name":"Neurolabs API v2","type":"collection"}},"urlObject":{"path":["image-recognition","tasks","{{task_uuid}}","results","{{result_uuid}}"],"host":["https://api.neurolabs.ai/v2"],"query":[],"variable":[]}},"response":[],"_postman_id":"6959e7fb-1587-46e5-9aaf-95eb09631e9f"}],"id":"3212abe0-67a1-4fa1-b53e-8560a63ac7fe","description":"These two endpoints provide all image predictions for a given IR Task via the task_uuid or provide image predictions for a specific IR Task and a specific Image via the result_uuid
We have added a score property that is a float and represents the calculated confidence of our inference. 1 representing a 100% confidence.
The alternative_predictions property field highlights the two next best predictions for an item for which the vision model was deployed. These should be used with caution when integrating and the use case further discussed with the Neurolabs Technical team.
The extra information provided in the neurolabs field is mapped to fields set in Catalog Item. This is useful for mapping back to one's catalog information.
\"neurolabs\": {\"barcode\": \"1000000\",\n \"customId\": \"123456\",\n \"label\": \"Keystone Light 18/12C\",\n \"productUuid\": \"00000000000000000000\"}\n\n