Experiment with this API

Get Metadata for Single Image

This endpoint returns the detailed image metadata for a specified image. Due to a wide variety of available image resolutions, the images are grouped into a handful of size categories for simplicity.

Quickstart

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key. There are several SDKs available for popular programming languages to help you get started.

Use the following endpoint to retrieve metadata for a single image:

GET https://api.gettyimages.com/v3/image?id=<asset id>

Add your API key to the request header:

Api-Key: <your api key>

Your request would look like this using curl:

curl -X GET -H "Api-Key: <your api key>" https://api.gettyimages.com/v3/images?ids=<asset id>

Your response will look like this:

{
    "images": [
    {
        "id": "<asset id>",
        "artist": "GK Hart/Vikki Hart",
        "asset_family": "creative",
        "caption": null,
        "collection_code": "PDI",
        "collection_id": 2,
        "collection_name": "Photodisc",
        "license_model": "royaltyfree",
        "max_dimensions": {
        "height": 4094,
        "width": 4094
        },
        "title": "Kitten"
    }
    ],
    "images_not_found": [

    ]
}

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

The summary_set query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every image in your result set when you include summary_set in your request.

{
    "images":
    [
        "artist",
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

The detail_set query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of images. The following fields are provided for every image in your result set when you include detail_set in your request.

{
    "images":
    [
        "allowed_use",
        "artist", 
        "artist_title", 
        "asset_family",
        "call_for_image",
        "caption", 
        "city",
        "collection_code",
        "collection_id", 
        "collection_name",
        "color_type", 
        "copyright", 
        "country", 
        "credit_line", 
        "date_created", 
        "date_submitted",
        "download_sizes", 
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "prestige",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "state_province", 
        "title"
    ]
}

Display Fields Set

The display_set query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every image in your result set when you include display_set in your request.

{
    "images":
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

Request Usage Considerations

  • Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Request Headers

Api-Key string Provide your API key. Required.
Accept-Language string Specifies the language of result values.
Authorization string Provide access token in the format of 'Bearer {token}'.

URI Path Parameters

id string An image id. For more than one image please use the /v3/images endpoint. Required.

Querystring Parameters

fields array Specifies fields to return. Defaults to 'summary_set'. Possible values: allowed_use alternative_ids artist artist_title asset_family call_for_image caption city collection_code collection_id collection_name color_type comp copyright country credit_line date_camera_shot date_created date_submitted detail_set display_set download_sizes downloads editorial_segments editorial_source entity_details event_ids graphical_style id keywords largest_downloads license_model links max_dimensions orientation people prestige preview product_types quality_rank referral_destinations state_province summary_set thumb title uri_oembed istock_licenses

Response Body Fields

images_detail

images array [ image_detail ] List of image identifiers found.
images_not_found array [ string ] List of image identifiers not found.

image_detail

allowed_use Specifies how customers are allowed to use the image.
alternative_ids array [ KeyValuePair[String,String] ] Lists all of the alternative ids for the asset.
artist string Specifies image creator.
artist_title string Specifies the title given by the artist.
asset_family string Indicates the asset family classification. Possible values are: creative, editorial.
call_for_image boolean Indicates whether a customer needs to call Getty Images in order to license this image.
caption string Gives a brief description of the image.
city string Specifies the city name.
collection_code string Specifies the code of the collection to which the image belongs.
collection_id integer Specifies the id of the collection to which the image belongs.
collection_name string Specifies the name of the collection to which the image belongs.
color_type string Specifies whether the image or video is color or black and white. Possible values are color, black_and_white, and null.
copyright string Specifies the copyright of the image.
country string Specifies the country where the image was created.
credit_line string Specifies the line of copy acknowledging the source or origin of the image.
date_camera_shot string Specifies the date the image was shot, in ISO 8601 format (e.g., 1999-12-31T00:00:00-00:00).
date_created string Specifies the date the image was created, in ISO 8601 format (e.g., 1999-12-31T00:00:00-00:00).
date_submitted string Specifies the date the image was submitted, in ISO 8601 format (e.g., 1999-12-31T00:00:00-00:00).
display_sizes array [ display_size ] Lists the display sizes available for this image.
download_sizes array [ download_size ] Lists the available download size information.
editorial_segments array [ string ] Lists the editorial segments for this asset. Possible values are archival, entertainment, news, publicity, royalty, sport.
editorial_source Specifies the editorial source of the image
event_ids array [ integer ] Lists the events that are relevant for this image.
graphical_style string Specifies the graphical style for the image. Possible values are Photography, Fine Art, and Illustration.
id string Specifies the unique identifier for the image.
keywords array [ keywords ] Lists the keywords that are associated with this image.
largest_downloads array [ download_size ] Lists the available largest download sizes.
license_model string Specifies the licensing model for the image. Possible values are: royaltyfree, rightsmanaged.
links array [ link ] List of links to explore related content, such as similar images and images from the same artist.
max_dimensions Specifies the maximum height and width of any size for this image.
orientation string Specifies the orientation of the image. Possible values are: Horizontal, PanoramicHorizontal, PanoramicVertical, Square, Vertical, and null.
people array [ string ] List of people appearing in the image.
prestige boolean Specifies the image is in the curated Prestige collection.
product_types array [ string ] Lists the product types for the image. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack.
quality_rank integer Specifies the quality ranking of the image.
referral_destinations array [ referral_destination ] Specifies the referral destination for Getty Images assets.
state_province string Specifies the state or province where the image was created.
title string Specifies the image title.
uri_oembed string GET this URI to retrieve oEmbed data for the image, if embeddable.
istock_licenses array [ istock_license ] Contains the cost in iStock credits for all available license types.

allowed_use

how_can_i_use_it string Specifies how the asset can be used.
release_info string Specifies the release status.
usage_restrictions array [ string ] Specifies the asset usage restriction.

KeyValuePair[String,String]

Key string
Value string

display_size

height integer Indicates the image height in pixels.
is_watermarked boolean Indicates whether the image is watermarked.
name string Identifies the name of the display size.
uri string GET this URI to retrieve the display size image.
width integer Indicates the image width in pixels.

download_size

bytes integer Indicates the size in bytes.
downloads array [ download ] Lists the sizes available for download.
height integer Specifies the height in pixels.
media_type string Specifies the file type expressed as internet media content type.
name string Specifies the name of the image size.
width integer Specifies the width in pixels.

download

product_id string Specifies the instance Id of the product.
product_type string Specifies the license agreement applied to this download. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack, sandbox.
uri string POST this URI to download the image.
agreement_name string Specifies the customer-defined name of the Premium Access agreement

EditorialSource

id integer Specifies the editorial source id of the image
name string Specifies the editorial source name of the image

keywords

keyword_id string Specifies the unique identifier for the keyword.
text string Provides localized text of the keyword.
type string Specifies the keyword type.
relevance integer Specifies the relevancy of the keyword to the asset. 0-5 or null, 5 being most relevant.
entity_uris array [ string ] Lists the URIs where detailed information can be found for a specific person.
entity_types array [ string ] Lists the person types for a specific person. E.g., 'Musician', 'Politician'.

download_size

bytes integer Indicates the size in bytes.
downloads array [ download ] Lists the sizes available for download.
height integer Specifies the height in pixels.
media_type string Specifies the file type expressed as internet media content type.
name string Specifies the name of the image size.
width integer Specifies the width in pixels.

download

product_id string Specifies the instance Id of the product.
product_type string Specifies the license agreement applied to this download. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack, sandbox.
uri string POST this URI to download the image.
agreement_name string Specifies the customer-defined name of the Premium Access agreement

link

rel string Specifies the link's relationship to the asset.
uri string GET this URI to retrieve image details regarding the related resource.

max_dimensions

height integer Specifies the height in pixels.
width integer Specifies the width in pixels.

referral_destination

site_name string Specifies the asset domain name.
uri string GET this URI to retrieve appropriate referral destination data.

istock_license

license_type string name of the license_type
credits integer Cost in iStock Credits

Response Status Codes

200 OK
400 InvalidParameterValue
400 MalformedRequest
400 InvalidPage
400 InvalidPageSize
400 ImageIdMustBeSpecified
401 AuthorizationTokenRequired
401 Unauthorized
403 UnauthorizedDisplaySize
404 ImageNotFound

Some response items contain hyperlinks which you can use to take you directly to the next steps in your workflow, when appropriate. The following URIs are provided in the response for this request.

display_size.uri string GET this URI to retrieve the display size image.
download.uri string POST this URI to download the image.
keywords.entity_uris array Lists the URIs where detailed information can be found for a specific person.
download.uri string POST this URI to download the image.
link.uri string GET this URI to retrieve image details regarding the related resource.
referral_destination.uri string GET this URI to retrieve appropriate referral destination data.
image_detail.uri_oembed string GET this URI to retrieve oEmbed data for the image, if embeddable.