Semantic data extraction
Last updated: Nov-25-2025
When you upload an asset to Cloudinary, the upload API response includes basic information about the uploaded image such as width, height, number of bytes, format, and more. By default, the following semantic data is automatically included in the upload response as well: ETag, any face or custom coordinates, and the number of pages (or layers) in "paged" files.
Cloudinary supports extracting additional semantic data from the uploaded image such as: media metadata (including Exif, IPTC, XMP and GPS), color histogram, predominant colors, custom coordinates, pHash image fingerprint, ETag, and face and/or text coordinates. You request the inclusion of this additional information in the upload response by including one or more optional parameters.
You can request data extraction while uploading an image, or by using the explicit method on an already uploaded image.
Clara Denari's Mini Mystery: The Sapphire Earring Match
Clara found sapphire earrings in her backyard, but her neighbor claims they're a family heirloom with an old photo to prove it. Clara already restored the photo by uploading it to Cloudinary.
Now, using Cloudinary's analysis capabilities, help Clara extract the earrings from the restored photo and analyze their color to verify if they match the ones she found.
Data extraction while uploading
The following example uploads an image and requests the pHash value, a color analysis, and the media metadata:
Data extraction on already uploaded images
There are two ways to request data extraction on already uploaded images:
- Use the Explicit method of the Upload API to request data extraction on a single asset. This method is not rate-limited and requires a signature to be generated on the server side.
- Use the Update resources method of the Admin API. This method is rate-limited and requires your API key and secret, so is not suitable for use in client-side code.
Explicit example
The following example uses the Explicit method of the Upload API to request the pHash value, a color analysis, and the media metadata on an uploaded image with a public ID of "couple1":
Update resources example
The following example uses the Update resources method of the Admin API to request the pHash value, a color analysis, and the media metadata on an uploaded image with a public ID of "table":
Sample response
The following is an example of a JSON response returned with the following additional information: media_metadata, colors,and phash:
Clara Denari mini-mystery challenge
Mini Mystery: The Sapphire Earring Match
Clara found sapphire earrings in her backyard, but her neighbor claims they're a family heirloom and provided an old photo to prove it. Clara already restored the photo by uploading it to Cloudinary.
Now, help Clara extract the earrings from the restored photo and analyze their color to verify if they match the ones she found.
The earrings Clara found
The restored photograph from the neighbor
Goal: Extract the earrings from the neighbor's restored photo, upload it with color analysis enabled, and compare the predominant color to determine if they match Clara's earrings.
Step 1 - Construct the extraction URL:
Construct a Cloudinary URL that extracts and crops the earrings from the neighbor's photo. You'll need these transformation groups (separated by forward slashes):
-
e_extract:prompt:earring- uses generative AI to extract the earrings from the image -
c_crop,g_auto:earring- crops the image to focus on the earrings (note: comma-separated parameters) -
w_100,h_120- resizes to 100x120 pixels for detailed color analysis (note: comma-separated parameters)
Base image URL: https://res.cloudinary.com/demo/image/upload/v1763564796/restored_earrings.jpg
Insert the transformations between /upload/ and /v1763564796/. Separate parameters within a group with commas, and separate transformation groups with forward slashes.
Step 2 - Upload the extracted image with color analysis:
Create an upload call to upload the extracted earring image URL using these parameters:
-
colors: true- extracts predominant colors from the image -
public_id: 'cropped_earrings'- gives the asset a specific identifier -
asset_folder: 'evidence'- organizes it into a folder
Use this URL as the source: https://res.cloudinary.com/demo/image/upload/e_extract:prompt:earring/c_crop,g_auto:earring,w_100,h_120/v1763564796/restored_earrings.jpg
Step 3 - Identify the predominant color:
Examine the upload response below and find the predominant non-white color. This will be the first indigo/blue color in the colors array (skip the white colors at the top).
Enter the predominant non-white color hex code:
Upload Response (colors data)
{
"asset_id": "abc123def456...",
"public_id": "cropped_earrings",
"width": 100,
"height": 120,
"format": "jpg",
"secure_url": "https://res.cloudinary.com/demo/image/upload/v1763671172/cropped_earrings.jpg",
"colors": [
["#FCFCFB", 53.9],
["#404169", 10.0],
["#E3E3EA", 10.3]
],
"predominant": {
"google": [
["white", 73.0],
["blue", 18.8],
["gray", 4.3]
]
}
}Color Comparison Results
Earrings Clara Found
#3B3D81 (Deep Slate Blue)
Photo Earrings (Predominant Color)
#404169 (Indigo Blue)
Conclusion: The colors don't match! Clara's earrings are deep slate blue (#3B3D81), while the earrings in the neighbor's photo are indigo blue (#404169). Although both are blue tones, the color analysis reveals they are different shades. The earrings Clara found do not belong to her neighbor!
How This Analysis Worked:
Used AI to extract and crop just the earrings from the restored photo
Analyzed the uploaded image to extract color information and identify the predominant color
Compared the analyzed color against the known color of Clara's found earrings
Real-World Value
This mystery demonstrates Cloudinary's color analysis capabilities, which are valuable for:
- E-commerce: Automatically categorize products by color for filtering and search, and arrange like colors together on a website
- Brand consistency: Verify uploaded images match brand color guidelines
- Image organization: Auto-tag and organize photos based on predominant colors
- Accessibility: Analyze color contrast for WCAG compliance
Note: Color analysis is performed server-side during upload or when updating an asset using the explicit method.
Security reminder: Never expose API secrets in client-side code. This interactive mystery simulates the upload process for educational purposes only. Real uploads must be performed server-side.
See the blog post on API for extracting semantic image data - colors, faces, Exif data and more for more information on semantic data extraction.
Error
Rate this page:
