Semantic Data Extraction

Image & Video APIs

Last updated: Dec-11-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.

On this page:

Data extraction while uploading
Data extraction on already uploaded images
Sample response
Clara Denari mini-mystery challenge

Clara Denari's Mini Mystery: The Sapphire Earring Match

Clara found sapphire earrings in her backyard. Her neighbor Mrs. Patterson claims they're hers, a family heirloom, and has an old photo to prove it. Clara restored the blurry photo using Cloudinary's AI. They look pretty similar, but something feels off...

Help Clara confirm whether it's an exact match. Extract the earrings from the photo and analyze their exact color to see if Mrs. Patterson's story holds up!

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

🔬 The Color Lab Analysis

A Clara Denari Mini Mystery, Part 2

Clara Denari

Welcome to my color lab! 🔬

I found sapphire earrings in my backyard. My neighbor Mrs. Patterson claims they're hers and showed me an old photo of her grandmother wearing similar ones. The photo was blurry, so I uploaded a restored version using Cloudinary's AI.

The earrings look similar, but are they the same?

Let's use Cloudinary to extract just the earring from the restored photo, upload that isolated earring image with color analysis enabled, and compare its predominant colors to my earrings.

If the colors don't match, Mrs. Patterson has some explaining to do! 🕵️‍♀️

🔍 Evidence to Analyze

My earrings

Restored photo

Clara Denari

The extraction worked! 🎉 Now I can see just the earrings.

Next step: upload this extracted image with color analysis enabled. Cloudinary will tell us the exact colors!

Edit the starter code below for your SDK. Replace the placeholders with these parameters:

colors: true: extracts predominant colors

public_id: 'cropped_earrings': the asset name

asset_folder: 'evidence': organize in a folder

✂️ Extracted Earrings

Upload this image

Source: https://res.cloudinary.com/demo/image/upload/e_extract:prompt:earring/c_crop,g_earring,w_100/f_auto/q_auto/restored_earrings.jpg

Your upload command:

Clara Denari

Perfect! The upload worked and Cloudinary analyzed the colors! 🎨

Now, look at the colors array in the response. I need the predominant non-white color. That's the first blue/indigo color (skip the white ones at the top).

Find the hex code and enter it below. This is the moment of truth! 🔍

📊 Color Analysis Response

{
  "asset_id": "a1b2c3d4e5f6g7h8i9j0",
  "public_id": "cropped_earrings",
  "version": 1763564796,
  "width": 100,
  "height": 100,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2024-01-15T10:30:00Z",
  "bytes": 12345,
  "type": "upload",
  "url": "http://res.cloudinary.com/.../cropped_earrings.jpg",
  "secure_url": "https://res.cloudinary.com/.../cropped_earrings.jpg",
  "asset_folder": "evidence",
  "colors": [
    ["#FCFCFB", 53.9],
    ["#404169", 10.0],
    ["#E3E3EA", 10.3]
  ],
  "predominant": {
    "google": [["white", 73.0], ["blue", 18.8]],
    "cloudinary": [["white", 73.0], ["blue", 18.8]]
  },
  "original_filename": "cropped_earrings"
}