Getty Images

App · 25 actions

Search Getty Images photos, videos, and events, retrieve asset details, and manage boards.

Actions

ActionWhat it does
Add board assetAdd an asset to a board
Create boardCreate a new board
Delete boardDelete a board
Get boardGet assets and metadata for a specific board
Get customerGet information about the current user.
Get imageGet metadata for a single image by supplying one image id
Get imagesGet metadata for multiple images by supplying multiple image ids
Get videoGet metadata for a single video by supplying one video id
Get videosGet metadata for multiple videos by supplying multiple video ids
List boardsGet all boards that the user participates in
List collectionsGet collections applicable for the customer.
List countriesGet countries codes and names.
List image seriesRetrieve creative images from the same series
List productsGet Products
List similar imagesRetrieve similar images
List similar videosRetrieve similar videos
List video seriesRetrieve creative videos from the same series
Remove board assetRemove an asset from a board
Search creative imagesSearch for creative images only
Search creative videosSearch for creative videos
Search editorial imagesSearch for editorial images only
Search editorial videosSearch for editorial videos
Search eventsSearch for events
Search imagesSearch for both creative and editorial images (deprecated)
Update boardUpdate a board

Add board asset

Add an asset to a board

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Board idboard_idtextRequired
Specifies the board to add an asset to.
Asset idasset_idtextRequired
Specifies the asset to add to the board. If it is already in the board's asset collection, no action is taken.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {}
}

Create board

Create a new board

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
NamenametextRequired
Name.
Descriptiondescriptiontext
Description.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "id": "example"
  }
}

Delete board

Delete a board

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Board idboard_idtextRequired
Specifies the board to delete.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {}
}

Get board

Get assets and metadata for a specific board

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Board idboard_idtextRequired
Retrieve details for a specific board.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "asset_count": 1,
    "assets": [],
    "comment_count": 1,
    "date_created": "example",
    "date_last_updated": "example",
    "description": "example",
    "id": "example",
    "links": {
      "invitation": "example",
      "share": "example"
    },
    "name": "example",
    "permissions": {
      "can_add_assets": false,
      "can_delete_board": false,
      "can_invite_to_board": false,
      "can_remove_assets": false,
      "can_update_description": false,
      "can_update_name": false
    }
  }
}

Get customer

Get information about the current user.

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "first_name": "example",
    "last_name": "example",
    "middle_name": "example"
  }
}

Get image

Get metadata for a single image by supplying one image id

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
IdidtextRequired
An image id. For more than one image please use the /v3/images endpoint.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.One or more of: allowed_use (Allowed use), alternative_ids (Alternative ids), artist, artist_title (Artist title), asset_family (Asset family), call_for_image (Call for image), caption, city, collection_code (Collection code), collection_id (Collection id), and 41 more.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "images": [],
    "images_not_found": []
  }
}

Get images

Get metadata for multiple images by supplying multiple image ids

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Idsidslist
Specifies one or more image ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.One or more of: allowed_use (Allowed use), alternative_ids (Alternative ids), artist, artist_title (Artist title), asset_family (Asset family), call_for_image (Call for image), caption, city, collection_code (Collection code), collection_id (Collection id), and 41 more.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "images": [],
    "images_not_found": []
  }
}

Get video

