Getty Images

Add a comment to a board

Add an asset to a board

Add assets to a board

Confirm asset change notifications.

# Delete Asset Changes Confirm asset changes acknowledges receipt of asset changes (from the PUT asset-changes endpoint). ## Quickstart You'll need an API key and an access token to use this resource. Use the change_set_id from the PUT asset-changes/change-sets endpoint to confirm receipt of notifications.

Create a new board

Delete a board

Delete a comment from a board

Endpoint for acquiring extended licenses with iStock credits for an asset.

Get a list of asset change notification channels.

# Get Partner Channels Retrieves the channel data for the partner. This data can be used to populate the channel_id parameter in the Put Asset Changes query. ## Quickstart You'll need an API key and an access token to use this resource. Partners who have a channel that has been removed should contact their sales representative to be set up again.

Get all boards that the user participates in

Get asset change notifications.

# Asset Changes Get notifications about new, updated or deleted assets for a specific channel. ## Quickstart You'll need an API key and an access token to use this resource. Maximum batch size is 2200. Change-sets must be confirmed before a new batch of notifications can be retrieved from this endpoint. Use the DELETE asset-changes/change-sets/{change-set-id} endpoint to confirm reciept of these notifications. Values returned for asset_type include Image, Film, and null. Values returned for asset_lifecycle include New, Update, and Delete. Delete notifications may be provided for asset ids that have not previously been received as New or Update notifications. Delete notifications may return null for the asset_type. If there are no notifications in the channel an empty response body will be returned. Notifications older than 60 days will be removed from partner channels.

Get assets and metadata for a specific board

Get comments from a board

Get metadata for a single event

This endpoint returns the detailed event metadata for a specified event. Getty Images news, sports and entertainment photographers and videographers cover editorially relevant events occurring around the world. All images or video clips produced in association with an event, are assigned the same EventID. EventIDs are part of the meta-data returned in SearchForImages Results. Only content produced under a Getty Images brand name (Getty Images News, Getty Images Sports, Getty Images Entertainment, Film Magic, Wire Image) will be consistently assigned an EventID. The Event framework may also be used to group similar content, such as "Hats from the Royal Wedding" or "Odd-ballOffbeat images of the week". You'll need an API key and access token to use this resource.

Get metadata for a single image by supplying one image id

This endpoint returns the detailed image metadata for a specified image. You'll need an API key and access token to use this resource. ## 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", "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. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "images": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ``` ## Request Usage Considerations - Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary. "name": "string", "uri": "string"

Get metadata for a single video by supplying one video id

Use this endpoint to return detailed video metadata for the specified video id. You'll need an API key and access token to use this resource. You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token. ## 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 video in your result set when you include **summary_set** in your request. ``` { "videos": [ "asset_family", "caption", "collection_code", "collection_name", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "license_model", "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 videos. The following fields are provided for every video in your result set when you include **detail_set** in your request. ``` { "videos": [ "allowed_use", "artist", "asset_family", "call_for_image", "caption", "clip_length", "collection_code", "collection_id", "collection_name", "color_type", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "download_sizes", "era", "event_ids", "license_model", "mastered_to", "originally_shot_on", "product_types", "quality_rank", "shot_speed", "source", "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 video in your result set when you include **display_set** in your request. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ], "key_frames": [ { "uri": "<link>" }, { "uri": "<link>" }, { "uri": "<link>" }, { "uri": "<link>" }, { "uri": "<link>" } ] } ``` ## Request Usage Considerations - Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Get metadata for multiple events

This endpoint returns the detailed event metadata for all specified events. Getty Images news, sports and entertainment photographers and videographers cover editorially relevant events occurring around the world. All images or video clips produced in association with an event, are assigned the same EventID. EventIDs are part of the meta-data returned in SearchForImages Results. Only content produced under a Getty Images brand name (Getty Images News, Getty Images Sports, Getty Images Entertainment, Film Magic, Wire Image) will be consistently assigned an EventID. The Event framework may also be used to group similar content, such as "Hats from the Royal Wedding" or "Odd-ballOffbeat images of the week". You'll need an API key and access token to use this resource.

