Photography — entry 007 of 25
Getty Images
Getty Images' REST API exposes its creative and editorial stock library for search, metadata lookup, and licensed downloads, covering photos, illustrations, and video. Every call must carry an Api-Key header identifying the registered application, and an OAuth2 bearer token — obtained via the client-credentials or authorization-code grant from Getty's own authentication server — is required even for search, not just for downloads; the API key alone is not enough. There's no public self-serve price list: access is provisioned per customer, with rate limits tied to the negotiated commercial agreement, and JSON is the only response format offered.
AuthenticationOAuthRequires an OAuth flow; expect app registration.
HTTPSSupportedTraffic is encrypted in transit.
CORSEnabledCallable directly from browser JavaScript.
PricingPaidSubscription required — no meaningful free tier.
FormatsJSONResponses can be requested as JSON.
GreatAPIs Score
Score66
Authentication8/25OAuth flow required
Pricing9/20Paid API
Docs20/20Machine-readable spec file bundled
Formats9/15Single response format
Freshness20/20Verified within 6 months
Embed this badge
<a href="https://greatapis.com/api/getty-images/"><img src="https://greatapis.com/badge/getty-images.svg" alt="Scored 66 on greatapis.com"></a>Auth quickstart
- Register an app / run the OAuth flow to obtain a bearer token.
- Send it as an Authorization header
Authorization: Bearer <token>
Stored keyNo key stored
Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.
Endpoints
AffiliateSearch2
GET/v3/affiliates/search/images
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
phrase | query | no | string |
style | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | AffiliateImageSearchResponse |
GET/v3/affiliates/search/videos
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
phrase | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | AffiliateVideoSearchResponse |
Artists2
GET/v3/artists/imagesSearch for images by a photographer
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
artist_name | query | no | string |
fields | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
GET/v3/artists/videosSearch for videos by a photographer
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
artist_name | query | no | string |
fields | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
AssetChanges3
PUT/v3/asset-changes/change-setsGet asset change notifications.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
channel_id | query | no | integer |
batch_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success - Channel contains unconfirmed asset change notifications | AssetChanges |
201 | Created | AssetChanges |
400 | InvalidChannelIdException | — |
403 | Your access token does not authorize access to this resource | — |
404 | The channel you specified does not exist | — |
DELETE/v3/asset-changes/change-sets/{change-set-id}Confirm asset change notifications.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
change-set-id | path | yes | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
400 | InvalidChangeSetId | — |
403 | Your access token does not authorize access to this resource | — |
404 | Transaction was not found | — |
GET/v3/asset-changes/channelsGet a list of asset change notification channels.
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
403 | UnauthorizedToAccessResource | — |
404 | ChannelsNotFound | — |
AssetLicensing1
POST/v3/asset-licensing/{assetId}Endpoint for acquiring extended licenses with iStock credits for an asset.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
assetId | path | yes | string |
Request body
application/json — AcquireAssetLicensesRequest
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | AssetLicensingResponse |
400 | InvalidRequestParameters | — |
401 | AuthorizationTokenRequired | — |
402 | NotEnoughCreditsForPurchase | — |
404 | StandardLicenseNotFound | — |
AssetManagement1
GET/v3/asset-management/assets/send-events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
last_offset | query | no | string |
event_count | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | GetSendEventsResponse |
400 | EventCountOutOfRange | — |
Boards12
GET/v3/boardsGet all boards that the user participates in
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
page | query | no | integer |
board_relationship | query | no | — |
sort_order | query | no | — |
pageSize | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | BoardList |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
POST/v3/boardsCreate a new board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
Request body
application/json — BoardInfo
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | BoardCreated |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
GET/v3/boards/{board_id}Get assets and metadata for a specific board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | BoardDetail |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
404 | BoardNotFound | — |
PUT/v3/boards/{board_id}Update a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
Request body
application/json — BoardInfo
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
204 | Updated | — |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | InsufficientAccess | — |
404 | BoardNotFound | — |
DELETE/v3/boards/{board_id}Delete a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
204 | — | |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | InsufficientAccess | — |
404 | BoardNotFound | — |
PUT/v3/boards/{board_id}/assetsAdd assets to a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | AddBoardAssetsResult |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | InsufficientAccess | — |
404 | BoardNotFound | — |
DELETE/v3/boards/{board_id}/assetsRemove assets from a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
asset_ids | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | InsufficientAccess | — |
404 | BoardNotFound | — |
PUT/v3/boards/{board_id}/assets/{asset_id}Add an asset to a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
asset_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | — |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | AssetNotFound | — |
404 | BoardNotFound | — |
DELETE/v3/boards/{board_id}/assets/{asset_id}Remove an asset from a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
asset_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | InsufficientAccess | — |
404 | BoardNotFound | — |
GET/v3/boards/{board_id}/commentsGet comments from a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | CommentsList |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
404 | BoardNotFound | — |
POST/v3/boards/{board_id}/commentsAdd a comment to a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
Request body
application/json — CommentRequest
Responses
| Status | Description | Schema |
|---|---|---|
201 | Created | CommentCreated |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | InsufficientAccess | — |
404 | BoardNotFound | — |
DELETE/v3/boards/{board_id}/comments/{comment_id}Delete a comment from a board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
board_id | path | yes | string |
comment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
204 | CommentDeleted | — |
400 | InvalidParameterValue | — |
401 | Unauthorized | — |
403 | InsufficientAccess | — |
404 | BoardNotFound | — |
Collections1
GET/v3/collectionsGets collections applicable for the customer.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | CollectionsList |
401 | Unauthorized | — |
Countries1
GET/v3/countriesGets countries codes and names.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | CountriesList |
401 | Unauthorized | — |
Customers1
GET/v3/customers/currentReturns information about the current user.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | CustomerInfoResponse |
400 | InvalidRequestParameters | — |
401 | Unauthorized | — |
503 | ServiceUnavailable | — |
Downloads3
GET/v3/downloadsReturns information about a customer's downloaded assets.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
date_from | query | no | string |
date_to | query | no | string |
use_time | query | no | boolean |
page | query | no | integer |
page_size | query | no | integer |
product_type | query | no | — |
company_downloads | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | GetDownloadsResponse |
400 | Bad request | — |
401 | AuthorizationTokenRequired | — |
403 | Forbidden | — |
POST/v3/downloads/images/{id}Download an image
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
auto_download | query | no | boolean |
file_type | query | no | — |
height | query | no | string |
product_id | query | no | integer |
product_type | query | no | — |
use_team_credits | query | no | boolean |
Request body
application/json — PremiumAccessDownloadData
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
303 | See Other | — |
400 | MissingRequiredQueryParameters | — |
401 | AuthorizationTokenRequired | — |
403 | OverageLimitReached | — |
404 | ImageNotFound | — |
POST/v3/downloads/videos/{id}Download a video
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
auto_download | query | no | boolean |
size | query | no | string |
product_id | query | no | integer |
product_type | query | no | — |
use_team_credits | query | no | boolean |
Request body
application/json — PremiumAccessDownloadData
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
303 | See Other | — |
400 | MissingRequiredQueryParameters | — |
401 | AuthorizationTokenRequired | — |
403 | OverageLimitReached | — |
404 | VideoNotFound | — |
Events2
GET/v3/eventsGet metadata for multiple events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
ids | query | no | array |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidRequestParameters | — |
401 | Unauthorized | — |
404 | EventNotFound | — |
GET/v3/events/{id}Get metadata for a single event
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | integer |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidRequestParameters | — |
401 | Unauthorized | — |
404 | EventNotFound | — |
Images5
GET/v3/imagesGet metadata for multiple images by supplying multiple image ids
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
ids | query | no | array |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | ImagesDetailResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | ImageNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/images/{id}Get metadata for a single image by supplying one image id
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | ImagesDetailResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | ImageNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/images/{id}/downloadhistoryReturns information about a customer's download history for a specific asset
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
company_downloads | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | AssetDownloadHistoryResults |
400 | Bad request | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | ImageNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/images/{id}/same-seriesRetrieve creative images from the same series
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
fields | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | ImageSearchItemSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | ImageNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/images/{id}/similarRetrieve similar images
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
fields | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | ImageSearchItemSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | ImageNotFound | — |
500 | InvalidIStockCollection | — |
Orders1
GET/v3/orders/{id}Get order metadata
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | OrderDetail |
401 | Unauthorized | — |
403 | NoAccessToOrderMetadata | — |
404 | OrderNotFound | — |
Products1
GET/v3/productsGet Products
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | ProductsResult |
400 | InvalidRequestParameters | — |
401 | Unauthorized | — |
500 | CreditPack | — |
Purchases1
GET/v3/purchased-assetsGet Previously Purchased Images and Video
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
date_to | query | no | string |
page | query | no | integer |
page_size | query | no | integer |
date_from | query | no | string |
company_purchases | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | PreviousAssetPurchases |
400 | PageNumberLessThanOne | — |
401 | Unauthorized | — |
403 | InsufficientPermissions | — |
Search9
PUT/v3/search/by-image/uploads/{file-name}Upload image for use by the search creative images/videos operations
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file-name | path | yes | string |
Request body
image/jpeg
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | — |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
GET/v3/search/eventsSearch for events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
editorial_segment | query | no | — |
date_from | query | no | string |
date_to | query | no | string |
fields | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
phrase | query | no | string |
sort_order | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | EventsSearchResult |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
GET/v3/search/imagesSearch for both creative and editorial images - *** DEPRECATED ***
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
age_of_people | query | no | array |
artists | query | no | string |
collection_codes | query | no | array |
collections_filter_type | query | no | — |
color | query | no | string |
compositions | query | no | array |
download_product | query | no | string |
embed_content_only | query | no | boolean |
event_ids | query | no | array |
ethnicity | query | no | array |
exclude_nudity | query | no | boolean |
fields | query | no | array |
file_types | query | no | array |
graphical_styles | query | no | array |
graphical_styles_filter_type | query | no | — |
include_related_searches | query | no | boolean |
keyword_ids | query | no | array |
minimum_size | query | no | — |
number_of_people | query | no | array |
orientations | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
phrase | query | no | string |
sort_order | query | no | — |
specific_people | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | ImageSearchItemSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
GET/v3/search/images/creativeSearch for creative images only
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
age_of_people | query | no | array |
artists | query | no | string |
collection_codes | query | no | array |
collections_filter_type | query | no | — |
color | query | no | string |
compositions | query | no | array |
download_product | query | no | string |
embed_content_only | query | no | boolean |
ethnicity | query | no | array |
exclude_keyword_ids | query | no | array |
exclude_nudity | query | no | boolean |
exclude_editorial_use_only | query | no | boolean |
fields | query | no | array |
file_types | query | no | array |
graphical_styles | query | no | array |
graphical_styles_filter_type | query | no | — |
include_related_searches | query | no | boolean |
keyword_ids | query | no | array |
minimum_size | query | no | — |
number_of_people | query | no | array |
orientations | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
phrase | query | no | string |
safe_search | query | no | boolean |
sort_order | query | no | — |
facet_fields | query | no | array |
include_facets | query | no | boolean |
facet_max_count | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | CreativeImageSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
500 | InvalidIStockCollection | — |
GET/v3/search/images/creative/by-imageSearch for creative images based on url
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
asset_id | query | no | string |
exclude_editorial_use_only | query | no | boolean |
facet_fields | query | no | array |
facet_max_count | query | no | integer |
fields | query | no | array |
image_url | query | no | string |
include_facets | query | no | boolean |
page | query | no | integer |
page_size | query | no | integer |
product_types | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | SearchByImageResourceResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | AssetNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/search/images/editorialSearch for editorial images only
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
age_of_people | query | no | array |
artists | query | no | string |
collection_codes | query | no | array |
collections_filter_type | query | no | — |
compositions | query | no | array |
date_from | query | no | string |
date_to | query | no | string |
download_product | query | no | string |
editorial_segments | query | no | array |
embed_content_only | query | no | boolean |
ethnicity | query | no | array |
event_ids | query | no | array |
exclude_keyword_ids | query | no | array |
fields | query | no | array |
file_types | query | no | array |
graphical_styles | query | no | array |
graphical_styles_filter_type | query | no | — |
include_related_searches | query | no | boolean |
keyword_ids | query | no | array |
minimum_size | query | no | — |
number_of_people | query | no | array |
orientations | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
phrase | query | no | string |
sort_order | query | no | — |
specific_people | query | no | array |
minimum_quality_rank | query | no | integer |
facet_fields | query | no | array |
include_facets | query | no | boolean |
facet_max_count | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | EditorialImageSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
GET/v3/search/videos/creativeSearch for creative videos
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
age_of_people | query | no | array |
artists | query | no | string |
aspect_ratios | query | no | array |
collection_codes | query | no | array |
collections_filter_type | query | no | — |
compositions | query | no | array |
download_product | query | no | string |
exclude_nudity | query | no | boolean |
exclude_editorial_use_only | query | no | boolean |
exclude_keyword_ids | query | no | array |
fields | query | no | array |
format_available | query | no | — |
frame_rates | query | no | array |
image_techniques | query | no | array |
include_related_searches | query | no | boolean |
keyword_ids | query | no | array |
license_models | query | no | array |
orientations | query | no | array |
min_clip_length | query | no | integer |
max_clip_length | query | no | integer |
page | query | no | integer |
page_size | query | no | integer |
phrase | query | no | string |
safe_search | query | no | boolean |
sort_order | query | no | — |
release_status | query | no | — |
facet_fields | query | no | array |
facet_max_count | query | no | integer |
include_facets | query | no | boolean |
viewpoints | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | CreativeVideoSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
500 | InvalidIStockCollection | — |
GET/v3/search/videos/creative/by-imageSearch for creative videos based on url
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
asset_id | query | no | string |
exclude_editorial_use_only | query | no | boolean |
facet_fields | query | no | array |
facet_max_count | query | no | integer |
fields | query | no | array |
image_url | query | no | string |
include_facets | query | no | boolean |
page | query | no | integer |
page_size | query | no | integer |
product_types | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Success | CreativeVideoSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | AssetNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/search/videos/editorialSearch for editorial videos
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
GI-Country-Code | header | no | string |
age_of_people | query | no | array |
artists | query | no | string |
aspect_ratios | query | no | array |
collection_codes | query | no | array |
collections_filter_type | query | no | — |
compositions | query | no | array |
download_product | query | no | string |
editorial_video_types | query | no | array |
fields | query | no | array |
format_available | query | no | — |
frame_rates | query | no | array |
image_techniques | query | no | array |
include_related_searches | query | no | boolean |
keyword_ids | query | no | array |
min_clip_length | query | no | integer |
max_clip_length | query | no | integer |
orientations | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
phrase | query | no | string |
sort_order | query | no | — |
specific_people | query | no | array |
release_status | query | no | — |
facet_fields | query | no | array |
include_facets | query | no | boolean |
facet_max_count | query | no | integer |
viewpoints | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | EditorialVideoSearchResults |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
Usage1
PUT/v3/usage-batches/{id}Report usage of assets via a batch format.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
Request body
application/json — report_usage_batch_request
Responses
| Status | Description | Schema |
|---|---|---|
201 | Success - All usages reported were successfully recorded. | report_usage_batch_response |
400 | InvalidRequest - The content of the request was invalid. Most commonly this is due to either too many assets specified, no assets or invalid JSON. | — |
401 | AuthorizationTokenRequired - Authorization token was missing or not valid. | — |
403 | UnauthorizedToReportUsage | — |
409 | TransactionIdDuplicated | — |
Videos5
GET/v3/videosGet metadata for multiple videos by supplying multiple video ids
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
ids | query | no | array |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | VideosNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/videos/{id}Get metadata for a single video by supplying one video id
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | VideosNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/videos/{id}/downloadhistoryReturns information about a customer's download history for a specific asset
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
company_downloads | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | AssetDownloadHistoryResults |
400 | Bad request | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | VideosNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/videos/{id}/same-seriesRetrieve creative videos from the same series
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
fields | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | VideosNotFound | — |
500 | InvalidIStockCollection | — |
GET/v3/videos/{id}/similarRetrieve similar videos
Parameters
| Name | In | Required | Type |
|---|---|---|---|
Accept-Language | header | no | string |
id | path | yes | string |
fields | query | no | array |
page | query | no | integer |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | OK | — |
400 | InvalidParameterValue | — |
401 | AuthorizationTokenRequired | — |
403 | UnauthorizedDisplaySize | — |
404 | VideosNotFound | — |
500 | InvalidIStockCollection | — |
Try it
Developer reference
Base URL
https://api.gettyimages.comRate limit
Throttled per API Key in queries-per-second (QPS) rather than through a published self-serve tier; limits are set per customer agreement and Getty support can raise them on request — exceeding the limit returns HTTP 429 with "Account Over Queries Per Second Limit."
Key endpoints
- GET/v3/search/images/creative
- GET/v3/search/images/editorial
- GET/v3/search/videos/creative
- GET/v3/search/videos/editorial
- GET/v3/search/events