Get metadata for a single video by supplying one video id

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
IdidtextRequired
A video id. For more than one video please use the /v3/video endpoint.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.One or more of: id, allowed_use (Allowed use), artist, asset_family (Asset family), call_for_image (Call for image), caption, city, clip_length (Clip length), collection_code (Collection code), collection_id (Collection id), and 38 more.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "allowed_use": {
      "editorial_use_only": false,
      "how_can_i_use_it": "example",
      "release_info": "example",
      "usage_restrictions": []
    },
    "alternative_ids": {},
    "artist": "example",
    "asset_family": "example",
    "call_for_image": false,
    "caption": "example",
    "city": "example",
    "clip_length": "example",
    "collection_code": "example",
    "collection_id": 1,
    "collection_name": "example",
    "color_type": "example",
    "copyright": "example",
    "country": "example",
    "date_created": "example",
    "date_submitted": "example",
    "display_sizes": [],
    "download_product": "example",
    "download_sizes": [],
    "editorial_segments": [],
    "era": "example",
    "event_ids": [],
    "id": "example",
    "is_ai_editable": false,
    "istock_collection": "example",
    "istock_exclusive": false,
    "istock_licenses": [],
    "istock_sub_collection": "example",
    "key_frames": [],
    "keywords": [],
    "license_model": "example",
    "mastered_to": "example",
    "max_dimensions": {
      "height": 1,
      "width": 1
    },
    "object_name": "example",
    "orientation": "example",
    "originally_shot_on": "example",
    "people": [],
    "product_types": [],
    "quality_rank": 1,
    "referral_destinations": [],
    "shot_speed": "example",
    "source": "example",
    "state_province": "example",
    "title": "example"
  }
}

Get videos

Get metadata for multiple videos by supplying multiple video ids

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Idsidslist
Specifies one or more video ids to return. Use comma delimiter when requesting multiple ids. Maximum of 100 ids.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.One or more of: id, allowed_use (Allowed use), artist, asset_family (Asset family), call_for_image (Call for image), caption, city, clip_length (Clip length), collection_code (Collection code), collection_id (Collection id), and 38 more.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "videos": [],
    "videos_not_found": []
  }
}

List boards

Get all boards that the user participates in

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Pagepagenumber
Request results starting at a page number (default is 1).Default: 1.
Board relationshipboard_relationshiptext
Search for boards the user owns or has been invited to as an editor.One of: owned, invited.
Sort ordersort_ordertext
Sort the list of boards by last update date or name. Defaults to date_last_updated_descending.One of: date_last_updated_descending (Date last updated descending), date_last_updated_ascending (Date last updated ascending), name_ascending (Name ascending), name_decending (Name decending).
Page sizepage_sizenumber
Request number of boards to return in each page. (default is 30).Default: 30.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "board_count": 1,
    "boards": []
  }
}

List collections

Get collections applicable for the customer.

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "collections": []
  }
}

List countries

Get countries codes and names.

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "countries": []
  }
}

List image series

Retrieve creative images from the same series

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
IdidtextRequired
Identifies an existing image
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.One or more of: accessrestriction, allowed_use (Allowed use), alternative_ids (Alternative ids), artist, asset_family (Asset family), call_for_image (Call for image), caption, collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), and 30 more.
Pagepagenumber
Identifies page to return. Default is 1.Default: 1.
Page sizepage_sizenumber
Specifies page size. Default is 30, maximum page_size is 100.Default: 30.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "images": [],
    "related_searches": [],
    "result_count": 1
  }
}

List products

Get Products

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Fieldsfieldslist
Comma separated list of fields. Allows product download requirements to be returned.One or more of: download_requirements (Download requirements).

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "products": []
  }
}

List similar images

Retrieve similar images

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
IdidtextRequired
Identifies an existing image
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.One or more of: accessrestriction, allowed_use (Allowed use), alternative_ids (Alternative ids), artist, asset_family (Asset family), call_for_image (Call for image), caption, collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), and 30 more.
Pagepagenumber
Identifies page to return. Default is 1.Default: 1.
Page sizepage_sizenumber
Specifies page size. Default is 30, maximum page_size is 100.Default: 30.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "images": [],
    "related_searches": [],
    "result_count": 1
  }
}

List similar videos

Retrieve similar videos

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
IdidtextRequired
A video id.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.One or more of: allowed_use (Allowed use), artist, aspect_ratio (Aspect ratio), asset_family (Asset family), call_for_image (Call for image), caption, clip_length (Clip length), collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), and 29 more.
Pagepagenumber
Identifies page to return. Default is 1.Default: 1.
Page sizepage_sizenumber
Specifies page size. Default is 30, maximum page_size is 100.Default: 30.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "related_searches": [],
    "result_count": 1,
    "videos": []
  }
}