Get metadata for multiple images by supplying multiple image ids

This endpoint returns the detailed image metadata for all specified images. You'll need an API key and access token to use this resource. ## 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", "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. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "images": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ``` ## Request Usage Considerations - Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Get metadata for multiple videos by supplying multiple video ids

Use this endpoint to return detailed video metadata for all the specified video ids. You'll need an API key and access token to use this resource. You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token. ## 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 video in your result set when you include **summary_set** in your request. ``` { "videos": [ "asset_family", "caption", "collection_code", "collection_name", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "license_model", "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 videos. The following fields are provided for every video in your result set when you include **detail_set** in your request. ``` { "videos": [ "allowed_use", "artist", "asset_family", "call_for_image", "caption", "clip_length", "collection_code", "collection_id", "collection_name", "color_type", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "download_sizes", "era", "event_ids", "license_model", "mastered_to", "originally_shot_on", "product_types", "quality_rank", "shot_speed", "source", "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 video in your result set when you include **display_set** in your request. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "videos": [ { "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ], "key_frames": [ { "uri": "<link>" }, { "uri": "<link>" }, { "uri": "<link>" }, { "uri": "<link>" }, { "uri": "<link>" } ] } ] } ``` ## Request Usage Considerations - Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Get order metadata

This endpoint returns detailed order metadata for a specified order. Use of this endpoint requires configuration changes to your API key. You'll need an API key and access token to use this resource.

Get Previously Purchased Images and Video

This endpoint returns a list of all assets purchased on gettyimages.com by the username used for authentication. Use of this endpoint requires configuration changes to your API key. Please contact your sales representative to learn more. You'll need an API key and access token to use this resource.

Get Products

This endpoint returns all products available to the username used during authentication. As such, this endpoint requires the use of a fully authorized access_token. The product data can then be used as search filters, restricting results to images from a specific product. You'll need an API key and access token to use this resource.

get_v3_affiliates_search_images

get_v3_affiliates_search_videos

get_v3_asset_management_assets_send_events

Gets collections applicable for the customer.

