Getting Started
Assess the quality of your images and enhance them at scale by applying predefined post-production workflows.
Quick start
Generate your API token
First let's generate your API token from within the web interface.
Send some images to the API
For this quick tutorial, we will send the API a set of 2 food images (also called a batch) and ask for the food workflow to be applied on them .
Note: You can replace the foodworkflow used in this tutorial with any of the custom workflows made available to you
curl "https://api-ai.ocus.com/v1/batches" \
-H "authorization: Bearer MY-TOKEN" -H "Content-type: application/json" --data '
{
"workflow": "food",
"files": [
{"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/06/Pabda_Jhaal_-_Home-_Kolkata_-_West_Bengal.jpg/1280px-Pabda_Jhaal_-_Home-_Kolkata_-_West_Bengal.jpg"},
{"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6f/Easter_breakfast_in_Serbia_%28close-up%29.jpg/1280px-Easter_breakfast_in_Serbia_%28close-up%29.jpg"}
]
}'
As expected the API immediately returns the idof the batch you have just created. This idcan be used to track its details (using API or webhook messages).
Looking at the API response, you also see that the batch is currently in PENDING status.
That means that images were correctly received and are now under processing. Great work!
{
"id": "9a077f0c-f7ab-4828-b496-4f65aa94f6a4",
"workflow": "food",
"status": "PENDING"
}
Visit Create a new batch process from our API reference to interactively create and test your request.
Retrieve quality scores and enhanced images
Now it is time to see how the API performed: you want to retrieve both the detailed quality scores and enhanced version of the images you sent. Using the batch id, this is straightforward:
curl "https://api-ai.ocus.com/v1/batches/9a077f0c-f7ab-4828-b496-4f65aa94f6a4" -H "authorization: Bearer MY-TOKEN"By repeating the above command, you should see the batch status progressively evolve (from initial PENDING status, QUEUED, PROCESSING, COMPLETED). After a few seconds you should get back detailed image quality scores and enhanced versions of the 2 images.
Typically, the response should be similar to:
{
"id": "9a077f0c-f7ab-4828-b496-4f65aa94f6a4",
"status": "COMPLETED",
"label": null,
"project": "mycompany-default",
"success_rate": 1,
"workflow": "food",
"metadata": {},
"created_at": "2023-09-01T12:04:30.000000Z",
"created_by": "[email protected]",
"files": [
{
"status": "ENHANCED",
"metadata": {},
"original": {
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/06/Pabda_Jhaal_-_Home-_Kolkata_-_West_Bengal.jpg/1280px-Pabda_Jhaal_-_Home-_Kolkata_-_West_Bengal.jpg",
"score": 0.6,
"actions": {
"food_is_too_close": {
"type": "QA",
"confidence": 0,
"status": false,
"raw_results": null
},
"food_is_collages": {
"type": "QA",
"confidence": 0,
"status": false,
"raw_results": null
},
"food_has_human": {
"type": "QA",
"confidence": 0.01,
"status": false,
"raw_results": null
},
"food_has_text_or_visual": {
"type": "QA",
"confidence": 0.03,
"status": false,
"raw_results": null
},
"is_blurry": {
"type": "QA",
"confidence": 1,
"status": true,
"raw_results": null
},
"is_bg_uniform": {
"type": "QA",
"confidence": 0.14,
"status": false,
"raw_results": null
}
}
},
"processed": {
"url": "https://ocus-ai-fs-production-media.s3.eu-west-3.amazonaws.com/00000000-0001-abcd-abcd-000000000001/99947dbe-a2af-4288-bbb6-f7d22be3b566/9a077f0c-f7ab-4828-b496-4f65aa94f6a4/9a077f0d-7c04-45f9-9ce6-1cae06f664aa/processed/83aa028113e4d9a7e1a1c5ea7efe44c8.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3B3ZI3LFML5BSKSG%2F20230901%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20230901T120549Z&X-Amz-SignedHeaders=host&X-Amz-Expires=518400&X-Amz-Signature=4c62e0f055768b22a14ff82e430a86479171a8a51158c99d8ee713e089d45d71",
"variations": [
{
"url": "https://ocus-ai-fs-production-media.s3.eu-west-3.amazonaws.com/00000000-0001-abcd-abcd-000000000001/99947dbe-a2af-4288-bbb6-f7d22be3b566/9a077f0c-f7ab-4828-b496-4f65aa94f6a4/9a077f0d-7c04-45f9-9ce6-1cae06f664aa/processed/83aa028113e4d9a7e1a1c5ea7efe44c8.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3B3ZI3LFML5BSKSG%2F20230901%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20230901T120549Z&X-Amz-SignedHeaders=host&X-Amz-Expires=518400&X-Amz-Signature=4c62e0f055768b22a14ff82e430a86479171a8a51158c99d8ee713e089d45d71"
}
],
"actions": {
"food_optional_repair_blurriness": {
"type": "ENHANCE",
"status": true,
},
"improve_colorimetry": {
"type": "ENHANCE",
"status": true,
}
}
}
},
{
"status": "ENHANCED",
"metadata": {},
"original": {
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6f/Easter_breakfast_in_Serbia_%28close-up%29.jpg/1280px-Easter_breakfast_in_Serbia_%28close-up%29.jpg",
"score": 0.5,
"actions": {
"food_is_too_close": {
"type": "QA",
"confidence": 0.3,
"status": false,
"raw_results": null
},
"food_is_collages": {
"type": "QA",
"confidence": 0,
"status": false,
"raw_results": null
},
"food_has_human": {
"type": "QA",
"confidence": 0.03,
"status": false,
"raw_results": null
},
"food_has_text_or_visual": {
"type": "QA",
"confidence": 0.1,
"status": false,
"raw_results": null
},
"is_blurry": {
"type": "QA",
"confidence": 0.01,
"status": false,
"raw_results": null
},
"is_bg_uniform": {
"type": "QA",
"confidence": 0.98,
"status": true,
"raw_results": null
}
}
},
"processed": {
"url": "https://ocus-ai-fs-production-media.s3.eu-west-3.amazonaws.com/00000000-0001-abcd-abcd-000000000001/99947dbe-a2af-4288-bbb6-f7d22be3b566/9a077f0c-f7ab-4828-b496-4f65aa94f6a4/9a077f0d-81d7-4168-b5a7-4f0e75fa0c01/processed/d8cf36e49f05ab8306d78481de74d99f.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3B3ZI3LFML5BSKSG%2F20230901%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20230901T120515Z&X-Amz-SignedHeaders=host&X-Amz-Expires=518400&X-Amz-Signature=7e39d7988771fb96c1d80263a1fec1809857769a0ae9875028b4924b3dd3fa2b",
"variations": [
{
"url": "https://ocus-ai-fs-production-media.s3.eu-west-3.amazonaws.com/00000000-0001-abcd-abcd-000000000001/99947dbe-a2af-4288-bbb6-f7d22be3b566/9a077f0c-f7ab-4828-b496-4f65aa94f6a4/9a077f0d-81d7-4168-b5a7-4f0e75fa0c01/processed/d8cf36e49f05ab8306d78481de74d99f.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3B3ZI3LFML5BSKSG%2F20230901%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20230901T120515Z&X-Amz-SignedHeaders=host&X-Amz-Expires=518400&X-Amz-Signature=7e39d7988771fb96c1d80263a1fec1809857769a0ae9875028b4924b3dd3fa2b"
}
],
"actions": {
"food_optional_repair_blurriness": {
"type": "ENHANCE",
"status": false,
},
"improve_colorimetry": {
"type": "ENHANCE",
"status": true,
},
"optional_replace_background": {
"type": "ENHANCE",
"status": true,
}
}
}
}
],
"links": {
"first": "https://api-ai.ocus.com/v1/batches/9a077f0c-f7ab-4828-b496-4f65aa94f6a4?page=1",
"last": "https://api-ai.ocus.com/v1/batches/9a077f0c-f7ab-4828-b496-4f65aa94f6a4?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://api-ai.ocus.com/v1/batches/9a077f0c-f7ab-4828-b496-4f65aa94f6a4",
"per_page": 1000,
"to": 2,
"total": 2
}
}The answer will contain an array called files. Each element of this array corresponds to one of the submitted images and contains an original and processed fields.
- The image quality scores are visible in the
actionssub-field of theoriginalfield. - The path of the enhanced images are visible in the
urlfield of theprocessedfield. - Some workflows can provide multiple variations of the image, and the
variationsarray will contain every variation
That's it you've submitted your first image batch to OCUS AI API!
Next steps
Do you want to test a workflow? Visit Retrieve batch process to interactively check the results for a given batch.
You can also configure your webhook URL to receive a notification as soon as your results are ready.
Updated 7 months ago