List video series

Retrieve creative videos from the same series

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
IdidtextRequired
Identifies an existing video
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.One or more of: allowed_use (Allowed use), artist, aspect_ratio (Aspect ratio), asset_family (Asset family), call_for_image (Call for image), caption, clip_length (Clip length), collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), and 29 more.
Pagepagenumber
Identifies page to return. Default is 1.Default: 1.
Page sizepage_sizenumber
Specifies page size. Default is 30, maximum page_size is 100.Default: 30.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "related_searches": [],
    "result_count": 1,
    "videos": []
  }
}

Remove board asset

Remove an asset from a board

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Board idboard_idtextRequired
Specifies the board to remove an asset from.
Asset idasset_idtextRequired
Specifies the asset to remove from the board.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {}
}

Search creative images

Search for creative images only

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Gi-country-codegi_country_codetext
Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
Age of peopleage_of_peoplelist
Filter based on the age of individuals in an image.One or more of: newborn, baby, child, teenager, young_adult (Young adult), adult, adults_only (Adults only), mature_adult (Mature adult), senior_adult (Senior adult), 0-1_months (0-1 months), and 32 more.
Artistsartiststext
Search for images by specific artists (free-text, comma-separated list of artists).
Collection codescollection_codeslist
Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
Collections filter typecollections_filter_typetext
Use to include or exclude collections from search. The default is includeOne of: include, exclude.
Colorcolortext
Filter based on predominant color in an image. Use 6 character hexadecimal format (e.g., #002244).
Compositionscompositionslist
Filter based on image composition.One or more of: abstract, candid, close_up (Close up), copy_space (Copy space), cut_out (Cut out), full_frame (Full frame), full_length (Full length), headshot, looking_at_camera (Looking at camera), macro, and 8 more.
Download productdownload_producttext
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example,.
Embed content onlyembed_content_onlytrue/false
Restrict search results to embeddable images. The default is false.Default: false.
Enhanced searchenhanced_searchtrue/false
If set to `false`, your search will not use enhanced search. Defaults to `true`.Default: true.
Ethnicityethnicitylist
Filter search results based on the ethnicity of individuals in an image.One or more of: black, white, east_asian (East asian), hispanic_latinx (Hispanic latinx), japanese, middle_eastern (Middle eastern), multiracial_person (Multiracial person), multiethnic_group (Multiethnic group), native_american_first_nations (Native american first nations), pacific_islander (Pacific islander), south_asian (South asian), southeast_asian (Southeast asian).
Exclude editorial use onlyexclude_editorial_use_onlytrue/false
Exclude images that are only available for editorial (non-commercial) use. Default value is false.
Exclude keyword idsexclude_keyword_idslist
Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned.
Exclude nudityexclude_nuditytrue/false
Excludes images containing nudity. The default is false.Default: false.
Facet fieldsfacet_fieldslist
Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.One or more of: artists, locations.
Facet max countfacet_max_countnumber
Specifies the maximum number of facets to return per type. Default is 300.Default: 300.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.One or more of: allowed_use (Allowed use), alternative_ids (Alternative ids), artist, asset_family (Asset family), call_for_image (Call for image), caption, collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), color_type (Color type), and 26 more.
File typesfile_typeslist
Return only images having a specific file type.One or more of: eps.
Graphical stylesgraphical_styleslist
Filter based on graphical style of the image.One or more of: fine_art (Fine art), illustration, photography, vector.
Graphical styles filter typegraphical_styles_filter_typetext
Provides searching based on specified graphical style(s). The default is include.One of: include, exclude.
Include facetsinclude_facetstrue/false
Specifies whether or not to include facets in the result set. Default is "false".
Include related searchesinclude_related_searchestrue/false
Specifies whether or not to include related searches in the response. The default is false.Default: false.
Istock exclusiveistock_exclusivetrue/false
Restricts results to iStock exclusive assets when true, or non-exclusive assets when false. The default is null (no filter).
Keyword idskeyword_idslist
Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
Minimum sizeminimum_sizetext
Filter based on minimum size requested. The default is x-small.One of: x_small (X small), small, medium, large, x_large (X large), xx_large (Xx large), vector.
Moodsmoodslist
Filter based on predominant mood in an image.One or more of: black_and_white (Black and white), bold, cool, dramatic, natural, vivid, warm.
Number of peoplenumber_of_peoplelist
Filter based on the number of people in the image.One or more of: none, one, two, group.
Orientationsorientationslist
Return only images with selected aspect ratios.One or more of: horizontal, vertical, square, panoramic_horizontal (Panoramic horizontal), panoramic_vertical (Panoramic vertical).
Pagepagenumber
Request results starting at a page number (default is 1).Default: 1.
Page sizepage_sizenumber
Request number of images to return in each page. Default is 30, maximum page_size is 100.Default: 30.
Phrasephrasetext
Search images using a search phrase.
Safe searchsafe_searchtrue/false
Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter..Default: false.
Sort ordersort_ordertext
Select sort order of results. The default is best_matchOne of: best_match (Best match), most_popular (Most popular), newest, random.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "images": [],
    "related_searches": [],
    "result_count": 1
  }
}