Use this endpoint to retrieve collections associated with your Getty Images account. To browse available collections see our [Image collections page]( http://www.gettyimages.com/creative-images/collections). You'll need an API key and access token to use this resource.

Gets countries codes and names.

Returns a list of country objects that contains country name, two letter ISO abbreviation and three letter ISO abbreviation. You'll need an API key and access token to use this resource.

Remove an asset from a board

Remove assets from a board

Retrieve creative images from the same series

This endpoint will provide the list of images, if any exist, from the same series as the specified creative asset id. These images are typically from the same photo shoot. This functionality will not work for editorial assets. You'll need an API key and access token to use this resource. ## 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": [ "asset_family", "caption", "collection_code", "collection_id", "collection_name", "display_sizes": [ { "name": "thumb" } ] "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", "asset_family", "call_for_image", "caption", "collection_code", "collection_id", "collection_name", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "editorial_segments", "event_ids", "graphical_style", "license_model", "max_dimensions", "orientation", "product_types", "quality_rank", "referral_destinations", "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. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "images": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Retrieve creative videos from the same series

This endpoint will provide the list of videos, if any exist, from the same series as the specified creative asset id. These images are typically from the same photo shoot. This functionality will not work for editorial assets. You'll need an API key and access token to use this resource. ## 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 video in your result set when you include **summary_set** in your request. ``` { "videos": [ "asset_family", "caption", "collection_code", "collection_name", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "license_model", "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 videos. The following fields are provided for every video in your result set when you include **detail_set** in your request. ``` { "videos": [ "allowed_use", "artist", "asset_family", "call_for_image", "caption", "clip_length", "collection_code", "collection_id", "collection_name", "color_type", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "download_sizes", "era", "license_model", "mastered_to", "originally_shot_on", "product_types", "quality_rank", "shot_speed", "source", "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 video in your result set when you include **display_set** in your request. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "videos": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Retrieve similar images

This endpoint will provide a list of images that are similar to the specified asset id. You'll need an API key and access token to use this resource. ## 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": [ "asset_family", "caption", "collection_code", "collection_id", "collection_name", "display_sizes": [ { "name": "thumb" } ] "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", "asset_family", "call_for_image", "caption", "collection_code", "collection_id", "collection_name", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "editorial_segments", "event_ids", "graphical_style", "license_model", "max_dimensions", "orientation", "product_types", "quality_rank", "referral_destinations", "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. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "images": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Retrieve similar videos

This endpoint will provide a list of videos that are similar to the specified asset id. You'll need an API key and access token to use this resource. ## 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 video in your result set when you include **summary_set** in your request. ``` { "videos": [ "asset_family", "caption", "collection_code", "collection_name", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "license_model", "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 videos. The following fields are provided for every video in your result set when you include **detail_set** in your request. ``` { "videos": [ "allowed_use", "artist", "asset_family", "call_for_image", "caption", "clip_length", "collection_code", "collection_id", "collection_name", "color_type", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "download_sizes", "era", "event_ids", "license_model", "mastered_to", "originally_shot_on", "product_types", "quality_rank", "shot_speed", "source", "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 video in your result set when you include **display_set** in your request. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "videos": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Returns information about the current user.

Returns the first, middle and last name of the authenticated user. You'll need an API key and access token to use this resource. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens.

Search for creative images based on url

Search for **similar creative images** by passing an `image_url` to an uploaded image OR an `asset_id` of an asset in our catalog. All responses will have the `exclude_nudity` filter automatically applied. ## Searching by URL Before calling the search by image endpoint, an image in JPEG format must be uploaded to `https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}`, where the client defines the `{CLIENT_IMAGE.jpg}` portion of the URL. For example, using cURL: ``` sh curl -i -X PUT https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg -H 'Content-Type: image/jpeg' -H 'Api-Key: API_KEY' --data-binary "@testimage.jpg" ``` Once the image has been uploaded, use the full URL in the `image_url` parameter, e.g. `image_url=https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg`. - Uploaded files must be 10MB or smaller. - Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately. - Uploads expire after 24 hours. - Uploads and searches must be performed using the _same_ API Key. ## Searching by asset id When searching by `asset_id`, any image or video asset id in the Getty/iStock catalog can be used as the source for similar images.

Search for creative images only

Use this endpoint to search our contemporary stock photos, illustrations and archival images. You'll need an API key and access token to use this resource. You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token. Search requests without a phrase parameter are not supported and may not always work. ## 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": [ "asset_family", "caption", "collection_code", "collection_id", "collection_name", "display_sizes": [ { "name": "thumb" } ], "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", "asset_family", "call_for_image", "caption", "collection_code", "collection_id", "collection_name", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "editorial_segments", "event_ids", "graphical_style", "license_model", "max_dimensions", "orientation", "product_types", "quality_rank", "referral_destinations", "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. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "images": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Search for creative videos

Use this endpoint to search premium stock video, from archival film to contemporary 4K and HD footage. You'll need an API key and access token to use this resource. You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens. Search requests without a phrase parameter are not supported and may not always work. ## 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 video in your result set when you include **summary_set** in your request. ``` { "videos": [ "asset_family", "caption", "collection_code", "collection_name", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "license_model", "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 videos. The following fields are provided for every video in your result set when you include **detail_set** in your request. ``` { "videos": [ "allowed_use", "artist", "asset_family", "call_for_image", "caption", "clip_length", "collection_code", "collection_id", "collection_name", "color_type", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "era", "license_model", "mastered_to", "originally_shot_on", "product_types", "quality_rank", "shot_speed", "source", "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 video in your result set when you include **display_set** in your request. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "videos": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Search for creative videos based on url

Search for **similar creative videos** by passing an `image_url` to an uploaded image/frame grab from a video OR an `asset_id` of an asset in our catalog. All responses will have the `exclude_nudity` filter automatically applied. ## Searching by URL Before calling the search by image endpoint, an image or frame grab in JPEG format must be uploaded to `https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}`, where the client defines the `{CLIENT_IMAGE.jpg}` portion of the URL. For example, using cURL: ``` sh curl -i -X PUT https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg -H 'Content-Type: image/jpeg' -H 'Api-Key: API_KEY' --data-binary "@testimage.jpg" ``` Once the image has been uploaded, use the full URL in the `image_url` parameter, e.g. `image_url=https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg`. - Uploaded files must be 10MB or smaller - Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately. - Uploads expire after 24 hours. - Uploads and searches must be performed using the _same_ API Key. ## Searching by asset id When searching by `asset_id`, any image or video asset id in the Getty/iStock catalog can be used as the source for similar videos.

Search for editorial images only

Use this endpoint to search our editorial stock photos, illustrations and archival images. Editorial images represent newsworthy events or illustrate matters of general interest, such as news, sport and entertainment and are generally intended for editorial use. You'll need an API key and access token to use this resource. You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token. To include your API token in the search request, add it to the headers as a Bearer token (example in curl): -H "Authorization: Bearer <your-token>" Search requests without a phrase parameter are not supported and may not always work. ## 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": [ "asset_family", "caption", "collection_code", "collection_id", "collection_name", "display_sizes": [ { "name": "thumb" } ], "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", "asset_family", "call_for_image", "caption", "collection_code", "collection_id", "collection_name", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "editorial_segments", "event_ids", "graphical_style", "license_model", "max_dimensions", "orientation", "product_types", "quality_rank", "referral_destinations", "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. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "images": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Search for editorial videos

Use this endpoint to search current and archival video clips of celebrities, newsmakers, and events. You'll need an API key and access token to use this resource. You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token. Search requests without a phrase parameter are not supported and may not always work. ## 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 video in your result set when you include **summary_set** in your request. ``` { "videos": [ "asset_family", "caption", "collection_code", "collection_name", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "license_model", "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 videos. The following fields are provided for every video in your result set when you include **detail_set** in your request. ``` { "videos": [ "allowed_use", "artist", "asset_family", "call_for_image", "caption", "clip_length", "collection_code", "collection_id", "collection_name", "color_type", "copyright", "date_created", "display_sizes": [ { "name": "comp" }, { "name": "preview" }, { "name": "thumb" } ], "era", "event_ids", "license_model", "mastered_to", "originally_shot_on", "product_types", "quality_rank", "shot_speed", "source", "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 video in your result set when you include **display_set** in your request. The URI provided is subject to change at any time and must be used as-is with no modification. ``` { "videos": [ "display_sizes": [ { "is_watermarked": <boolean>, "name": "comp", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "preview", "uri": "<link>" }, { "is_watermarked": <boolean>, "name": "thumb", "uri": "<link>" } ] ] } ```

Search for events

Use this endpoint to search Getty Images news, sports and entertainment events. Getty Images photographers and videographers cover editorially relevant events occurring around the world. All images or video clips produced in association with an event, are assigned the same EventID. EventIDs are part of the meta-data returned in Search Results. Only content produced under a Getty Images brand name (Getty Images News, Getty Images Sports, Getty Images Entertainment, Film Magic, Wire Image) will be consistently assigned an EventID. The Event framework may also be used to group similar content, such as "Hats from the Royal Wedding" or "Odd-ballOffbeat images of the week". You'll need an API key and access token to use this resource. You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token.

Search for images by a photographer

Search for videos by a photographer

Update a board