canonical: https://jentic.com/apis/imagga.com/imagga # Imagga Image Recognition API Jentic publishes the only available OpenAPI specification for Imagga Image Recognition API, keeping it validated and agent-ready. Imagga provides image recognition for auto-tagging, categorisation, color extraction, face detection, content moderation, smart cropping, and OCR. Apps upload an image once and reuse the upload ID across multiple analysis endpoints, which keeps bandwidth costs down. The API targets media platforms, e-commerce catalogues, and content moderation pipelines that need a vision layer without training their own models. ## For AI agents Tag, categorise, extract colors from, detect faces in, crop, and run OCR on images using Imagga's REST endpoints with a shared upload ID. ## Scope Does not handle image hosting, transformations, or CDN delivery - use for image recognition tasks like tagging, categorisation, face detection, cropping, and OCR only. ## Capabilities - Auto-tag an uploaded image with confidence scores per tag - Classify an image against a chosen categorizer such as nsfw or personal photos - Extract dominant colors and palettes from an image - Detect faces and compute similarity between two faces - Generate smart crop coordinates that preserve the focal point - Run OCR on an image to extract embedded text - Track API usage so callers can monitor remaining monthly quota ## Use cases ### E-Commerce Catalogue Auto-Tagging Online stores often have thousands of product photos with sparse metadata. Pushing each image to /uploads, calling /tags with the upload ID, and storing the high-confidence tags back on the product record produces a searchable catalogue without manual tagging. The shared upload ID means a single image can also feed /colors and /croppings without re-uploading. Example prompt: POST /uploads with the product image, GET /tags with the upload_id, then write the high-confidence tags back to the product record. ### Content Moderation for User Uploads Social and dating apps need to screen user-uploaded images for NSFW content and unsafe imagery. The /categories/{categorizer_id} endpoint with the nsfw categorizer returns class confidence scores that a moderation queue can act on, blocking or flagging content above a threshold. Example prompt: Upload the user image, call /categories/nsfw_beta with the upload_id, and queue the image for human review if the unsafe class confidence is above 0.7. ### Smart Cropping for Responsive Images Editorial sites need to render hero images at multiple aspect ratios without cutting off the subject. /croppings returns coordinates that preserve the focal point, so a CDN or image proxy can produce 16:9, 1:1, and 4:5 variants from one source image. Combined with /colors, the same upload also yields a placeholder color for skeleton screens. Example prompt: Upload a hero image, call /croppings for each target aspect ratio, and emit the crop coordinates to the image proxy that serves the front page. ### OCR for Receipt Capture Expense apps need to pull text out of photographed receipts. /text returns recognised text from the supplied image, which a downstream parser can map to fields like merchant, total, and date. Pairing this with face detection lets the same pipeline blur faces in any background people accidentally captured. Example prompt: Upload the receipt photo, call /text with the upload_id, and pass the recognised text to the receipt parser. ### Agent-Driven Vision Tasks An AI agent that acts on a user's photo (tag, moderate, crop, extract text) can search Jentic for the right Imagga operation and run it with the upload ID it already holds, rather than chaining HTTP calls by hand. Through Jentic, basic auth credentials stay vaulted and the agent only sees the upload reference. Example prompt: Search Jentic for 'tag an image with Imagga', load the /tags schema, and execute it with the upload ID returned from a prior /uploads call. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /uploads | Upload an image and receive an upload ID | | GET | /tags | Auto-tag an uploaded image | | GET | /categories/{categorizer_id} | Classify against a named categorizer | | GET | /colors | Extract dominant colors | | GET | /faces/detections | Detect faces in an image | | GET | /croppings | Compute smart crop coordinates | | GET | /text | Run OCR on an image | | GET | /usage | Check API usage and remaining quota | ## Key resources - **Uploads** — Upload images for reuse across multiple analysis endpoints. - **Tags** — Auto-tag images with descriptive keywords and confidence scores. - **Categories** — Classify images against named categorizers including NSFW. - **Colors** — Extract dominant color palettes from images. - **Faces** — Detect faces and compare similarity between two faces. - **Croppings** — Compute smart crop coordinates for an image. - **Text** — Run OCR on an image to extract embedded text. - **Usage** — Track API usage and remaining monthly quota. ## Why Jentic - **Setup:** Wiring Imagga by hand means encoding its API key and secret into a Basic auth header against api.imagga.com and tying analysis calls back to an uploaded asset yourself. Through Jentic you install once, import the Imagga Image Recognition API from the API Directory, store the key and secret once, and your agent calls it. - **Permission scoping:** Imagga takes the image or upload reference in the request rather than as a path resource id, so scope the agent to the operations it needs, such as uploading, tagging, and color extraction. Because you choose the allowed operations, an agent limited to tagging never gets face detection or OCR unless you add them. - **Credential handling:** Your Imagga API key and secret are stored once, encrypted, by your own Jentic One instance, and the Basic auth header is generated at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'tag an image' or 'detect faces', and Jentic returns the matching Imagga operation with its query schema, including the upload_id that ties analysis to an uploaded asset, so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Clarifai** — Clarifai offers vision models for tagging, moderation, and custom-trained classifiers. - **OpenAI** — OpenAI's vision-enabled models handle tagging, captioning, and OCR through chat completions. - **Cloudinary Upload API** — Cloudinary handles upload, transformation, and CDN delivery for the same images Imagga analyses. ## FAQ ### Why is there no official OpenAPI spec for Imagga Image Recognition API? Imagga publishes documentation but no canonical OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Imagga via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Imagga API use? The API uses HTTP Basic auth with an API key and secret as the username and password pair. Through Jentic the secret is held in the encrypted vault and the Authorization header is built at execute time. ### Can I run multiple analyses on a single uploaded image? Yes. POST /uploads once and reuse the returned upload_id with /tags, /categories/{categorizer_id}, /colors, /faces/detections, /croppings, and /text without uploading again. ### Does the API support content moderation? Yes. GET /categories/{categorizer_id} with a moderation categorizer returns class confidence scores that a moderation queue can use to flag or block uploads above a chosen threshold. ### How do I tag an image through Jentic? Run pip install jentic, search for 'tag an image with Imagga', load the /tags schema, and execute with the upload_id from a prior /uploads call. The agent receives the high-confidence tags as a structured list. ### How do I check my remaining Imagga quota? GET /usage returns request counts and remaining monthly quota for the authenticated account, which is useful for back-pressure logic in batch jobs. ### Can I limit what my agent is allowed to do with the Imagga Image Recognition API? Yes. Because Jentic One is self-hosted, you decide which Imagga operations the agent may call and which credentials it may use, and Imagga takes the image or upload reference in the request rather than as a path resource id, so you scope by operation. You might allow an agent to upload images, auto-tag them via GET /tags, and extract colors via GET /colors, while withholding face detection at GET /faces/detections, NSFW classification at GET /categories/{categorizer_id}, and OCR at GET /text. An agent limited to tagging never gets face detection or OCR unless you add those operations to its allowed set.