Search creative videos

Search for creative videos

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Gi-country-codegi_country_codetext
Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
Age of peopleage_of_peoplelist
Provides filtering according to the age of individuals in a video.One or more of: newborn, baby, child, teenager, young_adult (Young adult), adult, adults_only (Adults only), mature_adult (Mature adult), senior_adult (Senior adult), 0-1_months (0-1 months), and 32 more.
Artistsartiststext
Search for videos by specific artists (free-text, comma-separated list of artists).
Aspect ratiosaspect_ratioslist
Search for videos by specific aspect ratios.One or more of: 16:9, 9:16, 3:4, 4:3, 4:5, 2:1, 17:9, 9:17.
Collection codescollection_codeslist
Provides filtering by collection code.
Collections filter typecollections_filter_typetext
Use to include or exclude collections from search. The default is includeOne of: include, exclude.
Compositionscompositionslist
Filter based on video composition.One or more of: abstract, candid, close_up (Close up), copy_space (Copy space), cut_out (Cut out), full_frame (Full frame), full_length (Full length), headshot, looking_at_camera (Looking at camera), macro, and 8 more.
Download productdownload_producttext
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example,.
Enhanced searchenhanced_searchtrue/false
If set to `false`, your search will not use enhanced search. Defaults to `true`.Default: true.
Ethnicityethnicitylist
Filter search results based on the ethnicity of individuals.One or more of: black, white, east_asian (East asian), hispanic_latinx (Hispanic latinx), japanese, middle_eastern (Middle eastern), multiracial_person (Multiracial person), multiethnic_group (Multiethnic group), native_american_first_nations (Native american first nations), pacific_islander (Pacific islander), south_asian (South asian), southeast_asian (Southeast asian).
Exclude editorial use onlyexclude_editorial_use_onlytrue/false
Exclude videos that are only available for editorial (non-commercial) use. Default value is false.
Exclude keyword idsexclude_keyword_idslist
Return only videos not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also do not contain the requested keyword(s) are returned.
Exclude nudityexclude_nuditytrue/false
Excludes videos containing nudity. The default is false.Default: false.
Facet fieldsfacet_fieldslist
Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.One or more of: artists, locations.
Facet max countfacet_max_countnumber
Specifies the maximum number of facets to return per type. Default is 300.Default: 300.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.One or more of: allowed_use (Allowed use), artist, aspect_ratio (Aspect ratio), asset_family (Asset family), call_for_image (Call for image), caption, clip_length (Clip length), collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), and 27 more.
Format availableformat_availabletext
Filters according to the digital video format available on a film asset.One of: sd, hd, 4k, hd_web (Hd web).
Frame ratesframe_rateslist
Provides filtering by video frame rate (frames/second).One or more of: 23.98, 24, 25, 29.97, 30, 50, 59.94, 60.
Image techniquesimage_techniqueslist
Filter based on image technique.One or more of: realtime, time_lapse (Time lapse), slow_motion (Slow motion), color, black_and_white (Black and white), animation, selective_focus (Selective focus).
Include facetsinclude_facetstrue/false
Specifies whether or not to include facets in the result set. Default is "false".
Include related searchesinclude_related_searchestrue/false
Specifies whether or not to include related searches in the response. The default is false.Default: false.
Istock exclusiveistock_exclusivetrue/false
Restricts results to iStock exclusive assets when true, or non-exclusive assets when false. The default is null (no filter).
Keyword idskeyword_idslist
Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned.
License modelslicense_modelslist
Specifies the video licensing model(s).One or more of: rightsready, royaltyfree.
Min clip lengthmin_clip_lengthnumber
Provides filtering by minimum length of video clip, in secondsDefault: 0.
Max clip lengthmax_clip_lengthnumber
Provides filtering by maximum length of video, in secondsDefault: 0.
Number of peoplenumber_of_peoplelist
Filter based on the number of people.One or more of: none, one, two, group.
Orientationsorientationslist
Return only videos with selected orientations.One or more of: horizontal, vertical.
Pagepagenumber
Identifies page to return. Default is 1.Default: 1.
Page sizepage_sizenumber
Specifies page size. Default is 30, maximum page_size is 100.Default: 30.
Phrasephrasetext
Free-text search query.
Safe searchsafe_searchtrue/false
Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter..Default: false.
Sort ordersort_ordertext
Select sort order of results. The default is best_matchOne of: best_match (Best match), most_popular (Most popular), newest, random.
Release statusrelease_statustext
Allows filtering by type of model release.One of: release_not_important (Release not important), fully_released (Fully released).
Viewpointsviewpointslist
Filter based on viewpoint.One or more of: lockdown, panning, tracking_shot (Tracking shot), aerial_view (Aerial view), high_angle_view (High angle view), low_angle_view (Low angle view), tilt, point_of_view (Point of view).

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "related_searches": [],
    "result_count": 1,
    "videos": []
  }
}

Search editorial images

Search for editorial images only

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Gi-country-codegi_country_codetext
Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
Age of peopleage_of_peoplelist
Filter based on the age of individuals in an image.One or more of: newborn, baby, child, teenager, young_adult (Young adult), adult, adults_only (Adults only), mature_adult (Mature adult), senior_adult (Senior adult), 0-1_months (0-1 months), and 32 more.
Artistsartiststext
Search for images by specific artists (free-text, comma-separated list of artists).
Collection codescollection_codeslist
Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
Collections filter typecollections_filter_typetext
Use to include or exclude collections from search. The default is includeOne of: include, exclude.
Compositionscompositionslist
Filter based on image composition.One or more of: abstract, candid, close_up (Close up), copy_space (Copy space), cut_out (Cut out), full_frame (Full frame), full_length (Full length), headshot, looking_at_camera (Looking at camera), macro, and 8 more.
Date fromdate_fromdate and time
Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
Date todate_todate and time
Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
Download productdownload_producttext
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example,.
Editorial segmentseditorial_segmentslist
Return only events with a matching editorial segment.One or more of: archival, entertainment, news, publicity, royalty, sport.
Embed content onlyembed_content_onlytrue/false
Restrict search results to embeddable images. The default is false.Default: false.
Enhanced searchenhanced_searchtrue/false
If set to `true`, your search will use enhanced search. Defaults to `false`.Default: false.
Ethnicityethnicitylist
Filter search results based on the ethnicity of individuals in an image.One or more of: black, white, east_asian (East asian), hispanic_latinx (Hispanic latinx), japanese, middle_eastern (Middle eastern), multiracial_person (Multiracial person), multiethnic_group (Multiethnic group), native_american_first_nations (Native american first nations), pacific_islander (Pacific islander), south_asian (South asian), southeast_asian (Southeast asian).
Event idsevent_idslist
Filter based on specific events
Exclude keyword idsexclude_keyword_idslist
Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned.
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes, height, and width returned by 'download_sizes' field are estimates.One or more of: allowed_use (Allowed use), alternative_ids (Alternative ids), artist, asset_family (Asset family), call_for_image (Call for image), caption, collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), color_type (Color type), and 28 more.
File typesfile_typeslist
Return only images having a specific file type.One or more of: eps.
Graphical stylesgraphical_styleslist
Filter based on graphical style of the image.One or more of: photography, illustration, vector.
Graphical styles filter typegraphical_styles_filter_typetext
Provides searching based on specified graphical style(s). The default is include.One of: include, exclude.
Include related searchesinclude_related_searchestrue/false
Specifies whether or not to include related searches in the response. The default is false.Default: false.
Keyword idskeyword_idslist
Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
Minimum sizeminimum_sizetext
Filter based on minimum size requested. The default is x-small.One of: x_small (X small), small, medium, large, x_large (X large), xx_large (Xx large), vector.
Number of peoplenumber_of_peoplelist
Filter based on the number of people in the image.One or more of: none, one, two, group.
Orientationsorientationslist
Return only images with selected aspect ratios.One or more of: horizontal, vertical, square, panoramic_horizontal (Panoramic horizontal), panoramic_vertical (Panoramic vertical).
Pagepagenumber
Request results starting at a page number (default is 1).Default: 1.
Page sizepage_sizenumber
Request number of images to return in each page. Default is 30, maximum page_size is 100.Default: 30.
Phrasephrasetext
Search images using a search phrase.
Sort ordersort_ordertext
Select sort order of results. The default is best_matchOne of: best_match (Best match), most_popular (Most popular), newest, oldest, random.
Specific peoplespecific_peoplelist
Return only images associated with specific people (using a comma-delimited list).
Minimum quality rankminimum_quality_ranknumber
Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
Facet fieldsfacet_fieldslist
Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.One or more of: artists, events, locations, specific_people (Specific people).
Include facetsinclude_facetstrue/false
Specifies whether or not to include facets in the result set. Default is "false".
Facet max countfacet_max_countnumber
Specifies the maximum number of facets to return per type. Default is 300.Default: 300.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "images": [],
    "related_searches": [],
    "result_count": 1
  }
}

Search editorial videos

Search for editorial videos

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Gi-country-codegi_country_codetext
Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
Age of peopleage_of_peoplelist
Provides filtering according to the age of individuals in a video.One or more of: newborn, baby, child, teenager, young_adult (Young adult), adult, adults_only (Adults only), mature_adult (Mature adult), senior_adult (Senior adult), 0-1_months (0-1 months), and 32 more.
Artistsartiststext
Search for videos by specific artists (free-text, comma-separated list of artists).
Aspect ratiosaspect_ratioslist
Search for videos by specific aspect ratios.One or more of: 16:9, 9:16, 3:4, 4:3, 4:5, 2:1, 17:9, 9:17.
Collection codescollection_codeslist
Provides filtering by collection code.
Collections filter typecollections_filter_typetext
Use to include or exclude collections from search. The default is includeOne of: include, exclude.
Compositionscompositionslist
Filter based on video composition.One or more of: abstract, candid, close_up (Close up), copy_space (Copy space), cut_out (Cut out), full_frame (Full frame), full_length (Full length), headshot, looking_at_camera (Looking at camera), macro, and 8 more.
Date fromdate_fromdate and time
Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
Date todate_todate and time
Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
Download productdownload_producttext
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example,.
Editorial video typeseditorial_video_typeslist
Allows filtering by types of video.One or more of: raw, produced.
Event idsevent_idslist
Filter based on specific events
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes returned by 'download_sizes' field is an estimate.One or more of: allowed_use (Allowed use), artist, aspect_ratio (Aspect ratio), asset_family (Asset family), call_for_image (Call for image), caption, clip_length (Clip length), collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), and 30 more.
Format availableformat_availabletext
Filters according to the digital video format available on a film asset.One of: sd, hd, 4k, hd_web (Hd web).
Frame ratesframe_rateslist
Provides filtering by video frame rate (frames/second).One or more of: 23.98, 24, 25, 29.97, 30, 50, 59.94, 60.
Image techniquesimage_techniqueslist
Filter based on image technique.One or more of: realtime, time_lapse (Time lapse), slow_motion (Slow motion), color, black_and_white (Black and white), animation, selective_focus (Selective focus).
Include related searchesinclude_related_searchestrue/false
Specifies whether or not to include related searches in the response. The default is false.Default: false.
Keyword idskeyword_idslist
Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned.
Min clip lengthmin_clip_lengthnumber
Provides filtering by minimum length of video clip, in secondsDefault: 0.
Max clip lengthmax_clip_lengthnumber
Provides filtering by maximum length of video clip, in secondsDefault: 0.
Orientationsorientationslist
Return only videos with selected orientations.One or more of: horizontal, vertical.
Pagepagenumber
Identifies page to return. Default is 1.Default: 1.
Page sizepage_sizenumber
Specifies page size. Default is 30, maximum page_size is 100.Default: 30.
Phrasephrasetext
Free-text search query.
Sort ordersort_ordertext
Select sort order of results. The default is best_matchOne of: best_match (Best match), most_popular (Most popular), newest, oldest, random.
Specific peoplespecific_peoplelist
Allows filtering by specific peoples' names.
Release statusrelease_statustext
Allows filtering by type of model release.One of: release_not_important (Release not important), fully_released (Fully released).
Facet fieldsfacet_fieldslist
Specifies the facets to return in the response. Facets provide additional search parameters to refine your results. The include_facets parameter must be set to "true" for facets to be returned.One or more of: artists, events, locations, specific_people (Specific people).
Include facetsinclude_facetstrue/false
Specifies whether or not to include facets in the result set. Default is "false".
Facet max countfacet_max_countnumber
Specifies the maximum number of facets to return per type. Default is 300.Default: 300.
Viewpointsviewpointslist
Filter based on viewpoint.One or more of: lockdown, panning, tracking_shot (Tracking shot), aerial_view (Aerial view), high_angle_view (High angle view), low_angle_view (Low angle view), tilt, point_of_view (Point of view).

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "related_searches": [],
    "result_count": 1,
    "videos": []
  }
}

Search events

Search for events

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Gi-country-codegi_country_codetext
Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
Editorial segmenteditorial_segmenttext
Filters to events with a matching editorial segment.One of: archival, entertainment, news, publicity, royalty, sport.
Date fromdate_fromdate and time
Filters to events that start on or after this date. Use ISO 8601 format (e.g., 1999-12-31). Defaults to UTC unless otherwise specified.
Date todate_todate and time
Filters to events that start on or before this date. Use ISO 8601 format (e.g., 1999-12-31). Defaults to UTC unless otherwise specified.
Fieldsfieldslist
Specifies fields to return. Default set is 'id','name','start_date'.One or more of: id, child_event_count (Child event count), editorial_segments (Editorial segments), hero_image (Hero image), image_count (Image count), keywords, location, name, start_date (Start date), type.
Pagepagenumber
Request results starting at a page number (default is 1, maximum is 50).Default: 1.
Page sizepage_sizenumber
Request number of events to return in each page. Default is 30, maximum page_size is 100.Default: 30.
Phrasephrasetext
Filters to events related to this phrase
Sort ordersort_ordertext
Specifies the order in which to sort the results. Default is `newest`.One of: newest, oldest.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "events": [],
    "result_count": 1
  }
}

Search images

Search for both creative and editorial images (deprecated)

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Gi-country-codegi_country_codetext
Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
Age of peopleage_of_peoplelist
Filter based on the age of individuals in an image.One or more of: newborn, baby, child, teenager, young_adult (Young adult), adult, adults_only (Adults only), mature_adult (Mature adult), senior_adult (Senior adult), 0-1_months (0-1 months), and 32 more.
Artistsartiststext
Search for images by specific artists (free-text, comma-separated list of artists).
Collection codescollection_codeslist
Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
Collections filter typecollections_filter_typetext
Provides searching based on specified collection(s). The default is IncludeOne of: include, exclude.
Colorcolortext
Filter based on predominant color in an image. Use 6 character hexidecimal format (e.g., #002244). Note: when specified, results will not contain editorial images.
Compositionscompositionslist
Filter based on image composition.One or more of: abstract, candid, close_up (Close up), copy_space (Copy space), cut_out (Cut out), full_frame (Full frame), full_length (Full length), headshot, looking_at_camera (Looking at camera), macro, and 8 more.
Download productdownload_producttext
Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. For example,.
Embed content onlyembed_content_onlytrue/false
Restrict search results to embeddable images. The default is false.Default: false.
Event idsevent_idslist
Filter based on specific events
Ethnicityethnicitylist
Filter search results based on the ethnicity of individuals in an image.One or more of: black, white, east_asian (East asian), hispanic_latinx (Hispanic latinx), japanese, middle_eastern (Middle eastern), multiracial_person (Multiracial person), multiethnic_group (Multiethnic group), native_american_first_nations (Native american first nations), pacific_islander (Pacific islander), south_asian (South asian), southeast_asian (Southeast asian).
Fieldsfieldslist
Specifies fields to return. Defaults to 'summary_set'.One or more of: accessrestriction, allowed_use (Allowed use), alternative_ids (Alternative ids), artist, asset_family (Asset family), call_for_image (Call for image), caption, collection_code (Collection code), collection_id (Collection id), collection_name (Collection name), and 30 more.
File typesfile_typeslist
Return only images having a specific file type.One or more of: eps.
Graphical stylesgraphical_styleslist
Filter based on graphical style of the image.One or more of: fine_art (Fine art), illustration, photography, vector.
Graphical styles filter typegraphical_styles_filter_typetext
Provides searching based on specified graphical style(s). The default is IncludeOne of: include, exclude.
Include related searchesinclude_related_searchestrue/false
Specifies whether or not to include related searches in the response. The default is false.Default: false.
Keyword idskeyword_idslist
Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
Minimum sizeminimum_sizetext
Filter based on minimum size requested. The default is x-smallOne of: x_small (X small), small, medium, large, x_large (X large), xx_large (Xx large), vector.
Number of peoplenumber_of_peoplelist
Filter based on the number of people in the image.One or more of: none, one, two, group.
Orientationsorientationslist
Return only images with selected aspect ratios.One or more of: horizontal, vertical, square, panoramic_horizontal (Panoramic horizontal), panoramic_vertical (Panoramic vertical).
Pagepagenumber
Request results starting at a page number (default is 1).Default: 1.
Page sizepage_sizenumber
Request number of images to return in each page. Default is 30, maximum page_size is 100.Default: 30.
Phrasephrasetext
Search images using a search phrase.
Sort ordersort_ordertext
Select sort order of results. The default is best_matchOne of: best_match (Best match), most_popular (Most popular), newest, random.
Specific peoplespecific_peoplelist
Return only images associated with specific people (using a comma-delimited list).

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {
    "auto_corrections": {
      "phrase": "example"
    },
    "facets": {
      "artists": [],
      "entertainment": [],
      "events": [],
      "locations": [],
      "specific_people": []
    },
    "images": [],
    "related_searches": [],
    "result_count": 1
  }
}

Update board

Update a board

Inputs

Accept-languageaccept_languagetext
Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th.
Board idboard_idtextRequired
Specifies the board to update.
NamenametextRequired
Name.
Descriptiondescriptiontext
Description.

Outputs

dataobject
Getty Images response data.
Example output
{
  "data": {}
}

On this page