openapi: 3.0.1
info:
title: Getty Images
version: '3'
description: |-
Developer resources for the Getty Images API including SDK, documentation,
release notes, status, notifications and sample code.
paths:
/v3/affiliates/search/images:
get:
tags:
- Affiliates
- Search
- Images
summary: ''
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: phrase
in: query
description: Search images using a search phrase.
schema:
type: string
description: Search images using a search phrase.
nullable: true
- name: style
in: query
description: Filter based on graphical style of the image.
schema:
$ref: '#/components/schemas/AffiliateSearchStyle'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliateImageSearchResponse'
/v3/affiliates/search/videos:
get:
tags:
- Affiliates
- Search
- Videos
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: phrase
in: query
schema:
type: string
nullable: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliateVideoSearchResponse'
/v3/ai/image-generations:
post:
tags:
- Ai
- Image
- Generations
summary: Generates images from a prompt
description: "# AI Generator - Generate Images\n\nUse a text prompt to generate images. Use of this endpoint is restricted to clients with an AI Generation license\nproduct.\n\n## The Image Generations Request\n\nThe `ImageGenerationsRequest` payload to be posted contains the required `prompt` as well as some other optional\nparameters:\n\n| Parameter | Purpose |\n|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `prompt` _Required_ | The primary text used for the generation of the images. |\n| `product_id` | If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this generation request. If you have multiple products, this property is _required_. Can be retrieved from products (`GET /v3/products`). |\n| `notes` | This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n| `project_code` | If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n| `negative_prompt` | Concepts to _exclude_ from the result |\n| `seed`\t\t | To create new images that have a similar aesthetic, include the seed value from a set of previously generated images. Seed can also be used to reproduce previous results. |\n| `aspect_ratio` | The \"width:height\" aspect ratio of the resultant images. Must be one of: `1:1`, `3:4`, `4:3`, `9:16`, or `16:9` |\n| `media_type` | Media type of the results: `photography` or `illustration` |\n| `mood` | Can be `black_and_white`, `warm`, `cool`, `natural`, `vivid`, `dramatic`, or `bold` |\n| `lens_type` | Can be `wide_angle` or `telephoto` |\n| `depth_of_field` | Can be `shallow` or `deep` |\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a generation request `id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a generation request `id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsRequest'
text/json:
schema:
$ref: '#/components/schemas/ImageGenerationsRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ImageGenerationsRequest'
responses:
'200':
description: Returns the result of a request to generate images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: The request was invalid
'403':
description: Product quota exceeded
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/{generationRequestId}:
get:
tags:
- Ai
- Image
- Generations
- Generation
- Request
summary: Get generated images from a previous generation request
description: >
# AI Generator - Get Generated Images
Gets a previously generated set of images. This endpoint is used after
a call to `POST v3/ai/image-generations`, passing the `id` value from
the result of that call.
## Fulfilled and Pending Results
Like the `POST v3/ai/image-generations` endpoint, the result of calling
this endpoint will be either:
- `HTTP 200 OK` with the generated images' URLs and a generation request
`id` value
- `HTTP 202 Accepted` with the payload only containing a generation
request `id` value
`HTTP 202 Accepted` is returned in the case where the generation of
images has not yet completed. In this case it is expected that the
client will occasionally poll this endpoint until a `HTTP 200 OK` result
with a full payload is returned.
## Lifetime of Generated Images
Generated images will be retained for 6 months after generation.
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
responses:
'200':
description: Returns the result of a request to generate images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: NotAuthorized
'404':
description: The request ID was not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/{generationRequestId}/images/{index}/variations:
post:
tags:
- Ai
- Image
- Generations
- Generation
- Request
- Images
- Index
- Variations
summary: Get variations on a generated image
description: >
# AI Generator - Generate Variations
Generate image variations from a previously-generated image.
## The Image Variation Request
The `ImageVariationRequest` payload to be posted contains the optional
parameters:
| Parameter |
Purpose
|
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `product_id` | If you have multiple AI Generation Getty Images
products, indicate which one you would like to use for this generation
request. If you have multiple products, this property is _required_.
Can be retrieved from products (`GET /v3/products`). |
| `notes` | This is an optional free text parameter often
used by clients who wish to include notes specific to their integration.
This is for use by Getty Images customers only (not iStock). The
products endpoint (`GET /v3/products`) provides this
information.
|
| `project_code` | If your Getty Images Generative AI product
requires project_codes, use of this parameter is required. If your
product does not require a project_code, this parameter must be excluded
from the request. This is for use by Getty Images customers only (not
iStock). The products endpoint (`GET /v3/products`) provides this
information.
|
## Fulfilled and Pending Results
In many cases the result of this call will be the final fulfilled
result. In these cases, you will see a `HTTP 200 OK`
result and a payload including URLs to the result images and a
generation request `id` value.
However some generations may take more time than can be accommodated in
the initial call. In these cases the result of
this call is `HTTP 202 Accepted` and the payload will only contain a
generation request `id` value. This value must be
retained by the client for subsequent polling of the `GET
v3/ai/image-generations/{generationRequestId}` Get Images Generation
endpoint.
## Lifetime of Generated Images
Generated images will be retained for 6 months after generation.
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
- name: index
in: path
description: The index of the image from the specific images generation
required: true
style: simple
schema:
type: integer
format: int32
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ImageVariationRequest'
text/json:
schema:
$ref: '#/components/schemas/ImageVariationRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ImageVariationRequest'
responses:
'200':
description: Returns the result of a request to generate a variation of images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: >-
Returns the request ID for a pending request to generate a variation
of images
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: >-
Either the generation id does not exist, the index is incorrect, or
the generation is still pending
'429':
description: TooManyConcurrentGenerations
/beta/ai/file-registrations:
post:
tags:
- Ai
- Files
- Registrations
summary: Register a client provided file for use with AIGenerator endpoints
description: >
# File Registration
Provide the URL for a previously uploaded file to receive an ID that can
be used as the `reference_file_registration_id` in subsequent image
generation requests.
Use of this endpoint is restricted to clients with a Fine Tune AI
Generation license product.
## The File Registration Request
The `FileRegistrationRequest` payload accepts the following
parameters:
| Parameter |
Purpose
|
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `url` | Required. Specifies the location of the
file.
|
|
| `rights_claimed`| Required. Acknowledgment that client owns or has a
license for this
file.
|
|
| `category` | Optional. Accepted values: `CustomerProduct`,
`ImageReference`. Images to be used in `POST
/beta/ai/image-generations/background-generations` must have the
category set to
`CustomerProduct`.
|
|
## Uploading the file
Before calling this endpoint, a file 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 file has been uploaded, use the full URL as the `url`.
- 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 file registration must be performed using the _same_ API
Key.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FileRegistrationRequest'
text/json:
schema:
$ref: '#/components/schemas/FileRegistrationRequest'
application/*+json:
schema:
$ref: '#/components/schemas/FileRegistrationRequest'
responses:
'200':
description: Returns the response
content:
application/json:
schema:
$ref: '#/components/schemas/FileRegistrationResponse'
'400':
description: The request was invalid
'403':
description: Not authorized
'429':
description: TooManyConcurrentGenerations
/beta/ai/file-registrations/{fileRegistrationId}:
get:
tags:
- Ai
- Files
- Registrations
summary: Get details on a registered file
description: >-
# Get Registered File Details
Gets details for a registered file. This endpoint is used after a call
to `POST beta/ai/file-registrations`, passing the `id` value from the
result of that call.
parameters:
- name: fileRegistrationId
in: path
description: The id from a previous request to register a file
required: true
style: simple
schema:
type: string
responses:
'200':
description: Returns the response
content:
application/json:
schema:
$ref: '#/components/schemas/GetFileRegistrationResponse'
'400':
description: The request was invalid
'403':
description: Not authorized
'404':
description: FileRegistrationIdNotFound
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/refine:
post:
tags:
- Ai
- Image
- Generations
- Refine
summary: Refine a creative image
description: "# AI Generator - Image Refining\n\nUse a mask image and text prompts to modify content in a image from the Getty Images creative library (excluding illustrations and vectors).\nUse of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license. \nTo download a refined image, a traditional license product, such as Premium Access, that provides download access to the original creative image is required.\nLastly, downloading a refined image requires the client to first download the original image.\n \n\n## The Refine Request\n\nThe `RefineRequest` payload one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following\nparameters:\n\n| Parameter | Purpose |\n|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id`| Creative image id to modify. |\n| `reference_generation`| Generation details of image to modify. |\n| `prompt`\t\t | The primary text used for refined portion of the images. |\n| `negative_prompt` | Concepts to _exclude_ from the refined portion. |\n| `product_id` | If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this generation request. If you have multiple products, this property is _required_. Can be retrieved from products (`GET /v3/products`). |\n| `notes` | This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n| `project_code` | If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n| `mask_url` | Required. Specifies the location of the mask. | |\n\n## Uploading mask image\n\nBefore calling the refine endpoint, a mask 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.\n\nFor example, using cURL:\n\n``` sh\ncurl -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\"\n```\n\nOnce the mask has been uploaded, use the full URL as the `mask_url`.\n\n- Uploaded files must be 10MB or smaller.\n- Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately.\n- Uploads expire after 24 hours.\n- Uploads and refining must be performed using the _same_ API Key.\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a `generation_request_id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/RefineRequest'
text/json:
schema:
$ref: '#/components/schemas/RefineRequest'
application/*+json:
schema:
$ref: '#/components/schemas/RefineRequest'
responses:
'200':
description: Returns the result of a request to refine an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to refine an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/extend:
post:
tags:
- Ai
- Image
- Generations
- Extend
summary: Extend a creative image
description: >
# AI Generator - Image Extension
Use text prompts and numerical values to extend the content beyond the
borders of a image from the Getty Images creative library (excluding
illustrations and vectors).
Use of this endpoint is restricted to clients with an AI Generation
license product and may result in the deduction of a credit depending on
the terms of your license.
To download an extended image, a traditional license product, such as
Premium Access, that provides download access to the original creative
image is required.
Lastly, downloading an extended image requires the client to first
download the original image.
Extension involves adding content to one or more sides of an image by
specifying a percentage by which you want the image extended.
This means that the aspect ratio of the generated images will differ
from the original unless the same value is specified for all four sides.
Additionally, the pixel dimensions on the longest side will remain the
same - 612px for the
images provided in this endpoint's response, 1024px and 4096px on the
images retrieved through the download process.
## The Extend Request
The `ExtendRequest` payload requires one, and only one, reference image
(`reference_asset_id`, `reference_generation`) and requires at least one
percentage to be greater than zero (`left_percentage`,
`right_percentage`, `top_percentage`, or `bottom_percentage`) and
accepts the following optional
parameters:
| Parameter |
Purpose
|
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `reference_asset_id`| Creative image id to
modify.
|
| `reference_generation`| Generation details of image to
modify.
|
| `prompt` | The primary text used for the extended portion
of the
images.
|
| `negative_prompt` | Concepts to _exclude_ from the extended
portion.
|
| `product_id` | If you have multiple AI Generation Getty Images
products, indicate which one you would like to use for this generation
request. If you have multiple products, this property is _required_.
Can be retrieved from products (`GET /v3/products`). |
| `notes` | This is an optional free text parameter often
used by clients who wish to include notes specific to their integration.
This is for use by Getty Images customers only (not iStock). The
products endpoint (`GET /v3/products`) provides this
information.
|
| `project_code` | If your Getty Images Generative AI product
requires project_codes, use of this parameter is required. If your
product does not require a project_code, this parameter must be excluded
from the request. This is for use by Getty Images customers only (not
iStock). The products endpoint (`GET /v3/products`) provides this
information.
|
| `left_percentage` | Percentage to add to the left side of the image.
This must be a float that is equal to or greater than 0. Default is
0. |
| `right_percentage` | Percentage to add to the right side of the
image. This must be a float that is equal to or greater than 0. Default
is 0.
|
| `top_percentage` | Percentage to add to the top side of the image.
This must be a float that is equal to or greater than 0. Default is
0.
|
| `bottom_percentage` | Percentage to add to the bottom side of the
image. This must be a float that is equal to or greater than 0. Default
is 0.
|
## Fulfilled and Pending Results
In many cases the result of this call will be the final fulfilled
result. In these cases, you will see a `HTTP 200 OK`
result and a payload including URLs to the result images and a
`generation_request_id` value.
However some generations may take more time than can be accommodated in
the initial call. In these cases the result of
this call is `HTTP 202 Accepted` and the payload will only contain a
`generation_request_id` value. This value must be
retained by the client for subsequent polling of the `GET
v3/ai/image-generations/{generationRequestId}` Get Images Generation
endpoint.
## Lifetime of Generated Images
Generated images will be retained for 6 months after generation.
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ExtendRequest'
text/json:
schema:
$ref: '#/components/schemas/ExtendRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ExtendRequest'
responses:
'200':
description: Returns the result of a request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/background-removal:
post:
tags:
- Ai
- Image
- Generations
- Background
- Removal
summary: Remove a background
description: "# AI Generator - Background Removal\nUse of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license.\nWhen downloading an image generated using a `reference_asset_id`, a traditional license product, such as Premium Access, that provides download access to the original creative image is required. Downloading an image generated using a `reference_asset_id` also requires the client to first download the original image.\n\n## The Background Removal Request\n\nThe `BackgroundRemovalRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`) and accepts the following optional\nparameters:\n\n| Parameter\t\t\t | Purpose |\n|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id`| Creative image id to modify. |\n| `reference_generation`| Generation details of image to modify. | |\n| `product_id` | If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this generation request. If you have multiple products, this property is _required_. Can be retrieved from products (`GET /v3/products`). |\n| `notes` | This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n| `project_code` | If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. | |\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a `generation_request_id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/BackgroundRemovalRequest'
text/json:
schema:
$ref: '#/components/schemas/BackgroundRemovalRequest'
application/*+json:
schema:
$ref: '#/components/schemas/BackgroundRemovalRequest'
responses:
'200':
description: Returns the result of a request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: The request was invalid
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/object-removal:
post:
tags:
- Ai
- Image
- Generations
- Objects
- Removal
summary: Remove object(s)
description: >
# AI Generator - Object Removal
Use a mask image to remove object content in a previously generated
image or a previously licensed image from the Getty Images creative
library. Use of this endpoint is restricted to clients with an AI
Generation license product and may result in the deduction of a credit
depending on the terms of your license.
When downloading an image generated using a `reference_asset_id`, a
traditional license product, such as Premium Access, that provides
download access to the original creative image is required. Downloading
an image generated using a `reference_asset_id` also requires the client
to first download the original image.
## The Remove Object Request
The `RemoveObjectRequest` payload accepts the following parameters.
One, and only one, of either `reference_asset_id` or
`reference_generation` must be used. Omitting or including both are
invalid.
| Parameter |
Purpose
|
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `reference_asset_id` | Creative image id to
modify.
|
| `reference_generation` | Generation details of image to
modify.
|
|
| `mask_url` | **Required**: Specifies the location of the
mask.
|
| `product_id` | If you have multiple AI Generation Getty
Images products, indicate which one you would like to use for this
generation request. If you have multiple products, this property is
**required**. Can be retrieved from products (`GET
/v3/products`).
|
| `notes` | This is an optional free text parameter often
used by clients who wish to include notes specific to their integration.
This is for use by Getty Images customers only (not iStock). The
products endpoint (`GET /v3/products`) provides this
information. |
| `project_code` | This is for use by Getty Images customers
only (not iStock). If your Getty Images Generative AI product requires
project codes, use of this parameter is **required**. Otherwise, this
parameter **must be excluded** from the request. The products endpoint
(`GET /v3/products`) provides this information. |
## Uploading mask image
Before calling the endpoint, a mask 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 mask has been uploaded, use the full URL as the `mask_url`.
- 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 object removal must be performed using the same API Key.
## Fulfilled and Pending Results
In many cases the result of this call will be the final fulfilled
result. In these cases, you will see a `HTTP 200 OK` result and a
payload including URLs to the result images and a generation request
`id` value.
However some generations may take more time than can be accommodated in
the initial call. In these cases the result of this call is `HTTP 202
Accepted` and the payload will only contain a generation request `id`
value. This value must be retained by the client for subsequent polling
of the `GET v3/ai/image-generations/{generationRequestId}` Get Images
Generation endpoint.
## Lifetime of Generated Images
Generated images will be retained for 6 months after generation.
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveObjectRequest'
text/json:
schema:
$ref: '#/components/schemas/RemoveObjectRequest'
application/*+json:
schema:
$ref: '#/components/schemas/RemoveObjectRequest'
responses:
'200':
description: Returns the result of a request to refine images
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to refine images
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: >-
Either the generation id does not exist, the index is incorrect, or
the generation is still pending
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/influence-color-by-image:
post:
tags:
- Ai
- Image
- Generations
- Influence
- Color
summary: Influence the color of generated images using a reference image
description: "# AI Generator - Influence Color By Image\n\nInfluence Color By Image allows the client application to provide an existing Getty Images creative image or an existing generated image, along with prompt text, as a reference for generating new images. The generated images are influenced by the color palette, tone and location of colors within the reference image.\n\nUse of this endpoint is restricted to clients with an AI Generation license product and may result in the deduction of a credit depending on the terms of your license.\nWhen generating new images using using a `reference_asset_id`, the reference image must first be licensed (downloaded) through a traditional license product such as Premium Access.\n\n## The Influence Color By Image Request\n\nThe `InfluenceColorByImageRequest` payload requires one, and only one, reference image (`reference_asset_id`, `reference_generation`, or `reference_file_registration_id`) and accepts the following optional parameters:\n\n| Parameter | Purpose |\n| -------------------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_asset_id` | Creative image ID of the image being used as a reference. |\n| `reference_generation` | Generation details of the image being used as a reference. |\n| `reference_file_registration_id` | Registered file id of the image being used as a reference. The `ImageReference` category **must** be used when registering the file. |\n| `prompt` _Required_ | The primary text used for the generation of the images. |\n| `negative_prompt` | Concepts to _exclude_ from the result. |\n| `noise_level`\t_Required_ | Accepted values are 0-1. Higher values will increase differences between the reference and generated images. |\n| `media_type` | Media type of the results: `photography` or `illustration` |\n| `mood` | Can be `black_and_white`, `warm`, `cool`, `natural`, `vivid`, `dramatic`, or `bold` |\n| `seed` | To create new images that have a similar aesthetic, include the seed value from a set of previously generated images. Seed can also be used to reproduce previous results. |\n| `product_id` | If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this generation request. If you have multiple products, this property is _required_. Can be retrieved from products (`GET /v3/products`). |\n| `notes` | This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n| `project_code` | If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a `generation_request_id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation.\n"
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/InfluenceColorByImageRequest'
text/json:
schema:
$ref: '#/components/schemas/InfluenceColorByImageRequest'
application/*+json:
schema:
$ref: '#/components/schemas/InfluenceColorByImageRequest'
responses:
'200':
description: Returns the result of a request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: The request was invalid
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/v3/ai/image-generations/influence-composition-by-image:
post:
tags:
- Ai
- Image
- Generations
- Influence
- Compositions
summary: Influence the composition of generated images using a reference image
description: >
# AI Generator - Influence Composition By Image
Influence Composition By Image allows the client application to provide
an existing Getty Images creative image or an existing generated image,
along with prompt text, as a reference for generating new images. The
generated images are influenced by the compositional elements like pose,
object location and object depth within the reference image.
Use of this endpoint is restricted to clients with an AI Generation
license product and may result in the deduction of a credit depending on
the terms of your license.
When generating new images using using a `reference_asset_id`, the
reference image must first be licensed (downloaded) through a
traditional license product such as Premium Access.
## The Influence Composition By Image Request
The `InfluenceCompositionByImageRequest` payload requires one, and only
one, reference image (`reference_asset_id`, `reference_generation`, or
`reference_file_registration_id`) and accepts the following optional
parameters:
| Parameter |
Purpose
|
| --------------------------------
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `reference_asset_id` | Creative image ID of the image
being used as a
reference.
|
| `reference_generation` | Generation details of the image
being used as a
reference.
|
| `reference_file_registration_id` | Registered file id of the image
being used as a reference. The `ImageReference` category **must** be
used when registering the
file.
|
| `prompt` _Required_ | The primary text used for the
generation of the
images.
|
| `negative_prompt` | Concepts to _exclude_ from the
result.
|
| `influence_level` _Required_ | Accepted values are 0-1. Higher
values will increase the similarities between the reference and
generated
images.
|
| `media_type` | Media type of the results:
`photography` or
`illustration`
|
| `mood` | Can be `black_and_white`, `warm`,
`cool`, `natural`, `vivid`, `dramatic`, or
`bold`
|
| `seed` | To create new images that have a
similar aesthetic, include the seed value from a set of previously
generated images. Seed can also be used to reproduce previous
results.
|
| `product_id` | If you have multiple AI Generation
Getty Images products, indicate which one you would like to use for this
generation request. If you have multiple products, this property is
_required_. Can be retrieved from products (`GET
/v3/products`).
|
| `notes` | This is an optional free text
parameter often used by clients who wish to include notes specific to
their integration. This is for use by Getty Images customers only (not
iStock). The products endpoint (`GET /v3/products`) provides this
information.
|
| `project_code` | If your Getty Images Generative AI
product requires project_codes, use of this parameter is required. If
your product does not require a project_code, this parameter must be
excluded from the request. This is for use by Getty Images customers
only (not iStock). The products endpoint (`GET /v3/products`) provides
this information. |
## Fulfilled and Pending Results
In many cases the result of this call will be the final fulfilled
result. In these cases, you will see a `HTTP 200 OK`
result and a payload including URLs to the result images and a
`generation_request_id` value.
However some generations may take more time than can be accommodated in
the initial call. In these cases the result of
this call is `HTTP 202 Accepted` and the payload will only contain a
`generation_request_id` value. This value must be
retained by the client for subsequent polling of the `GET
v3/ai/image-generations/{generationRequestId}` Get Images Generation
endpoint.
## Lifetime of Generated Images
Generated images will be retained for 6 months after generation.
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/InfluenceCompositionByImageRequest'
text/json:
schema:
$ref: '#/components/schemas/InfluenceCompositionByImageRequest'
application/*+json:
schema:
$ref: '#/components/schemas/InfluenceCompositionByImageRequest'
responses:
'200':
description: Returns the result of a request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request to extend an image
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Image not found
'410':
description: GenerationRequestGone
'429':
description: TooManyConcurrentGenerations
/beta/ai/image-generations/background-generations:
post:
tags:
- Ai
- Image
- Generations
- Background
summary: Add a background to a reference image
description: "# AI Generator - Background Generation\n\nBackground Generation allows the client application to provide a `reference_file_registration_id` as a reference for creating new AI-generated product photos. Our technology will generate new background content behind the image based on the prompt and other parameters submitted with the request. The padding values are used to position the product on the canvas.\n\nUse of this endpoint may result in the deduction of a credit depending on the terms of your license.\n\n## The Background Generation Request\n\nThe `BackgroundGenerationRequest` payload requires a reference image (`reference_file_registration_id`) and `prompt` and accepts the following parameters:\n\n| Parameter\t\t\t\t\t\t\t | Purpose |\n|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `reference_file_registration_id` _Required_\t| Registered file id of the image being used as a reference. The `CustomerProduct` category **must** be used when registering the file. |\n| `prompt`\t_Required_\t\t\t\t| The primary text used for refined portion of the images. |\n| `negative_prompt`\t\t\t\t\t| Concepts to _exclude_ from the refined portion. |\n| `product_id`\t\t\t\t\t\t| If you have multiple AI Generation Getty Images products, indicate which one you would like to use for this generation request. If you have multiple products, this property is _required_. Can be retrieved from products (`GET /v3/products`). |\n| `notes`\t\t\t\t\t\t\t| This is an optional free text parameter often used by clients who wish to include notes specific to their integration. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. |\n| `project_code`\t\t\t\t\t| If your Getty Images Generative AI product requires project_codes, use of this parameter is required. If your product does not require a project_code, this parameter must be excluded from the request. This is for use by Getty Images customers only (not iStock). The products endpoint (`GET /v3/products`) provides this information. | \n| `left_percentage`\t\t\t\t\t| Percentage of padding to add to the left side of the item in the image. Default is 0. |\n| `right_percentage`\t\t\t\t| Percentage of padding to add to the right side of the item in the image. Default is 0. |\n| `top_percentage`\t\t\t\t\t| Percentage of padding to add to the top side of the item in the image. Default is 0. |\n| `bottom_percentage`\t\t\t\t| Percentage of padding to add to the bottom side of the item in the image. Default is 0. |\n\n## Fulfilled and Pending Results\n\nIn many cases the result of this call will be the final fulfilled result. In these cases, you will see a `HTTP 200 OK`\nresult and a payload including URLs to the result images and a `generation_request_id` value.\n\nHowever some generations may take more time than can be accommodated in the initial call. In these cases the result of\nthis call is `HTTP 202 Accepted` and the payload will only contain a `generation_request_id` value. This value must be\nretained by the client for subsequent polling of the `GET v3/ai/image-generations/{generationRequestId}` Get Images Generation endpoint.\n\n## Lifetime of Generated Images\n\nGenerated images will be retained for 6 months after generation."
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/BackgroundGenerationRequest'
text/json:
schema:
$ref: '#/components/schemas/BackgroundGenerationRequest'
application/*+json:
schema:
$ref: '#/components/schemas/BackgroundGenerationRequest'
responses:
'200':
description: Returns the result of a request
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerationsResponse'
'202':
description: Returns the request ID for a pending request
content:
application/json:
schema:
$ref: '#/components/schemas/PendingImageGenerationResponse'
'400':
description: InvalidProduct
'403':
description: Product quota exceeded
'404':
description: Image not found
'429':
description: TooManyConcurrentGenerations
/v3/ai/generation-history:
get:
tags:
- Ai
- Generation
- History
summary: Retrieve history of AI generations
description: |-
# AI Generator - Generation History
Get the history of AI generation requests.
parameters:
- name: date_start
in: query
description: "If included, limits the results to those generation requests made on or after date_start. Both dates and datetimes are supported. \r\nDates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. \r\nDatetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ."
style: form
schema:
type: string
format: date-time
- name: date_end
in: query
description: "If included, limits the results to those generation requests made on or before date_end. Both dates and datetimes are supported. \r\nDates should be submitted in ISO 8601 format YYYY-MM-DD. The time will default to 00:00:00 UTC. \r\nDatetimes should be submitted in ISO 8601 format YYYY-MM-DDTHH:mm:ssZ."
style: form
schema:
type: string
format: date-time
- name: media_type
in: query
description: >-
If included, limits the results to those generation requests made
for the given media type.
style: form
schema:
$ref: '#/components/schemas/MediaType'
- name: page_size
in: query
description: The page size of results. Default is 30.
style: form
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
- name: page
in: query
description: The page number of results. Default is 1.
style: form
schema:
maximum: 2147483647
minimum: 1
type: integer
format: int32
- name: product_ids
in: query
description: >-
If included, limits the results to only those requests made against
the indicated products.
style: form
schema:
type: array
items:
type: integer
format: int32
- name: company_generations
in: query
description: "If `true`, returns the list of previously downloaded images for all users in\r\n your company. Your account must be enabled for this functionality. Contact your Getty Images account rep for\r\n more information. Default is `false`."
style: form
schema:
type: boolean
default: false
responses:
'200':
description: Returns the history of AI generations
content:
text/plain:
schema:
$ref: '#/components/schemas/GenerationHistoryResponse'
application/json:
schema:
$ref: '#/components/schemas/GenerationHistoryResponse'
text/json:
schema:
$ref: '#/components/schemas/GenerationHistoryResponse'
'403':
description: >-
Company generations were requested but your account is not
configured for access.
/v3/ai/generation-history/{generationRequestId}:
get:
tags:
- Ai
- Generation
- History
- Request
summary: Retrieve history item for an individual generation request
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
responses:
'200':
description: Returns the history item for the request
content:
text/plain:
schema:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
application/json:
schema:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
text/json:
schema:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
'403':
description: NotAuthorized
'404':
description: The request ID was not found
/v3/ai/image-generations/{generationRequestId}/images/{index}/download-sizes:
get:
tags:
- Ai
- Image
- Generations
- Generation
- Request
- Images
- Index
- Downloads
- Ai Generator
summary: Get download sizes for a generated image
description: >
# AI Generator - Get Download Sizes
Given a fulfilled generation request `id` and the `index` of a generated
image, gets a list of download sizes for the image.
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
- name: index
in: path
description: The index of the image from the specific images generation
required: true
style: simple
schema:
type: integer
format: int32
responses:
'200':
description: Returns the result of a request
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadSizesResponse'
'400':
description: InvalidProduct
'404':
description: >-
Either the generation id does not exist, the index is incorrect, or
the generation is still pending
'410':
description: GenerationRequestGone
/v3/ai/image-generations/{generationRequestId}/images/{index}/download:
put:
tags:
- Ai
- Image
- Generations
- Generation
- Request
- Images
- Index
- Downloads
summary: Begin the download process
description: >
# AI Generator - Download Image
Download a generated image. Initiating the download process for a 4K
file may incur a cost depending on the terms of your agreement.
## Download Image Request body details
The `ImageDownloadRequest` payload to be posted contains the required
`size` as well as some other optional
parameters:
| Parameter |
Purpose
|
|-------------------|----------------------------------------------------------------------------------------------|
| `size_name` _Required_ | Must be one of the valid download sizes
retrieved through the "Get Download Sizes" endpoint |
| `notes` | This is an optional free text parameter often
used by clients who wish to include notes specific to their integration.
This is for use by Getty Images customers only (not iStock). The
products endpoint (`GET /v3/products`) provides this
information.
|
| `project_code` | If your Getty Images Generative AI product
requires project_codes, use of this parameter is required. If your
product does not require a project_code, this parameter must be excluded
from the request. This is for use by Getty Images customers only (not
iStock). The products endpoint (`GET /v3/products`) provides this
information.
|
## Fulfilled and Pending Results
In many cases the result of this call will be the final fulfilled
result. In these cases, you will see a `HTTP 200 OK`
result and a payload including a URL for the download.
However some generations may take more time than can be accommodated in
the initial call. In these cases the result of
this call is `HTTP 202 Accepted` with no payload. This client should
then
poll `GET
v3/ai/image-generations/{generationRequestId}/images/{index}/download`
periodically to get the final
download.
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
- name: index
in: path
description: The index of the image from the specific images generation
required: true
style: simple
schema:
type: integer
format: int32
requestBody:
description: Request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ImageDownloadRequest'
text/json:
schema:
$ref: '#/components/schemas/ImageDownloadRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ImageDownloadRequest'
responses:
'200':
description: Download request was successful and is complete
content:
text/plain:
schema:
$ref: '#/components/schemas/DownloadResponse'
application/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
text/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
'202':
description: Download request was successful put is pending
'400':
description: InvalidProduct
'403':
description: ProductQuotaExceeded
'404':
description: GenerationRequestIdNotFound
'409':
description: >-
A download is already in progress for the given
`generationRequestId` and `index`.
'410':
description: GenerationRequestGone
get:
tags:
- Ai
- Image
- Generations
- Generation
- Request
- Images
- Index
- Downloads
summary: "Once the download process has started, this endpoint can be used to check the status of the download and get the\r\ndownload URL once it is completed."
description: >
# AI Generator - Get Download Image
Get the download for a generated image
## Fulfilled and Pending Results
In many cases the result of this call will be the final fulfilled
result. In these cases, you will see a `HTTP 200 OK`
result and a payload including a URL for the download.
However some generations may take more time than can be accommodated in
the initial call. In these cases the result of
this call is `HTTP 202 Accepted` with no payload. This client should
then
poll `GET
v3/ai/image-generations/{generationRequestId}/images/{index}/download`
periodically to get the final
download.
Like the `PUT
v3/ai/image-generations/{generationRequestId}/images/{index}/download`
endpoint, the result of calling
this endpoint will be either:
- `HTTP 200 OK` with the download URL
- `HTTP 202 Accepted` with no payload
`HTTP 202 Accepted` is returned in the case where the download
preparation has not yet completed. In this case it is
expected that the client will occasionally poll this endpoint until a
`HTTP 200 OK` result with a full payload is
returned.
parameters:
- name: generationRequestId
in: path
description: The ID from a previous request to generate images
required: true
style: simple
schema:
type: string
- name: index
in: path
description: The index of the image from the specific images generation
required: true
style: simple
schema:
type: integer
format: int32
responses:
'200':
description: Download request was successful and is complete
content:
text/plain:
schema:
$ref: '#/components/schemas/DownloadResponse'
application/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
text/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
'202':
description: Download request was successful put is pending
'400':
description: InvalidProduct
'404':
description: GenerationRequestIdNotFound
'410':
description: GenerationRequestGone
/v3/ai/redownloads:
post:
tags:
- Ai
- Ai Generator
summary: Re-download a previously downloaded item
description: >-
# Re-download AI Generated media
Re-download previously downloaded AI generated media.
## `ReDownloadRequest` details
| Parameter |
Purpose
|
|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `generated_asset_id` _Required_ | The generated asset identifier to
re-download. Can be retrieved from previously downloaded assets (`GET
/v3/downloads`) |
| `product_id` _Required_ | The product to use to re-download.
Can be retrieved from products (`GET
/v3/products`)
|
| `size_name` _Required_ | The size to re-download. Valid
values are `1k` and
`4k`
|
| `notes` | This is an optional free text parameter often
used by clients who wish to include notes specific to their integration.
This is for use by Getty Images customers only (not iStock). The
products endpoint (`GET /v3/products`) provides this
information.
|
| `project_code` | If your Getty Images Generative AI product
requires project_codes, use of this parameter is required. If your
product does not require a project_code, this parameter must be excluded
from the request. This is for use by Getty Images customers only (not
iStock). The products endpoint (`GET /v3/products`) provides this
information.
|
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReDownloadRequest'
text/json:
schema:
$ref: '#/components/schemas/ReDownloadRequest'
application/*+json:
schema:
$ref: '#/components/schemas/ReDownloadRequest'
responses:
'200':
description: Returns the re-download response
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadResponse'
'400':
description: The request was invalid
'403':
description: Product is not active or quota exceeded
'404':
description: Could not find source generated_asset_id
'410':
description: GenerationRequestGone
/v3/artists/images:
get:
tags:
- Artists
- Images
summary: Search for images by a photographer
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: artist_name
in: query
description: Name of artist for desired images
schema:
type: string
description: Name of artist for desired images
nullable: true
- name: fields
in: query
description: >-
Comma separated list of fields. Allows restricting which fields are
returned. If no fields are selected, the summary_set of fields are
returned.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ArtistsImageSearchFieldValues'
description: >-
Comma separated list of fields. Allows restricting which fields
are returned. If no fields are selected, the summary_set of fields
are returned.
nullable: true
- name: page
in: query
description: Identifies page to return. Default page is 1.
schema:
type: integer
description: Identifies page to return. Default page is 1.
format: int32
default: 1
- name: page_size
in: query
description: >-
Specifies page size. Default page_size is 10, maximum page_size is
100.
schema:
type: integer
description: >-
Specifies page size. Default page_size is 10, maximum page_size is
100.
format: int32
default: 10
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
/v3/artists/videos:
get:
tags:
- Artists
- Videos
summary: Search for videos by a photographer
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: artist_name
in: query
description: Name of artist for desired images
schema:
type: string
description: Name of artist for desired images
nullable: true
- name: fields
in: query
description: >-
Comma separated list of fields. Allows restricting which fields are
returned. If no fields are selected, the summary_set of fields are
returned.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ArtistsVideoSearchFieldValues'
description: >-
Comma separated list of fields. Allows restricting which fields
are returned. If no fields are selected, the summary_set of fields
are returned.
nullable: true
- name: page
in: query
description: Identifies page to return. Default page is 1.
schema:
type: integer
description: Identifies page to return. Default page is 1.
format: int32
default: 1
- name: page_size
in: query
description: >-
Specifies page size. Default page_size is 10, maximum page_size is
100.
schema:
type: integer
description: >-
Specifies page size. Default page_size is 10, maximum page_size is
100.
format: int32
default: 10
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
/v3/asset-changes/change-sets:
put:
tags:
- Assets
- Changes
- Change
- Sets
summary: Get asset change notifications.
description: >
# 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.
parameters:
- name: channel_id
in: query
description: >-
Specifies the id of the channel for the asset data. Valid channel
ids can be found in the results of the Get Partner Channel query.
schema:
type: integer
description: >-
Specifies the id of the channel for the asset data. Valid channel
ids can be found in the results of the Get Partner Channel query.
format: int32
- name: batch_size
in: query
description: >-
Specifies the number of assets to return. The default is 2200;
maximum is 2200.
schema:
type: integer
description: >-
Specifies the number of assets to return. The default is 2200;
maximum is 2200.
format: int32
nullable: true
responses:
'200':
description: Success - Channel contains unconfirmed asset change notifications
content:
application/json:
schema:
$ref: '#/components/schemas/AssetChanges'
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/AssetChanges'
'400':
description: InvalidChannelIdException
'403':
description: Your access token does not authorize access to this resource
'404':
description: The channel you specified does not exist
/v3/asset-changes/change-sets/{change-set-id}:
delete:
tags:
- Assets
- Changes
- Change
- Sets
- Set
summary: Confirm asset change notifications.
description: >
# 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.
parameters:
- name: change-set-id
in: path
description: >-
Specify the change-set-id associated with a transaction resource
whose receipt you want to confirm.
required: true
schema:
type: integer
description: >-
Specify the change-set-id associated with a transaction resource
whose receipt you want to confirm.
format: int64
responses:
'200':
description: Success
'400':
description: InvalidChangeSetId
'403':
description: Your access token does not authorize access to this resource
'404':
description: Transaction was not found
/v3/asset-changes/channels:
get:
tags:
- Assets
- Changes
- Channels
summary: Get a list of asset change notification channels.
description: >+
# 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.
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Channel'
'403':
description: UnauthorizedToAccessResource
'404':
description: ChannelsNotFound
/v3/asset-licensing/{assetId}:
post:
tags:
- Assets
- Licensing
summary: >-
Endpoint for acquiring extended licenses with iStock credits for an
asset.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: assetId
in: path
description: Getty Images assetId - examples 520621493, 112301284
required: true
schema:
type: string
description: Getty Images assetId - examples 520621493, 112301284
nullable: true
requestBody:
description: "Structure that specifies an array of LicenseTypes (multiseat, unlimited, resale, indemnification) to acquire,\r\n and whether or not to use Team Credits. Authenticated User must have access to Team Credits if UseTeamCredits is set to \"true\"."
content:
application/json:
schema:
$ref: '#/components/schemas/AcquireAssetLicensesRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AssetLicensingResponse'
'400':
description: InvalidRequestParameters
'401':
description: AuthorizationTokenRequired
'402':
description: NotEnoughCreditsForPurchase
'404':
description: StandardLicenseNotFound
/v3/asset-management/assets/send-events:
get:
tags:
- Assets
- Management
- Send
- Events
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: last_offset
in: query
description: "Specifies a date/time (with timezone information) for continuing retrieval of events.\r\nEvents occuring _after_ the `last_offset` value provided will be returned."
schema:
type: string
description: "Specifies a date/time (with timezone information) for continuing retrieval of events.\r\nEvents occuring _after_ the `last_offset` value provided will be returned."
format: date-time
nullable: true
- name: event_count
in: query
description: >-
Specifies the number of events to return. Default is 50, maximum
value is 100.
schema:
type: integer
description: >-
Specifies the number of events to return. Default is 50, maximum
value is 100.
format: int32
nullable: true
responses:
'200':
description: Success
content:
text/plain:
schema:
$ref: '#/components/schemas/GetSendEventsResponse'
application/json:
schema:
$ref: '#/components/schemas/GetSendEventsResponse'
text/json:
schema:
$ref: '#/components/schemas/GetSendEventsResponse'
'400':
description: EventCountOutOfRange
/v3/boards:
get:
tags:
- Boards
summary: Get all boards that the user participates in
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: page
in: query
description: Request results starting at a page number (default is 1).
schema:
type: integer
description: Request results starting at a page number (default is 1).
format: int32
default: 1
- name: board_relationship
in: query
description: Search for boards the user owns or has been invited to as an editor.
schema:
$ref: '#/components/schemas/BoardRelationship'
- name: sort_order
in: query
description: >-
Sort the list of boards by last update date or name. Defaults to
date_last_updated_descending.
schema:
$ref: '#/components/schemas/BoardSortOrder'
- name: pageSize
in: query
description: Request number of boards to return in each page. (default is 30).
schema:
type: integer
description: Request number of boards to return in each page. (default is 30).
format: int32
default: 30
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BoardList'
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
post:
tags:
- Boards
summary: Create a new board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
requestBody:
description: >-
Specify a name and description of the board to create (name is
required).
content:
application/json:
schema:
$ref: '#/components/schemas/BoardInfo'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/BoardCreated'
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
/v3/boards/{board_id}:
get:
tags:
- Boards
summary: Get assets and metadata for a specific board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Retrieve details for a specific board.
required: true
schema:
type: string
description: Retrieve details for a specific board.
nullable: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BoardDetail'
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'404':
description: BoardNotFound
delete:
tags:
- Boards
summary: Delete a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to delete.
required: true
schema:
type: string
description: Specify the board to delete.
nullable: true
responses:
'200':
description: Success
'204':
description: ''
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: InsufficientAccess
'404':
description: BoardNotFound
put:
tags:
- Boards
summary: Update a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to update.
required: true
schema:
type: string
description: Specify the board to update.
nullable: true
requestBody:
description: Specify a new name and description for the board (name is required).
content:
application/json:
schema:
$ref: '#/components/schemas/BoardInfo'
responses:
'200':
description: Success
'204':
description: Updated
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: InsufficientAccess
'404':
description: BoardNotFound
/v3/boards/{board_id}/assets:
put:
tags:
- Boards
- Assets
summary: Add assets to a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to add assets to.
required: true
schema:
type: string
description: Specify the board to add assets to.
nullable: true
requestBody:
description: List assets to add to the board.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BoardAsset'
description: List assets to add to the board.
nullable: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/AddBoardAssetsResult'
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: InsufficientAccess
'404':
description: BoardNotFound
delete:
tags:
- Boards
- Assets
summary: Remove assets from a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to remove assets from.
required: true
schema:
type: string
description: Specify the board to remove assets from.
nullable: true
- name: asset_ids
in: query
description: List the assets to be removed from the board.
schema:
type: array
items:
type: string
description: List the assets to be removed from the board.
nullable: true
responses:
'200':
description: Success
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: InsufficientAccess
'404':
description: BoardNotFound
/v3/boards/{board_id}/assets/{asset_id}:
put:
tags:
- Boards
- Assets
summary: Add an asset to a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to add an asset to.
required: true
schema:
type: string
description: Specify the board to add an asset to.
nullable: true
- name: asset_id
in: path
description: >-
Specify the asset to add to the board. If it is already in the
board's asset collection, no action is taken.
required: true
schema:
type: string
description: >-
Specify the asset to add to the board. If it is already in the
board's asset collection, no action is taken.
nullable: true
responses:
'201':
description: Created
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: AssetNotFound
'404':
description: BoardNotFound
delete:
tags:
- Boards
- Assets
summary: Remove an asset from a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to remove an asset from.
required: true
schema:
type: string
description: Specify the board to remove an asset from.
nullable: true
- name: asset_id
in: path
description: Specify the asset to remove from the board.
required: true
schema:
type: string
description: Specify the asset to remove from the board.
nullable: true
responses:
'200':
description: Success
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: InsufficientAccess
'404':
description: BoardNotFound
/v3/boards/{board_id}/comments:
get:
tags:
- Boards
- Comments
summary: Get comments from a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to retrieve comments from.
required: true
schema:
type: string
description: Specify the board to retrieve comments from.
nullable: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CommentsList'
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'404':
description: BoardNotFound
post:
tags:
- Boards
- Comments
summary: Add a comment to a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board to add a comment to.
required: true
schema:
type: string
description: Specify the board to add a comment to.
nullable: true
requestBody:
description: Comment to be added to the board.
content:
application/json:
schema:
$ref: '#/components/schemas/CommentRequest'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CommentCreated'
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: InsufficientAccess
'404':
description: BoardNotFound
/v3/boards/{board_id}/comments/{comment_id}:
delete:
tags:
- Boards
- Comments
summary: Delete a comment from a board
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: board_id
in: path
description: Specify the board containing the comment to delete.
required: true
schema:
type: string
description: Specify the board containing the comment to delete.
nullable: true
- name: comment_id
in: path
description: Specify the comment to delete.
required: true
schema:
type: string
description: Specify the comment to delete.
nullable: true
responses:
'200':
description: Success
'204':
description: CommentDeleted
'400':
description: InvalidParameterValue
'401':
description: Unauthorized
'403':
description: InsufficientAccess
'404':
description: BoardNotFound
/v3/collections:
get:
tags:
- Collections
summary: Gets collections applicable for the customer.
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionsList'
'401':
description: Unauthorized
/v3/countries:
get:
tags:
- Countries
summary: Gets countries codes and names.
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CountriesList'
'401':
description: Unauthorized
/v3/customers/current:
get:
tags:
- Customers
- Current
summary: Returns information about the current user.
description: "Returns the first, middle and last name of the authenticated user.\n\nYou'll need an API key and access token to use this resource.\n\t\nPlease consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens.\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerInfoResponse'
'400':
description: InvalidRequestParameters
'401':
description: Unauthorized
'503':
description: ServiceUnavailable
/v3/downloads:
get:
tags:
- Downloads
summary: Returns information about a customer's downloaded assets.
description: "Returns information about a customer's previously downloaded assets.\n\nYou'll need an API key and access token to use this resource.\n \n\t\nThis endpoint requires being a Getty Images customer to limit your results to only assets that you have a license to use, \nyou need to also include an authorization token in the header of your request. \nPlease consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens.\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: date_from
in: query
description: "If specified, selects assets downloaded on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD). \r\nAny hour, minute, second values in the request are not used, unless useTimePart parameter is included.\r\nDate/times in the response are UTC. Default is 30 days prior to date_to"
schema:
type: string
description: "If specified, selects assets downloaded on or after this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD). \r\nAny hour, minute, second values in the request are not used, unless useTimePart parameter is included.\r\nDate/times in the response are UTC. Default is 30 days prior to date_to"
format: date-time
nullable: true
- name: date_to
in: query
description: "If specified, selects assets downloaded on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD)\r\nAny hour, minute, second values in the request are not used, unless useTimePart parameter is included.\r\nDate/times in the response are UTC. Default is current date or 30 days after specified start date, whichever one is earlier."
schema:
type: string
description: "If specified, selects assets downloaded on or before this date. Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD)\r\nAny hour, minute, second values in the request are not used, unless useTimePart parameter is included.\r\nDate/times in the response are UTC. Default is current date or 30 days after specified start date, whichever one is earlier."
format: date-time
nullable: true
- name: use_time
in: query
description: "If specified, time values provided with date_to or date_from will be used. Time values should be appended to the date value in ISO 8601 format\r\ni.e.: 2019-09-19T19:30:37 or 2019-09-19 19:30:37. Time zone can be specified as optional.\r\nDefault value is false"
schema:
type: boolean
description: "If specified, time values provided with date_to or date_from will be used. Time values should be appended to the date value in ISO 8601 format\r\ni.e.: 2019-09-19T19:30:37 or 2019-09-19 19:30:37. Time zone can be specified as optional.\r\nDefault value is false"
default: false
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
- name: product_type
in: query
description: >-
Specifies product type to be included in the previous download
results. Product types easyaccess, editorialsubscription, imagepack,
and premiumaccess are for GettyImages API keys. Product types
royaltyfreesubscription and creditpack are for iStock API keys. To
get previous iStockPhoto credit downloads, creditpack must be
selected.
schema:
$ref: '#/components/schemas/ProductTypeForDownloads'
- name: company_downloads
in: query
description: >-
If specified, returns the list of previously downloaded images for
all users in your company. Your account must be enabled for this
functionality. Contact your Getty Images account rep for more
information. Default is false.
schema:
type: boolean
description: >-
If specified, returns the list of previously downloaded images for
all users in your company. Your account must be enabled for this
functionality. Contact your Getty Images account rep for more
information. Default is false.
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetDownloadsResponse'
'400':
description: Bad request
'401':
description: AuthorizationTokenRequired
'403':
description: Forbidden
/v3/downloads/images/{id}:
post:
tags:
- Downloads
- Images
summary: Download an image
description: "Use this endpoint to generate download URLs and related data for images you are authorized to download.\n\nMost product offerings have enforced periodic download limits such as monthly, weekly, and daily. When this operation executes, the count of allowed downloads is decremented by one for the product offering. Once the download limit is reached for a given product offering, no further downloads may be requested for that product offering until the next download period.\n\nThe download limit for a given download period is covered in your product agreement established with Getty Images.\n\nYou'll need an API key and a [Resource Owner Grant or Implicit Grant](http://developers.gettyimages.com/en/authorization-faq.html) access token to use this resource.\n\n## Auto Downloads\nThe `auto_download` request query parameter specifies whether to automatically download the image.\n\nIf the `auto_download` request query parameter is set to _true_, the API will return an HTTP status code 303 *See Other*.Your client code will need to process this response and redirect to the URI specified in the *Location* header to enable you to automatically download the file. The redirection workflow follows the [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4.4).\n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=true\n```\n\nServer Response:\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response Location header. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\n```\nHTTP/1.1 303 See Other\nLocation: https://delivery.gettyimages.com/...\n```\n\nIf the `auto_download` request query parameter is set to false, the API will return a HTTP status code 200, along with the URI in the response body which can be used to download the image. \n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/images/[asset_id]?auto_download=false\n```\n\nServer Response:\n\n```\nHTTP/1.1 200 OK\n{\n\t\"uri\": \"https://delivery.gettyimages.com/...\"\n}\n```\n## Downloading Via the Returned URI\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\nThe URI returned by this call should be considered opaque and the format could change at any time.\nIn order to get the filename, length or file type, the response headers must be inspected. An example\nresponse follows:\n\n```\ncontent-length: 33959979\ncontent-type: image/jpeg\ncontent-disposition: attachment; filename=GettyImages-1167612765.jpg\n```\n\nThe `content-disposition` header must be parsed to get a usable filename.\n\n## Download URI expiration\n\nDownload URIs are _**only valid for 24 hours**_, starting from the moment they are returned from this call.\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: "\r\n Id of image to download.\r\n "
required: true
schema:
type: string
description: "\r\n Id of image to download.\r\n "
nullable: true
- name: auto_download
in: query
description: "\r\n Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the image.\r\n If false is specified, the download URI will be returned in the response message. Default is true.\r\n "
schema:
type: boolean
description: "\r\n Specifies whether to auto-download the image. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the image.\r\n If false is specified, the download URI will be returned in the response message. Default is true.\r\n "
default: true
- name: file_type
in: query
description: "\r\n File Type expressed with three character file extension.\r\n "
schema:
$ref: '#/components/schemas/DownloadFileType'
- name: height
in: query
description: "\r\n Specifies the pixel height of the particular image to download.\r\n Available heights can be found in the images/{ids} response for the specific image.\r\n If left blank, it will return the largest available size.\r\n "
schema:
type: string
description: "\r\n Specifies the pixel height of the particular image to download.\r\n Available heights can be found in the images/{ids} response for the specific image.\r\n If left blank, it will return the largest available size.\r\n "
nullable: true
- name: product_id
in: query
description: "\r\n Identifier of the instance for the selected product offering type.\r\n "
schema:
type: integer
description: "\r\n Identifier of the instance for the selected product offering type.\r\n "
format: int32
nullable: true
- name: product_type
in: query
description: "\r\n Product types easyaccess, editorialsubscription, imagepack, and premiumaccess are for GettyImages API keys. Product types royaltyfreesubscription and creditpack are for iStock API keys. Default product type for iStock API keys is creditpack.\r\n "
schema:
$ref: '#/components/schemas/ProductTypeForDownloads'
- name: use_team_credits
in: query
description: >-
Specifies whether to download the image with iStock Team Credits.
Only applicable to iStock API keys authenticated with a user that
has Team Credits. Blank is the same as False.
schema:
type: boolean
description: >-
Specifies whether to download the image with iStock Team Credits.
Only applicable to iStock API keys authenticated with a user that
has Team Credits. Blank is the same as False.
default: false
nullable: true
requestBody:
description: "\r\n Additional information required from specific customers when downloading. \r\n Only users who have been set up with a project code by Getty Images Sales need to use this field.\r\n "
content:
application/json:
schema:
$ref: '#/components/schemas/PremiumAccessDownloadData'
responses:
'200':
description: OK
'303':
description: See Other
'400':
description: MissingRequiredQueryParameters
'401':
description: AuthorizationTokenRequired
'403':
description: OverageLimitReached
'404':
description: ImageNotFound
/v3/downloads/videos/{id}:
post:
tags:
- Downloads
- Videos
summary: Download a video
description: "Use this endpoint to generate download URLs and related data for videos you are authorized to download.\n\nMost product offerings have enforced periodic download limits such as monthly, weekly, and daily. When this operation executes, the count of allowed downloads is decremented by one for the product offering. Once the download limit is reached for a given product offering, no further downloads may be requested for that product offering until the next download period.\n\nThe download limit for a given download period is covered in your product agreement established with Getty Images.\n\nYou'll need an API key and a [Resource Owner Grant or Implicit Grant](http://developers.gettyimages.com/en/authorization-faq.html) access token to use this resource.\n\n## Auto Downloads\nThe `auto_download` request query parameter specifies whether to automatically download the video.\n\nIf the `auto_download` request query parameter is set to _true_, the API will return an HTTP status code 303 *See Other*.Your client code will need to process this response and redirect to the URI specified in the *Location* header to enable you to automatically download the file. The redirection workflow follows the [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4.4).\n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=true\n```\n\nServer Response:\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response Location header. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\n```\nHTTP/1.1 303 See Other\nLocation: https://delivery.gettyimages.com/...\n```\n\nIf the `auto_download` request query parameter is set to false, the API will return a HTTP status code 200, along with the URI in the response body which can be used to download the video. \n\nClient Request:\n\n```\nhttps://api.gettyimages.com/v3/downloads/videos/[asset_id]?auto_download=false\n```\n\nServer Response:\n\n```\nHTTP/1.1 200 OK\n{\n\t\"uri\": \"https://delivery.gettyimages.com/...\"\n}\n```\n\n## Downloading Via the Returned URI\n\nYour client code should follow redirect (3xx) status codes returned from the URI in the response. More information here: [HTTP 1.1 protocol](https://tools.ietf.org/html/rfc7231#section-6.4).\n\nThe URI returned by this call should be considered opaque and the format could change at any time.\nIn order to get the filename, length or file type, the response headers must be inspected. An example\nresponse follows:\n\n```\ncontent-length: 283925783\ncontent-type: video/quicktime\ncontent-disposition: attachment; filename=GettyImages-690773579.mov\n```\n\nThe `content-disposition` header must be parsed to get a usable filename.\n\n## Download URI expiration\n\nDownload URIs are _**only valid for 24 hours**_, starting from the moment they are returned from this call.\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: "\r\n Id of video to download.\r\n "
required: true
schema:
type: string
description: "\r\n Id of video to download.\r\n "
nullable: true
- name: auto_download
in: query
description: "\r\n Specifies whether to auto-download the video. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the video.\r\n If false is specified, the download URI will be returned in the response message. Default is false.\r\n "
schema:
type: boolean
description: "\r\n Specifies whether to auto-download the video. If true is specified, a 303 SeeOther status is returned with a\r\n Location header set to the location of the video.\r\n If false is specified, the download URI will be returned in the response message. Default is false.\r\n "
default: false
- name: size
in: query
description: Specifies the size to be downloaded.
schema:
type: string
description: Specifies the size to be downloaded.
nullable: true
- name: product_id
in: query
description: "\r\n Identifier of the instance for the selected product offering type.\r\n "
schema:
type: integer
description: "\r\n Identifier of the instance for the selected product offering type.\r\n "
format: int32
nullable: true
- name: product_type
in: query
description: "\r\n Product types easyaccess, editorialsubscription, imagepack, and premiumaccess are for GettyImages API keys. Product types royaltyfreesubscription and creditpack are for iStock API keys. Default product type for iStock API keys is creditpack.\r\n "
schema:
$ref: '#/components/schemas/ProductTypeForDownloads'
- name: use_team_credits
in: query
description: >-
Specifies whether to download the image with iStock Team Credits.
Only applicable to iStock API keys authenticated with a user that
has Team Credits. Blank is the same as False.
schema:
type: boolean
description: >-
Specifies whether to download the image with iStock Team Credits.
Only applicable to iStock API keys authenticated with a user that
has Team Credits. Blank is the same as False.
nullable: true
requestBody:
description: "\r\n Additional information required from specific customers when downloading. \r\n Only users who have been set up with a project code by Getty Images Sales need to use this field.\r\n "
content:
application/json:
schema:
$ref: '#/components/schemas/PremiumAccessDownloadData'
responses:
'200':
description: OK
'303':
description: See Other
'400':
description: MissingRequiredQueryParameters
'401':
description: AuthorizationTokenRequired
'403':
description: OverageLimitReached
'404':
description: VideoNotFound
/v3/events:
get:
tags:
- Events
summary: Get metadata for multiple events
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: ids
in: query
description: A comma separated list of event ids.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: A comma separated list of event ids.
nullable: true
- name: fields
in: query
description: A comma separated list of fields to return in the response.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EventDetailFieldValues'
description: A comma separated list of fields to return in the response.
nullable: true
responses:
'200':
description: OK
'400':
description: InvalidRequestParameters
'401':
description: Unauthorized
'404':
description: EventNotFound
/v3/events/{id}:
get:
tags:
- Events
summary: Get metadata for a single event
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: An event id.
required: true
schema:
type: integer
description: An event id.
format: int32
- name: fields
in: query
description: A comma separated list of fields to return in the response.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EventDetailFieldValues'
description: A comma separated list of fields to return in the response.
nullable: true
responses:
'200':
description: OK
'400':
description: InvalidRequestParameters
'401':
description: Unauthorized
'404':
description: EventNotFound
/v3/images:
get:
tags:
- Images
summary: Get metadata for multiple images by supplying multiple image ids
description: >
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": ,
"name": "comp",
"uri": ""
},
{
"is_watermarked": ,
"name": "preview",
"uri": ""
},
{
"is_watermarked": ,
"name": "thumb",
"uri": ""
}
]
]
}
```
## Request Usage Considerations
- Specifying the "entity_details" response field can have significant
performance implications. The field should be used only when necessary.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: ids
in: query
description: >-
Specifies one or more image ids to return. Use comma delimiter when
requesting multiple ids. Maximum of 100 ids.
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Specifies one or more image ids to return. Use comma delimiter
when requesting multiple ids. Maximum of 100 ids.
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes,
height, and width returned by 'download_sizes' field are estimates.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageDetailFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE:
Bytes, height, and width returned by 'download_sizes' field are
estimates.
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesDetailResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: ImageNotFound
'500':
description: InvalidIStockCollection
/v3/images/{id}:
get:
tags:
- Images
summary: Get metadata for a single image by supplying one image id
description: >-
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": ,
"name": "comp",
"uri": ""
},
{
"is_watermarked": ,
"name": "preview",
"uri": ""
},
{
"is_watermarked": ,
"name": "thumb",
"uri": ""
}
]
]
}
```
## 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"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: >-
An image id. For more than one image please use the /v3/images
endpoint.
required: true
schema:
type: string
description: >-
An image id. For more than one image please use the /v3/images
endpoint.
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes,
height, and width returned by 'download_sizes' field are estimates.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageDetailFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE:
Bytes, height, and width returned by 'download_sizes' field are
estimates.
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesDetailResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: ImageNotFound
'500':
description: InvalidIStockCollection
/v3/images/{id}/downloadhistory:
get:
tags:
- Images
summary: >-
Returns information about a customer's download history for a specific
asset
description: ''
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: An image id.
required: true
schema:
type: string
description: An image id.
nullable: true
- name: company_downloads
in: query
description: "If specified, returns the list of previously downloaded images for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false."
schema:
type: boolean
description: "If specified, returns the list of previously downloaded images for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssetDownloadHistoryResults'
'400':
description: Bad request
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: ImageNotFound
'500':
description: InvalidIStockCollection
/v3/images/{id}/same-series:
get:
tags:
- Images
- Series
summary: Retrieve creative images from the same series
description: >
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": ,
"name": "comp",
"uri": ""
},
{
"is_watermarked": ,
"name": "preview",
"uri": ""
},
{
"is_watermarked": ,
"name": "thumb",
"uri": ""
}
]
]
}
```
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: Identifies an existing image
required: true
schema:
type: string
description: Identifies an existing image
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes,
height, and width returned by 'download_sizes' field are estimates.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImagesFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE:
Bytes, height, and width returned by 'download_sizes' field are
estimates.
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImageSearchItemSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: ImageNotFound
'500':
description: InvalidIStockCollection
/v3/images/{id}/similar:
get:
tags:
- Images
- Similar
summary: Retrieve similar images
description: >
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": ,
"name": "comp",
"uri": ""
},
{
"is_watermarked": ,
"name": "preview",
"uri": ""
},
{
"is_watermarked": ,
"name": "thumb",
"uri": ""
}
]
]
}
```
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: Identifies an existing image
required: true
schema:
type: string
description: Identifies an existing image
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes,
height, and width returned by 'download_sizes' field are estimates.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImagesFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE:
Bytes, height, and width returned by 'download_sizes' field are
estimates.
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImageSearchItemSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: ImageNotFound
'500':
description: InvalidIStockCollection
/v3/orders/{id}:
get:
tags:
- Orders
summary: Get order metadata
description: |-
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: An order id.
required: true
schema:
type: integer
description: An order id.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDetail'
'401':
description: Unauthorized
'403':
description: NoAccessToOrderMetadata
'404':
description: OrderNotFound
/v3/products:
get:
tags:
- Products
summary: Get Products
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: fields
in: query
description: >-
Comma separated list of fields. Allows product download requirements
to be returned.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ProductFieldValues'
description: >-
Comma separated list of fields. Allows product download
requirements to be returned.
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProductsResult'
'400':
description: InvalidRequestParameters
'401':
description: Unauthorized
'500':
description: CreditPack
/v3/purchased-assets:
get:
tags:
- Purchased
- Assets
summary: Get Previously Purchased Images and Video
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: date_to
in: query
description: >-
If specified, retrieves previous purchases on or before this date.
Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
schema:
type: string
description: >-
If specified, retrieves previous purchases on or before this date.
Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
format: date-time
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 75, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 75, maximum page_size is 100.
format: int32
default: 75
- name: date_from
in: query
description: >-
If specified, retrieves previous purchases on or after this date.
Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
schema:
type: string
description: >-
If specified, retrieves previous purchases on or after this date.
Dates should be submitted in ISO 8601 format (i.e., YYYY-MM-DD).
format: date-time
nullable: true
- name: company_purchases
in: query
description: >-
If specified, returns the list of previously purchased assets for
all users in your company. Your account must be enabled for this
functionality. Contact your Getty Images account rep for more
information. Default is false.
schema:
type: boolean
description: >-
If specified, returns the list of previously purchased assets for
all users in your company. Your account must be enabled for this
functionality. Contact your Getty Images account rep for more
information. Default is false.
default: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PreviousAssetPurchases'
'400':
description: PageNumberLessThanOne
'401':
description: Unauthorized
'403':
description: InsufficientPermissions
/v3/search/events:
get:
tags:
- Search
- Events
summary: Search for events
description: >
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 a specific event are assigned
the same event ID. Event IDs are part of the metadata 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 event ID.
This endpoint will provide events based on a search phrase or editorial
segment and an optional from/to date filter. You can show different
information in the response by specifying values on the "fields"
parameter. The results will include events whose associated images or
videos may not be included in your product(s).
This endpoint requires only an API key. An access token is NOT
required.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: editorial_segment
in: query
description: Filters to events with a matching editorial segment.
schema:
$ref: '#/components/schemas/EditorialSegmentContract'
- name: date_from
in: query
description: >-
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.
schema:
type: string
description: >-
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.
format: date-time
nullable: true
- name: date_to
in: query
description: >-
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.
schema:
type: string
description: >-
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.
format: date-time
nullable: true
- name: fields
in: query
description: Specifies fields to return. Default set is 'id','name','start_date'.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EventFieldValues'
description: >-
Specifies fields to return. Default set is
'id','name','start_date'.
nullable: true
- name: page
in: query
description: >-
Request results starting at a page number (default is 1, maximum is
50).
schema:
type: integer
description: >-
Request results starting at a page number (default is 1, maximum
is 50).
format: int32
default: 1
- name: page_size
in: query
description: >-
Request number of events to return in each page. Default is 30,
maximum page_size is 100.
schema:
type: integer
description: >-
Request number of events to return in each page. Default is 30,
maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Filters to events related to this phrase
schema:
type: string
description: Filters to events related to this phrase
default: ''
nullable: true
- name: sort_order
in: query
description: >-
Specifies the order in which to sort the results. Default is
`newest`.
schema:
$ref: '#/components/schemas/EventSearchSortOrder'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EventsSearchResult'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
/v3/search/images/creative:
get:
tags:
- Search
- Images
- Creative
summary: Search for creative images only
description: >-
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": ,
"name": "comp",
"uri": ""
},
{
"is_watermarked": ,
"name": "preview",
"uri": ""
},
{
"is_watermarked": ,
"name": "thumb",
"uri": ""
}
]
]
}
```
## Enhanced Search
Our enhanced search uses machine-learning models to understand natural,
conversational language. Meaning you can search for longer phrases and
get more relevant results from our creative image and creative video
libraries. Default is `true`. Set `enhanced_search` to `false` if you
require a precise result set and not one expanded through enhanced
search.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Filter based on the age of individuals in an image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Filter based on the age of individuals in an image.
nullable: true
- name: artists
in: query
description: >-
Search for images by specific artists (free-text, comma-separated
list of artists).
schema:
type: string
description: >-
Search for images by specific artists (free-text, comma-separated
list of artists).
nullable: true
- name: collection_codes
in: query
description: >-
Filter by collection codes (comma-separated list). Include or
exclude based on collections_filter_type.
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Filter by collection codes (comma-separated list). Include or
exclude based on collections_filter_type.
nullable: true
- name: collections_filter_type
in: query
description: >-
Use to include or exclude collections from search. The default is
include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: color
in: query
description: >-
Filter based on predominant color in an image. Use 6 character
hexadecimal format (e.g., #002244).
schema:
type: string
description: >-
Filter based on predominant color in an image. Use 6 character
hexadecimal format (e.g., #002244).
nullable: true
- name: compositions
in: query
description: Filter based on image composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on image composition.
nullable: true
- name: download_product
in: query
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
schema:
type: string
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
- name: embed_content_only
in: query
description: Restrict search results to embeddable images. The default is false.
schema:
type: boolean
description: >-
Restrict search results to embeddable images. The default is
false.
default: false
- name: enhanced_search
in: query
description: >-
If set to {false}, your search will not use enhanced search.
Defaults to {true}.
schema:
type: boolean
description: >-
If set to {false}, your search will not use enhanced search.
Defaults to {true}.
default: true
nullable: true
- name: ethnicity
in: query
description: >-
Filter search results based on the ethnicity of individuals in an
image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EthnicityFilterType'
description: >-
Filter search results based on the ethnicity of individuals in an
image.
nullable: true
- name: exclude_editorial_use_only
in: query
description: >-
Exclude images that are only available for editorial
(non-commercial) use. Default value is false.
schema:
type: boolean
description: >-
Exclude images that are only available for editorial
(non-commercial) use. Default value is false.
nullable: true
- name: exclude_keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: exclude_nudity
in: query
description: Excludes images containing nudity. The default is false.
schema:
type: boolean
description: Excludes images containing nudity. The default is false.
default: false
- name: facet_fields
in: query
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreateImageSearchFacetsFields'
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
nullable: true
- name: facet_max_count
in: query
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
schema:
type: integer
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
format: int32
default: 300
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes,
height, and width returned by 'download_sizes' field are estimates.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreativeImagesFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE:
Bytes, height, and width returned by 'download_sizes' field are
estimates.
nullable: true
- name: file_types
in: query
description: Return only images having a specific file type.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/SearchFileType'
description: Return only images having a specific file type.
nullable: true
- name: graphical_styles
in: query
description: Filter based on graphical style of the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/GraphicalStyle'
description: Filter based on graphical style of the image.
nullable: true
- name: graphical_styles_filter_type
in: query
description: >-
Provides searching based on specified graphical style(s). The
default is include.
schema:
$ref: '#/components/schemas/GraphicalStylesFilterType'
- name: include_facets
in: query
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
schema:
type: boolean
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
nullable: true
- name: include_related_searches
in: query
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
schema:
type: boolean
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
default: false
- name: keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: minimum_size
in: query
description: Filter based on minimum size requested. The default is x-small.
schema:
$ref: '#/components/schemas/TeeShirtSize'
- name: moods
in: query
description: Filter based on predominant mood in an image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/MoodFilterType'
description: Filter based on predominant mood in an image.
nullable: true
- name: number_of_people
in: query
description: Filter based on the number of people in the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/NumberOfPeopleFilterType'
description: Filter based on the number of people in the image.
nullable: true
- name: orientations
in: query
description: Return only images with selected aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageOrientationRequest'
description: Return only images with selected aspect ratios.
nullable: true
- name: page
in: query
description: Request results starting at a page number (default is 1).
schema:
type: integer
description: Request results starting at a page number (default is 1).
format: int32
default: 1
- name: page_size
in: query
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
schema:
type: integer
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Search images using a search phrase.
schema:
type: string
description: Search images using a search phrase.
default: ''
nullable: true
- name: safe_search
in: query
description: >-
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. Please direct feedback to
your Getty Images Account or API support representative.
schema:
type: boolean
description: >-
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. Please direct
feedback to your Getty Images Account or API support
representative.
default: false
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/CreativeImageSortOrder'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreativeImageSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'500':
description: InvalidIStockCollection
/v3/search/images/creative/by-image:
get:
tags:
- Search
- Images
- Creative
- Image
summary: Search for creative images based on url
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: asset_id
in: query
description: Specifies the Getty image id to use in the search.
schema:
type: string
description: Specifies the Getty image id to use in the search.
nullable: true
- name: exclude_editorial_use_only
in: query
description: >-
Exclude images that are only available for editorial
(non-commercial) use. Default value is false.
schema:
type: boolean
description: >-
Exclude images that are only available for editorial
(non-commercial) use. Default value is false.
nullable: true
- name: facet_fields
in: query
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreateImageSearchFacetsFields'
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
nullable: true
- name: facet_max_count
in: query
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
schema:
type: integer
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
format: int32
default: 300
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes,
height, and width returned by 'download_sizes' field are estimates.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreativeImagesFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE:
Bytes, height, and width returned by 'download_sizes' field are
estimates.
nullable: true
- name: image_url
in: query
description: Specifies the location of the image to use in the search.
schema:
type: string
description: Specifies the location of the image to use in the search.
nullable: true
- name: include_facets
in: query
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
schema:
type: boolean
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
nullable: true
- name: page
in: query
description: Request results starting at a page number (default is 1).
schema:
type: integer
description: Request results starting at a page number (default is 1).
format: int32
default: 1
- name: page_size
in: query
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
schema:
type: integer
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Free-text search query.
schema:
type: string
description: Free-text search query.
default: ''
nullable: true
- name: product_types
in: query
description: "Filter images to those from one of your product types. \r\n Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. \r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
style: form
explode: false
schema:
type: array
items:
type: string
description: "Filter images to those from one of your product types. \r\n Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. \r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SearchByImageResourceResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: AssetNotFound
'500':
description: InvalidIStockCollection
/v3/search/images/editorial:
get:
tags:
- Search
- Images
- Editorial
summary: Search for editorial images only
description: "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.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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.\nTo include your API token in the search request, add it to the headers as a Bearer token (example in curl):\n\n\t-H \"Authorization: Bearer \"\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **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.\n\n```\n{\n \"images\": \n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"display_sizes\": \n [\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"max_dimensions\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **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.\n\n```\n{\n \"images\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n \"call_for_image\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\": \n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"editorial_segments\",\n \"event_ids\",\n \"graphical_style\",\n \"license_model\",\n \"max_dimensions\",\n \"orientation\",\n \"product_types\",\n \"quality_rank\",\n \"referral_destinations\",\n \"title\"\n ]\n]\n```\n\n#### Display Fields Set\n\nThe **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.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"images\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Filter based on the age of individuals in an image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Filter based on the age of individuals in an image.
nullable: true
- name: artists
in: query
description: >-
Search for images by specific artists (free-text, comma-separated
list of artists).
schema:
type: string
description: >-
Search for images by specific artists (free-text, comma-separated
list of artists).
nullable: true
- name: collection_codes
in: query
description: >-
Filter by collections (comma-separated list of collection codes).
Include or exclude based on collections_filter_type.
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Filter by collections (comma-separated list of collection codes).
Include or exclude based on collections_filter_type.
nullable: true
- name: collections_filter_type
in: query
description: >-
Use to include or exclude collections from search. The default is
include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: compositions
in: query
description: Filter based on image composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on image composition.
nullable: true
- name: date_from
in: query
description: >-
Return only images that are created on or after this date. Use ISO
8601 format (e.g., 1999-12-31).
schema:
type: string
description: >-
Return only images that are created on or after this date. Use ISO
8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: date_to
in: query
description: >-
Return only images that are created on or before this date. Use ISO
8601 format (e.g., 1999-12-31).
schema:
type: string
description: >-
Return only images that are created on or before this date. Use
ISO 8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: download_product
in: query
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
schema:
type: string
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
- name: editorial_segments
in: query
description: Return only events with a matching editorial segment.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialSegmentContract'
description: Return only events with a matching editorial segment.
nullable: true
- name: embed_content_only
in: query
description: Restrict search results to embeddable images. The default is false.
schema:
type: boolean
description: >-
Restrict search results to embeddable images. The default is
false.
default: false
- name: ethnicity
in: query
description: >-
Filter search results based on the ethnicity of individuals in an
image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EthnicityFilterType'
description: >-
Filter search results based on the ethnicity of individuals in an
image.
nullable: true
- name: event_ids
in: query
description: Filter based on specific events
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Filter based on specific events
nullable: true
- name: exclude_keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes,
height, and width returned by 'download_sizes' field are estimates.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialImagesFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE:
Bytes, height, and width returned by 'download_sizes' field are
estimates.
nullable: true
- name: file_types
in: query
description: Return only images having a specific file type.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/SearchFileType'
description: Return only images having a specific file type.
nullable: true
- name: graphical_styles
in: query
description: Filter based on graphical style of the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialGraphicalStyle'
description: Filter based on graphical style of the image.
nullable: true
- name: graphical_styles_filter_type
in: query
description: >-
Provides searching based on specified graphical style(s). The
default is include.
schema:
$ref: '#/components/schemas/GraphicalStylesFilterType'
- name: include_related_searches
in: query
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
schema:
type: boolean
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
default: false
- name: keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: minimum_size
in: query
description: Filter based on minimum size requested. The default is x-small.
schema:
$ref: '#/components/schemas/TeeShirtSize'
- name: number_of_people
in: query
description: Filter based on the number of people in the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/NumberOfPeopleFilterType'
description: Filter based on the number of people in the image.
nullable: true
- name: orientations
in: query
description: Return only images with selected aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageOrientationRequest'
description: Return only images with selected aspect ratios.
nullable: true
- name: page
in: query
description: Request results starting at a page number (default is 1).
schema:
type: integer
description: Request results starting at a page number (default is 1).
format: int32
default: 1
- name: page_size
in: query
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
schema:
type: integer
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Search images using a search phrase.
schema:
type: string
description: Search images using a search phrase.
nullable: true
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/SortOrder'
- name: specific_people
in: query
description: >-
Return only images associated with specific people (using a
comma-delimited list).
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Return only images associated with specific people (using a
comma-delimited list).
nullable: true
- name: minimum_quality_rank
in: query
description: >-
Filter search results based on minimum quality ranking. Possible
values 1, 2, 3 with 1 being best.
schema:
type: integer
description: >-
Filter search results based on minimum quality ranking. Possible
values 1, 2, 3 with 1 being best.
format: int32
nullable: true
- name: facet_fields
in: query
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialImageSearchFacetsFields'
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
nullable: true
- name: include_facets
in: query
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
schema:
type: boolean
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
nullable: true
- name: facet_max_count
in: query
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
schema:
type: integer
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
format: int32
default: 300
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialImageSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
/v3/search/videos/creative:
get:
tags:
- Search
- Videos
- Creative
summary: Search for creative videos
description: "Use this endpoint to search premium stock video, from archival film to contemporary 4K and HD footage.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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\nbeing logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only \nassets that you have a license to use, you need to also include an authorization token in the header of your request.\nPlease consult our [Authorization FAQ](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens.\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to build search\nresponse results. The following fields are provided for every video in your result set when you include **summary_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"asset_family\", \n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **detail_set** query string parameter fields value represents a large batch of metadata fields that are often used to build a \ndetailed view of videos. The following fields are provided for every video in your result set when you include **detail_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\", \n\t\t\"call_for_image\",\n \"caption\", \n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\", \n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"era\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution files \nthat are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result \nset when you include **display_set** in your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```\n\n## Enhanced Search\n\nOur enhanced search uses machine-learning models to understand natural, conversational language. Meaning you can search for longer phrases and get more relevant results from our creative image and creative video libraries. Default is `true`. Set `enhanced_search` to `false` if you require a precise result set and not one expanded through enhanced search."
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Provides filtering according to the age of individuals in a video.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Provides filtering according to the age of individuals in a video.
nullable: true
- name: artists
in: query
description: >-
Search for videos by specific artists (free-text, comma-separated
list of artists).
schema:
type: string
description: >-
Search for videos by specific artists (free-text, comma-separated
list of artists).
nullable: true
- name: aspect_ratios
in: query
description: Search for videos by specific aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoAspectRatioFilterType'
description: Search for videos by specific aspect ratios.
nullable: true
- name: collection_codes
in: query
description: Provides filtering by collection code.
style: form
explode: false
schema:
type: array
items:
type: string
description: Provides filtering by collection code.
nullable: true
- name: collections_filter_type
in: query
description: >-
Use to include or exclude collections from search. The default is
include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: compositions
in: query
description: Filter based on video composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on video composition.
nullable: true
- name: download_product
in: query
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
schema:
type: string
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
- name: enhanced_search
in: query
description: >-
If set to {false}, your search will not use enhanced search.
Defaults to {true}.
schema:
type: boolean
description: >-
If set to {false}, your search will not use enhanced search.
Defaults to {true}.
default: true
nullable: true
- name: ethnicity
in: query
description: Filter search results based on the ethnicity of individuals.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EthnicityFilterType'
description: Filter search results based on the ethnicity of individuals.
nullable: true
- name: exclude_editorial_use_only
in: query
description: >-
Exclude videos that are only available for editorial
(non-commercial) use. Default value is false.
schema:
type: boolean
description: >-
Exclude videos that are only available for editorial
(non-commercial) use. Default value is false.
nullable: true
- name: exclude_keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: exclude_nudity
in: query
description: Excludes videos containing nudity. The default is false.
schema:
type: boolean
description: Excludes videos containing nudity. The default is false.
default: false
- name: facet_fields
in: query
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreateVideoSearchFacetsFields'
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
nullable: true
- name: facet_max_count
in: query
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
schema:
type: integer
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
format: int32
default: 300
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreativeVideosFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
nullable: true
- name: format_available
in: query
description: >-
Filters according to the digital video format available on a film
asset.
schema:
$ref: '#/components/schemas/VideoFormatsRequest'
- name: frame_rates
in: query
description: Provides filtering by video frame rate (frames/second).
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoFrameRates'
description: Provides filtering by video frame rate (frames/second).
nullable: true
- name: image_techniques
in: query
description: Filter based on image technique.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageTechniquesFilterType'
description: Filter based on image technique.
nullable: true
- name: include_facets
in: query
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
schema:
type: boolean
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
nullable: true
- name: include_related_searches
in: query
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
schema:
type: boolean
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
default: false
- name: keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: license_models
in: query
description: Specifies the video licensing model(s).
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/LicenseModelVideoRequest'
description: Specifies the video licensing model(s).
nullable: true
- name: min_clip_length
in: query
description: Provides filtering by minimum length of video clip, in seconds
schema:
type: integer
description: Provides filtering by minimum length of video clip, in seconds
format: int32
default: 0
- name: max_clip_length
in: query
description: Provides filtering by maximum length of video, in seconds
schema:
type: integer
description: Provides filtering by maximum length of video, in seconds
format: int32
default: 0
- name: number_of_people
in: query
description: Filter based on the number of people.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/NumberOfPeopleFilterType'
description: Filter based on the number of people.
nullable: true
- name: orientations
in: query
description: Return only videos with selected orientations.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoOrientationRequest'
description: Return only videos with selected orientations.
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Free-text search query.
schema:
type: string
description: Free-text search query.
default: ''
nullable: true
- name: safe_search
in: query
description: >-
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. Please direct feedback to
your Getty Images Account or API support representative.
schema:
type: boolean
description: >-
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. Please direct
feedback to your Getty Images Account or API support
representative.
default: false
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/CreativeVideoSortOrder'
- name: release_status
in: query
description: Allows filtering by type of model release.
schema:
$ref: '#/components/schemas/ReleaseStatus'
- name: viewpoints
in: query
description: Filter based on viewpoint.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ViewpointsFilterType'
description: Filter based on viewpoint.
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreativeVideoSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'500':
description: InvalidIStockCollection
/v3/search/videos/creative/by-image:
get:
tags:
- Search
- Videos
- Creative
- Image
summary: Search for creative videos based on url
description: >
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.
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: asset_id
in: query
description: Specifies the Getty video id to use in the search.
schema:
type: string
description: Specifies the Getty video id to use in the search.
nullable: true
- name: exclude_editorial_use_only
in: query
description: >-
Exclude videos that are only available for editorial
(non-commercial) use. Default value is false.
schema:
type: boolean
description: >-
Exclude videos that are only available for editorial
(non-commercial) use. Default value is false.
nullable: true
- name: facet_fields
in: query
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreateVideoSearchFacetsFields'
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
nullable: true
- name: facet_max_count
in: query
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
schema:
type: integer
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
format: int32
default: 300
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CreativeVideosFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
nullable: true
- name: image_url
in: query
description: Specifies the location of the image to use in the search.
schema:
type: string
description: Specifies the location of the image to use in the search.
nullable: true
- name: include_facets
in: query
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
schema:
type: boolean
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
nullable: true
- name: page
in: query
description: Request results starting at a page number (default is 1).
schema:
type: integer
description: Request results starting at a page number (default is 1).
format: int32
default: 1
- name: page_size
in: query
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
schema:
type: integer
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Free-text search query.
schema:
type: string
description: Free-text search query.
default: ''
nullable: true
- name: product_types
in: query
description: "Filter images to those from one of your product types. \r\n Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. \r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
style: form
explode: false
schema:
type: array
items:
type: string
description: "Filter images to those from one of your product types. \r\n Allowed values are easyaccess, imagepack, premiumaccess and royaltyfreesubscription. \r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the product_types value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreativeVideoSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: AssetNotFound
'500':
description: InvalidIStockCollection
/v3/search/videos/editorial:
get:
tags:
- Search
- Videos
- Editorial
summary: Search for editorial videos
description: "Use this endpoint to search current and archival video clips of celebrities, newsmakers, and events.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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.\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **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.\n\n```\n{\n \"videos\": \n [\n \"asset_family\", \n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **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.\n\n```\n{\n \"videos\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\", \n\t\t\"call_for_image\",\n \"caption\", \n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\", \n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"era\",\n \"event_ids\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **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.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Provides filtering according to the age of individuals in a video.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Provides filtering according to the age of individuals in a video.
nullable: true
- name: artists
in: query
description: >-
Search for videos by specific artists (free-text, comma-separated
list of artists).
schema:
type: string
description: >-
Search for videos by specific artists (free-text, comma-separated
list of artists).
nullable: true
- name: aspect_ratios
in: query
description: Search for videos by specific aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoAspectRatioFilterType'
description: Search for videos by specific aspect ratios.
nullable: true
- name: collection_codes
in: query
description: Provides filtering by collection code.
style: form
explode: false
schema:
type: array
items:
type: string
description: Provides filtering by collection code.
nullable: true
- name: collections_filter_type
in: query
description: >-
Use to include or exclude collections from search. The default is
include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: compositions
in: query
description: Filter based on video composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on video composition.
nullable: true
- name: date_from
in: query
description: >-
Return only images that are created on or after this date. Use ISO
8601 format (e.g., 1999-12-31).
schema:
type: string
description: >-
Return only images that are created on or after this date. Use ISO
8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: date_to
in: query
description: >-
Return only images that are created on or before this date. Use ISO
8601 format (e.g., 1999-12-31).
schema:
type: string
description: >-
Return only images that are created on or before this date. Use
ISO 8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: download_product
in: query
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
schema:
type: string
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
- name: editorial_video_types
in: query
description: Allows filtering by types of video.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialVideoType'
description: Allows filtering by types of video.
nullable: true
- name: event_ids
in: query
description: Filter based on specific events
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Filter based on specific events
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialVideosFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
nullable: true
- name: format_available
in: query
description: >-
Filters according to the digital video format available on a film
asset.
schema:
$ref: '#/components/schemas/VideoFormatsRequest'
- name: frame_rates
in: query
description: Provides filtering by video frame rate (frames/second).
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoFrameRates'
description: Provides filtering by video frame rate (frames/second).
nullable: true
- name: image_techniques
in: query
description: Filter based on image technique.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageTechniquesFilterType'
description: Filter based on image technique.
nullable: true
- name: include_related_searches
in: query
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
schema:
type: boolean
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
default: false
- name: keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: min_clip_length
in: query
description: Provides filtering by minimum length of video clip, in seconds
schema:
type: integer
description: Provides filtering by minimum length of video clip, in seconds
format: int32
default: 0
- name: max_clip_length
in: query
description: Provides filtering by maximum length of video clip, in seconds
schema:
type: integer
description: Provides filtering by maximum length of video clip, in seconds
format: int32
default: 0
- name: orientations
in: query
description: Return only videos with selected orientations.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoOrientationRequest'
description: Return only videos with selected orientations.
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Free-text search query.
schema:
type: string
description: Free-text search query.
default: ''
nullable: true
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/SortOrder'
- name: specific_people
in: query
description: Allows filtering by specific peoples' names.
style: form
explode: false
schema:
type: array
items:
type: string
description: Allows filtering by specific peoples' names.
nullable: true
- name: release_status
in: query
description: Allows filtering by type of model release.
schema:
$ref: '#/components/schemas/ReleaseStatus'
- name: facet_fields
in: query
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialVideoSearchFacetsFields'
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
nullable: true
- name: include_facets
in: query
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
schema:
type: boolean
description: >-
Specifies whether or not to include facets in the result set.
Default is "false".
nullable: true
- name: facet_max_count
in: query
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
schema:
type: integer
description: >-
Specifies the maximum number of facets to return per type. Default
is 300.
format: int32
default: 300
- name: viewpoints
in: query
description: Filter based on viewpoint.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ViewpointsFilterType'
description: Filter based on viewpoint.
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialVideoSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
/v3/search/by-image/uploads/{file-name}:
put:
tags:
- Search
- Image
- Uploads
- Files
- Name
summary: Upload image for use by the search creative images/videos operations
parameters:
- name: file-name
in: path
description: ''
required: true
schema:
type: string
description: ''
nullable: true
requestBody:
description: ''
content:
image/jpeg:
schema:
type: string
description: ''
format: byte
nullable: true
image/png:
schema:
type: string
description: ''
format: byte
nullable: true
responses:
'200':
description: Success
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
/v3/search/images:
get:
tags:
- Search
- Images
summary: Search for both creative and editorial images - *** DEPRECATED ***
description: "## _This endpoint draws from such a large diversity of content, the results will not be as relevant as when the more specific Creative or Editorial endpoints are used. Additionally, the response time for this endpoint is slower compared to that for Creative and Editorial-specific endpoints. For these reasons,_ _**it is highly recommended that those endpoints are used instead of this blended endpoint.**_\n\n\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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. \nTo include your API token in the search request, add it to the headers as a Bearer token (example in curl):\n\n\t-H \"Authorization: Bearer \"\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **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.\n\n```\n{\n \"images\": \n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"display_sizes\": \n [\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"max_dimensions\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **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. \nThe following fields are provided for every image in your result set when you include **detail_set** in your request.\n\n```\n{\n \"images\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n \"call_for_image\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\": \n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"editorial_segments\",\n \"event_ids\",\n \"graphical_style\",\n \"license_model\",\n \"max_dimensions\",\n \"orientation\",\n \"product_types\",\n \"quality_rank\",\n \"referral_destinations\",\n \"title\"\n ]\n]\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most \nfrequently 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**\nin your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"images\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```\n\n## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: GI-Country-Code
in: header
description: >-
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.
schema:
type: string
description: >-
Use of this parameter requires configuration changes to your API
key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Filter based on the age of individuals in an image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Filter based on the age of individuals in an image.
nullable: true
- name: artists
in: query
description: >-
Search for images by specific artists (free-text, comma-separated
list of artists).
schema:
type: string
description: >-
Search for images by specific artists (free-text, comma-separated
list of artists).
nullable: true
- name: collection_codes
in: query
description: >-
Filter by collection codes (comma-separated list). Include or
exclude based on collections_filter_type.
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Filter by collection codes (comma-separated list). Include or
exclude based on collections_filter_type.
nullable: true
- name: collections_filter_type
in: query
description: >-
Provides searching based on specified collection(s). The default is
Include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: color
in: query
description: >-
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.
schema:
type: string
description: >-
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.
nullable: true
- name: compositions
in: query
description: Filter based on image composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on image composition.
nullable: true
- name: download_product
in: query
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
schema:
type: string
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n 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. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
- name: embed_content_only
in: query
description: Restrict search results to embeddable images. The default is false.
schema:
type: boolean
description: >-
Restrict search results to embeddable images. The default is
false.
default: false
- name: event_ids
in: query
description: Filter based on specific events
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Filter based on specific events
nullable: true
- name: ethnicity
in: query
description: >-
Filter search results based on the ethnicity of individuals in an
image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EthnicityFilterType'
description: >-
Filter search results based on the ethnicity of individuals in an
image.
nullable: true
- name: exclude_nudity
in: query
description: Excludes images containing nudity. The default is false.
schema:
type: boolean
description: Excludes images containing nudity. The default is false.
default: false
- name: fields
in: query
description: Specifies fields to return. Defaults to 'summary_set'.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImagesFieldValues'
description: Specifies fields to return. Defaults to 'summary_set'.
nullable: true
- name: file_types
in: query
description: Return only images having a specific file type.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/SearchFileType'
description: Return only images having a specific file type.
nullable: true
- name: graphical_styles
in: query
description: Filter based on graphical style of the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/GraphicalStyle'
description: Filter based on graphical style of the image.
nullable: true
- name: graphical_styles_filter_type
in: query
description: >-
Provides searching based on specified graphical style(s). The
default is Include
schema:
$ref: '#/components/schemas/GraphicalStylesFilterType'
- name: include_related_searches
in: query
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
schema:
type: boolean
description: >-
Specifies whether or not to include related searches in the
response. The default is false.
default: false
- name: keyword_ids
in: query
description: >-
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.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: >-
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.
nullable: true
- name: minimum_size
in: query
description: Filter based on minimum size requested. The default is x-small
schema:
$ref: '#/components/schemas/TeeShirtSize'
- name: number_of_people
in: query
description: Filter based on the number of people in the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/NumberOfPeopleFilterType'
description: Filter based on the number of people in the image.
nullable: true
- name: orientations
in: query
description: Return only images with selected aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageOrientationRequest'
description: Return only images with selected aspect ratios.
nullable: true
- name: page
in: query
description: Request results starting at a page number (default is 1).
schema:
type: integer
description: Request results starting at a page number (default is 1).
format: int32
default: 1
- name: page_size
in: query
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
schema:
type: integer
description: >-
Request number of images to return in each page. Default is 30,
maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Search images using a search phrase.
schema:
type: string
description: Search images using a search phrase.
nullable: true
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/BlendedImageSortOrder'
- name: specific_people
in: query
description: >-
Return only images associated with specific people (using a
comma-delimited list).
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Return only images associated with specific people (using a
comma-delimited list).
nullable: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImageSearchItemSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
/v3/usage-batches/{id}:
put:
tags:
- Usage
- Batches
summary: Report usage of assets via a batch format.
description: >
# Report Usage
Use this endpoint to report the usages of a set of assets. The count of
assets submitted in a single batch to this endpoint is limited to 1000.
Note that all asset Ids specified must be valid or the operation will
fail causing no usages to be recorded. In this case, you will need to
remove the invalid asset Ids from the query request and re-submit the
query.
## Quickstart
You'll need an API key and an access token to use this resource.
_Note_: Date of use can be in any unambiguous date format.
parameters:
- name: id
in: path
description: Specifies a unique batch transaction id to identify the report.
required: true
schema:
type: string
description: Specifies a unique batch transaction id to identify the report.
nullable: true
requestBody:
description: "Specifies up to 1000 sets of asset Id, usage count, and date of use to submit usages for. \r\n Note that all asset Ids specified must be valid or the operation will fail causing no usages to be recorded. \r\n All dates must be on or before this date and the format should be ISO 8601 (ex: YYYY-MM-DD), time is not needed."
content:
application/json:
schema:
$ref: '#/components/schemas/report_usage_batch_request'
responses:
'201':
description: Success - All usages reported were successfully recorded.
content:
application/json:
schema:
$ref: '#/components/schemas/report_usage_batch_response'
'400':
description: >-
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':
description: >-
AuthorizationTokenRequired - Authorization token was missing or not
valid.
'403':
description: UnauthorizedToReportUsage
'409':
description: TransactionIdDuplicated
/v3/videos:
get:
tags:
- Videos
summary: Get metadata for multiple videos by supplying multiple video ids
description: "Use this endpoint to return detailed video metadata for all the specified video ids.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **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.\n\n```\n{\n \"videos\": \n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **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.\n\n```\n{\n \"videos\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n\t\t\"call_for_image\",\n \"caption\",\n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"download_sizes\",\n \"era\",\n \"event_ids\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **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.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n {\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ],\n \"key_frames\": [\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n }\n ]\n }\n ]\n}\n```\n\n## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: ids
in: query
description: >-
Specifies one or more video ids to return. Use comma delimiter when
requesting multiple ids. Maximum of 100 ids.
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Specifies one or more video ids to return. Use comma delimiter
when requesting multiple ids. Maximum of 100 ids.
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoDetailFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
nullable: true
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: VideosNotFound
'500':
description: InvalidIStockCollection
/v3/videos/{id}:
get:
tags:
- Videos
summary: Get metadata for a single video by supplying one video id
description: "Use this endpoint to return detailed video metadata for the specified video id.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **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.\n\n```\n{\n \"videos\":\n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **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.\n\n```\n{\n \"videos\":\n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n\t\t\"call_for_image\",\n \"caption\",\n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"download_sizes\",\n \"era\",\n \"event_ids\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **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.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"display_sizes\": [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ],\n \"key_frames\": [\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n },\n {\n \"uri\": \"\"\n }\n ]\n}\n```\n\n## Request Usage Considerations\n\n- Specifying the \"entity_details\" response field can have significant performance implications. The field should be used only when necessary.\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: >-
A video id. For more than one video please use the /v3/video
endpoint.
required: true
schema:
type: string
description: >-
A video id. For more than one video please use the /v3/video
endpoint.
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoDetailFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
nullable: true
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: VideosNotFound
'500':
description: InvalidIStockCollection
/v3/videos/{id}/downloadhistory:
get:
tags:
- Videos
summary: >-
Returns information about a customer's download history for a specific
asset
description: ''
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: A video id.
required: true
schema:
type: string
description: A video id.
nullable: true
- name: company_downloads
in: query
description: "If specified, returns the list of previously downloaded videos for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false."
schema:
type: boolean
description: "If specified, returns the list of previously downloaded videos for all users in your company.\r\n Your account must be enabled for this functionality. Contact your Getty Images account rep for more information. Default is false."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssetDownloadHistoryResults'
'400':
description: Bad request
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: VideosNotFound
'500':
description: InvalidIStockCollection
/v3/videos/{id}/same-series:
get:
tags:
- Videos
- Series
summary: Retrieve creative videos from the same series
description: "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.\n\nYou'll need an API key and access token to use this resource.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **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.\n\n```\n{\n \"videos\":\n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **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.\n\n```\n{\n \"videos\":\n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n\t\t\"call_for_image\",\n \"caption\",\n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"download_sizes\",\n \"era\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **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.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```\n"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: Identifies an existing video
required: true
schema:
type: string
description: Identifies an existing video
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AssociatedVideoDetailFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: VideosNotFound
'500':
description: InvalidIStockCollection
/v3/videos/{id}/similar:
get:
tags:
- Videos
- Similar
summary: Retrieve similar videos
description: "This endpoint will provide a list of videos that are similar to the specified asset id.\n\nYou'll need an API key and access token to use this resource.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **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.\n\n```\n{\n \"videos\": \n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **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.\n\n```\n{\n \"videos\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n\t\t\"call_for_image\",\n \"caption\",\n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"download_sizes\",\n \"era\",\n \"event_ids\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **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.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": ,\n \"name\": \"comp\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"preview\",\n \"uri\": \"\"\n },\n {\n \"is_watermarked\": ,\n \"name\": \"thumb\",\n \"uri\": \"\"\n }\n ]\n ]\n}\n```"
parameters:
- name: Accept-Language
in: header
description: >-
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 (iStock only), tr, uk
(iStock only), vi (iStock only), zh-HK (creative assets only).
schema:
type: string
description: >-
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 (iStock
only), tr, uk (iStock only), vi (iStock only), zh-HK (creative
assets only).
- name: id
in: path
description: A video id.
required: true
schema:
type: string
description: A video id.
nullable: true
- name: fields
in: query
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AssociatedVideoDetailFieldValues'
description: >-
Specifies fields to return. Defaults to 'summary_set'. NOTE: Bytes
returned by 'download_sizes' field is an estimate.
nullable: true
- name: page
in: query
description: Identifies page to return. Default is 1.
schema:
type: integer
description: Identifies page to return. Default is 1.
format: int32
default: 1
- name: page_size
in: query
description: Specifies page size. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Specifies page size. Default is 30, maximum page_size is 100.
format: int32
default: 30
responses:
'200':
description: OK
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'404':
description: VideosNotFound
'500':
description: InvalidIStockCollection
components:
schemas:
AffiliateSearchStyle:
enum:
- photography
- vector
type: string
description: Specifies the graphical style of images desired.
AffiliateImageUrls:
type: object
properties:
small:
type: string
nullable: true
small_height:
type: integer
format: int32
small_width:
type: integer
format: int32
medium:
type: string
nullable: true
medium_height:
type: integer
format: int32
medium_width:
type: integer
format: int32
large:
type: string
nullable: true
large_height:
type: integer
format: int32
large_width:
type: integer
format: int32
additionalProperties: false
AffiliateImage:
type: object
properties:
id:
type: string
nullable: true
title:
type: string
nullable: true
caption:
type: string
nullable: true
preview_urls:
$ref: '#/components/schemas/AffiliateImageUrls'
destination_url:
type: string
nullable: true
additionalProperties: false
AutoCorrections:
type: object
properties:
phrase:
type: string
nullable: true
additionalProperties: false
AffiliateImageSearchResponse:
type: object
properties:
images:
type: array
items:
$ref: '#/components/schemas/AffiliateImage'
nullable: true
auto_corrections:
$ref: '#/components/schemas/AutoCorrections'
additionalProperties: false
AffiliateVideoUrls:
type: object
properties:
small_still:
type: string
nullable: true
medium_still:
type: string
nullable: true
large_still:
type: string
nullable: true
small_motion:
type: string
nullable: true
large_motion:
type: string
nullable: true
additionalProperties: false
AffiliateVideo:
type: object
properties:
id:
type: string
nullable: true
title:
type: string
nullable: true
caption:
type: string
nullable: true
preview_urls:
$ref: '#/components/schemas/AffiliateVideoUrls'
destination_url:
type: string
nullable: true
clip_length:
type: string
nullable: true
additionalProperties: false
AffiliateVideoSearchResponse:
type: object
properties:
videos:
type: array
items:
$ref: '#/components/schemas/AffiliateVideo'
nullable: true
auto_corrections:
$ref: '#/components/schemas/AutoCorrections'
additionalProperties: false
ArtistsImageSearchFieldValues:
enum:
- id
- allowed_use
- alternative_ids
- artist
- asset_family
- asset_type
- call_for_image
- caption
- collection_id
- collection_code
- collection_name
- comp
- comp_webp
- copyright
- date_created
- date_submitted
- detail_set
- display_set
- editorial_segments
- event_ids
- graphical_style
- high_res_comp_webp
- keywords
- license_model
- max_dimensions
- mid_res_comp_webp
- orientation
- preview
- product_types
- quality_rank
- referral_destinations
- summary_set
- thumb
- title
type: string
ArtistsVideoSearchFieldValues:
enum:
- id
- allowed_use
- alternative_ids
- artist
- asset_family
- asset_type
- call_for_image
- caption
- clip_length
- collection_id
- collection_code
- collection_name
- comp
- copyright
- date_created
- date_submitted
- detail_set
- display_set
- editorial_segments
- event_ids
- graphical_style
- keywords
- license_model
- max_dimensions
- orientation
- preview
- product_types
- quality_rank
- referral_destinations
- summary_set
- thumb
- title
type: string
ExtendedLicenses:
enum:
- multiseat
- unlimited
- resale
- indemnification
type: string
AcquireAssetLicensesRequest:
required:
- extended_licenses
type: object
properties:
extended_licenses:
type: array
items:
$ref: '#/components/schemas/ExtendedLicenses'
use_team_credits:
type: boolean
description: Defaults to false.
additionalProperties: false
AssetLicensingResponse:
type: object
properties:
credits_used:
type: integer
format: int32
acquired_licenses:
type: array
items:
$ref: '#/components/schemas/ExtendedLicenses'
nullable: true
additionalProperties: false
AssetEvent:
type: object
properties:
timestamp:
type: string
format: date-time
asset_id:
type: string
nullable: true
email_address:
type: string
nullable: true
additionalProperties: false
GetSendEventsResponse:
type: object
properties:
last_offset:
type: string
format: date-time
nullable: true
asset_send_events:
type: array
items:
$ref: '#/components/schemas/AssetEvent'
nullable: true
additionalProperties: false
Collection:
type: object
properties:
asset_family:
type: string
nullable: true
code:
type: string
nullable: true
id:
type: integer
format: int32
license_model:
type: string
nullable: true
name:
type: string
nullable: true
product_types:
type: array
items:
type: string
nullable: true
additionalProperties: false
CollectionsList:
type: object
properties:
collections:
type: array
items:
$ref: '#/components/schemas/Collection'
nullable: true
additionalProperties: false
Country:
type: object
properties:
iso_alpha_2:
type: string
nullable: true
iso_alpha_3:
type: string
nullable: true
name:
type: string
nullable: true
additionalProperties: false
CountriesList:
type: object
properties:
countries:
type: array
items:
$ref: '#/components/schemas/Country'
nullable: true
additionalProperties: false
CuratedSet:
type: object
properties:
set_id:
type: string
nullable: true
title:
type: string
nullable: true
description:
type: string
nullable: true
date_created:
type: string
format: date-time
nullable: true
date_last_updated:
type: string
format: date-time
nullable: true
hero_image_uri:
type: string
nullable: true
assets:
type: array
items:
type: string
nullable: true
keywords:
type: array
items:
type: string
nullable: true
additionalProperties: false
CustomerInfoResponse:
type: object
properties:
first_name:
type: string
nullable: true
middle_name:
type: string
nullable: true
last_name:
type: string
nullable: true
additionalProperties: false
LogLevel:
enum:
- Trace
- Debug
- Information
- Warning
- Error
- Critical
- None
type: string
MemcachedLogEntry:
type: object
properties:
Time:
type: string
format: date-time
LogLevel:
$ref: '#/components/schemas/LogLevel'
Message:
type: string
nullable: true
ExceptionMessage:
type: string
nullable: true
additionalProperties: false
DownloadFileType:
enum:
- eps
- jpg
type: string
ProductTypeForDownloads:
enum:
- easyaccess
- editorialsubscription
- imagepack
- premiumaccess
- royaltyfreesubscription
- creditpack
- aigen
type: string
PremiumAccessDownloadData:
type: object
properties:
download_notes:
type: string
nullable: true
project_code:
type: string
nullable: true
additionalProperties: false
DownloadDetails:
type: object
properties:
download_notes:
type: string
nullable: true
project_code:
type: string
nullable: true
additionalProperties: false
User:
type: object
properties:
username:
type: string
nullable: true
first_name:
type: string
nullable: true
middle_name:
type: string
nullable: true
last_name:
type: string
nullable: true
additionalProperties: false
Dimensions:
type: object
properties:
width:
type: integer
format: int32
nullable: true
height:
type: integer
format: int32
nullable: true
dpi:
type: integer
format: int32
nullable: true
additionalProperties: false
HistoricalDownload:
type: object
properties:
date_downloaded:
type: string
format: date-time
id:
type: string
nullable: true
asset_type:
type: string
nullable: true
product_type:
type: string
nullable: true
thumb_uri:
type: string
nullable: true
agreement_name:
type: string
nullable: true
product_id:
type: integer
format: int32
download_details:
$ref: '#/components/schemas/DownloadDetails'
download_source:
type: string
nullable: true
user:
$ref: '#/components/schemas/User'
size_name:
type: string
nullable: true
dimensions:
$ref: '#/components/schemas/Dimensions'
license_model:
type: string
nullable: true
generated_asset_id:
type: string
nullable: true
additionalProperties: false
GetDownloadsResponse:
type: object
properties:
result_count:
type: integer
format: int32
downloads:
type: array
items:
$ref: '#/components/schemas/HistoricalDownload'
nullable: true
additionalProperties: false
EventDetailFieldValues:
enum:
- id
- child_event_count
- editorial_segments
- hero_image
- image_count
- location
- name
- start_date
- type
type: string
ImageDetailFieldValues:
enum:
- allowed_use
- alternative_ids
- artist
- artist_title
- asset_family
- call_for_image
- caption
- city
- collection_code
- collection_id
- collection_name
- color_type
- comp
- comp_webp
- copyright
- country
- credit_line
- date_camera_shot
- date_created
- date_submitted
- detail_set
- display_set
- download_sizes
- download_product
- downloads
- editorial_segments
- editorial_source
- entity_details
- event_ids
- graphical_style
- id
- is_ai_editable
- istock_collection
- istock_licenses
- keywords
- largest_downloads
- license_model
- links
- max_dimensions
- object_name
- orientation
- people
- preview
- product_types
- quality_rank
- referral_destinations
- state_province
- summary_set
- thumb
- title
- uri_oembed
type: string
ImagesDetailResults:
type: object
properties:
images:
nullable: true
images_not_found:
type: array
items:
type: string
nullable: true
additionalProperties: false
ImagesFieldValues:
enum:
- accessrestriction
- allowed_use
- alternative_ids
- artist
- asset_family
- call_for_image
- caption
- collection_code
- collection_id
- collection_name
- color_type
- comp
- comp_webp
- copyright
- date_camera_shot
- date_created
- date_submitted
- detail_set
- display_set
- download_product
- download_sizes
- editorial_segments
- editorial_source
- entity_details
- event_ids
- graphical_style
- id
- istock_collection
- keywords
- largest_downloads
- license_model
- max_dimensions
- orientation
- people
- preview
- product_types
- quality_rank
- referral_destinations
- summary_set
- thumb
- title
- uri_oembed
type: string
AllowedUse:
type: object
properties:
how_can_i_use_it:
type: string
description: Indicates how the asset can be used
nullable: true
release_info:
type: string
description: Indicates release status
nullable: true
usage_restrictions:
type: array
items:
type: string
description: Indicates asset usage restriction, if any
nullable: true
additionalProperties: false
Contributor:
type: object
properties:
member_name:
type: string
description: The contributor's member name
nullable: true
display_name:
type: string
description: The contributor's display name
nullable: true
additionalProperties: false
description: Contributor information for an image or video
ImageSearchItemDisplaySize:
type: object
properties:
is_watermarked:
type: boolean
name:
type: string
nullable: true
uri:
type: string
nullable: true
additionalProperties: false
Keyword:
type: object
properties:
keyword_id:
type: string
nullable: true
text:
type: string
nullable: true
type:
type: string
nullable: true
relevance:
type: integer
format: int32
nullable: true
entity_uris:
type: array
items:
type: string
nullable: true
entity_types:
type: array
items:
type: string
nullable: true
additionalProperties: false
Download:
type: object
properties:
product_id:
type: string
nullable: true
product_type:
type: string
nullable: true
uri:
type: string
nullable: true
agreement_name:
type: string
nullable: true
additionalProperties: false
MaxDimensions:
type: object
properties:
height:
type: integer
format: int32
width:
type: integer
format: int32
additionalProperties: false
ReferralDestination:
type: object
properties:
site_name:
type: string
nullable: true
uri:
type: string
nullable: true
additionalProperties: false
TerritoryRestriction:
type: object
properties:
country_code:
type: string
nullable: true
type:
type: string
nullable: true
description:
type: string
nullable: true
additionalProperties: false
AssetLicenseName:
enum:
- Standard
- Multiseat
- Unlimited
- Resale
- Indemnification
type: string
IStockLicense:
type: object
properties:
license_type:
$ref: '#/components/schemas/AssetLicenseName'
credits:
type: integer
format: int32
additionalProperties: false
ImageSearchItem:
type: object
properties:
allowed_use:
$ref: '#/components/schemas/AllowedUse'
alternative_ids:
type: object
additionalProperties:
type: string
nullable: true
artist:
type: string
nullable: true
asset_family:
type: string
nullable: true
call_for_image:
type: boolean
caption:
type: string
nullable: true
collection_code:
type: string
nullable: true
collection_id:
type: integer
format: int32
nullable: true
collection_name:
type: string
nullable: true
color_type:
type: string
nullable: true
copyright:
type: string
nullable: true
date_camera_shot:
type: string
format: date-time
nullable: true
date_created:
type: string
format: date-time
nullable: true
display_sizes:
type: array
items:
$ref: '#/components/schemas/ImageSearchItemDisplaySize'
nullable: true
download_product:
type: string
nullable: true
editorial_segments:
type: array
items:
type: string
nullable: true
event_ids:
type: array
items:
type: integer
format: int32
nullable: true
graphical_style:
type: string
nullable: true
id:
type: string
nullable: true
keywords:
type: array
items:
$ref: '#/components/schemas/Keyword'
nullable: true
largest_downloads:
type: array
items:
$ref: '#/components/schemas/Download'
nullable: true
license_model:
type: string
nullable: true
max_dimensions:
$ref: '#/components/schemas/MaxDimensions'
orientation:
type: string
nullable: true
people:
type: array
items:
type: string
nullable: true
product_types:
type: array
items:
type: string
nullable: true
quality_rank:
type: integer
format: int32
referral_destinations:
type: array
items:
$ref: '#/components/schemas/ReferralDestination'
nullable: true
title:
type: string
nullable: true
uri_oembed:
type: string
nullable: true
istock_licenses:
type: array
items:
$ref: '#/components/schemas/IStockLicense'
nullable: true
additionalProperties: false
RelatedSearch:
type: object
properties:
phrase:
type: string
nullable: true
url:
type: string
nullable: true
additionalProperties: false
ImageSearchItemSearchResults:
type: object
properties:
result_count:
type: integer
format: int32
images:
type: array
items:
$ref: '#/components/schemas/ImageSearchItem'
nullable: true
related_searches:
type: array
items:
$ref: '#/components/schemas/RelatedSearch'
nullable: true
additionalProperties: false
AssetDownloadHistoryResults:
type: object
properties:
id:
type: string
nullable: true
downloads:
nullable: true
additionalProperties: false
OrderNotes:
type: object
properties:
licensee_name:
type: string
nullable: true
purchase_order_number:
type: string
nullable: true
project_title:
type: string
nullable: true
ordered_by:
type: string
nullable: true
additionalProperties: false
AssetIdFromOrder:
type: object
properties:
id:
type: string
nullable: true
additionalProperties: false
OrderDetail:
type: object
properties:
id:
type: string
nullable: true
invoice_number:
type: string
nullable: true
order_date:
type: string
format: date-time
end_client:
type: string
nullable: true
notes:
$ref: '#/components/schemas/OrderNotes'
assets:
type: array
items:
$ref: '#/components/schemas/AssetIdFromOrder'
nullable: true
additionalProperties: false
ProductStatusRequest:
enum:
- all
- active
- inactive
type: string
ProductFieldValues:
enum:
- download_requirements
type: string
ProductStatus:
enum:
- active
- inactive
type: string
ProductTypeResponse:
enum:
- easyaccess
- editorialsubscription
- imagepack
- premiumaccess
- royaltyfreesubscription
- creditpack
- aigen
type: string
DownloadRequirements:
type: object
properties:
is_note_required:
type: boolean
is_project_code_required:
type: boolean
project_codes:
type: array
items:
type: string
nullable: true
additionalProperties: false
OverageDetails:
type: object
properties:
limit:
type: integer
format: int32
nullable: true
remaining:
type: integer
format: int32
nullable: true
count:
type: integer
format: int32
nullable: true
overages_reached:
type: boolean
nullable: true
additionalProperties: false
Product:
type: object
properties:
application_website:
type: string
nullable: true
credits_remaining:
type: integer
format: int32
nullable: true
download_limit:
type: integer
format: int32
nullable: true
download_limit_duration:
type: string
nullable: true
download_limit_reset_utc_date:
type: string
format: date-time
nullable: true
downloads_remaining:
type: integer
format: int32
nullable: true
expiration_utc_date:
type: string
format: date-time
nullable: true
id:
type: integer
format: int32
name:
type: string
nullable: true
status:
$ref: '#/components/schemas/ProductStatus'
type:
$ref: '#/components/schemas/ProductTypeResponse'
ai_gen_requirements:
$ref: '#/components/schemas/DownloadRequirements'
download_requirements:
$ref: '#/components/schemas/DownloadRequirements'
overage:
$ref: '#/components/schemas/OverageDetails'
agreement_name:
type: string
nullable: true
imagepack_resolution:
type: string
nullable: true
team_credits:
type: integer
format: int32
nullable: true
additionalProperties: false
ProductsResult:
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
nullable: true
additionalProperties: false
PreviousPurchase:
type: object
properties:
date_purchased:
type: string
format: date-time
image_id:
type: string
nullable: true
license_model:
type: string
nullable: true
order_id:
type: string
nullable: true
thumb_uri:
type: string
nullable: true
additionalProperties: false
PreviousPurchases:
type: object
properties:
result_count:
type: integer
format: int32
previous_purchases:
type: array
items:
$ref: '#/components/schemas/PreviousPurchase'
nullable: true
additionalProperties: false
PreviousAssetPurchase:
type: object
properties:
date_purchased:
type: string
format: date-time
purchased_by:
type: string
nullable: true
asset_id:
type: string
nullable: true
asset_type:
type: string
nullable: true
license_model:
type: string
nullable: true
order_id:
type: string
nullable: true
thumb_uri:
type: string
nullable: true
size_name:
type: string
nullable: true
file_size_in_bytes:
type: string
nullable: true
download_uri:
type: string
nullable: true
additionalProperties: false
PreviousAssetPurchases:
type: object
properties:
result_count:
type: integer
format: int32
previous_purchases:
type: array
items:
$ref: '#/components/schemas/PreviousAssetPurchase'
nullable: true
additionalProperties: false
EditorialSegmentContract:
enum:
- archival
- entertainment
- news
- publicity
- royalty
- sport
type: string
EventFieldValues:
enum:
- id
- child_event_count
- editorial_segments
- hero_image
- image_count
- keywords
- location
- name
- start_date
- type
type: string
EventSearchSortOrder:
enum:
- newest
- oldest
type: string
HeroImageDisplaySize:
type: object
properties:
name:
type: string
nullable: true
is_watermarked:
type: boolean
uri:
type: string
nullable: true
additionalProperties: false
HeroImage:
type: object
properties:
id:
type: string
nullable: true
display_sizes:
type: array
items:
$ref: '#/components/schemas/HeroImageDisplaySize'
nullable: true
additionalProperties: false
LocationEvent:
type: object
properties:
city:
type: string
nullable: true
country:
type: string
nullable: true
state_province:
type: string
nullable: true
venue:
type: string
nullable: true
additionalProperties: false
Event:
type: object
properties:
child_event_count:
type: integer
format: int32
editorial_segments:
type: array
items:
type: string
nullable: true
hero_image:
$ref: '#/components/schemas/HeroImage'
id:
type: integer
format: int32
image_count:
type: integer
format: int32
location:
$ref: '#/components/schemas/LocationEvent'
name:
type: string
nullable: true
start_date:
type: string
format: date-time
nullable: true
additionalProperties: false
EventsSearchResult:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/Event'
nullable: true
result_count:
type: integer
format: int32
additionalProperties: false
AgeOfPeopleFilterType:
enum:
- newborn
- baby
- child
- teenager
- young_adult
- adult
- adults_only
- mature_adult
- senior_adult
- 0-1_months
- 2-5_months
- 6-11_months
- 12-17_months
- 18-23_months
- 2-3_years
- 4-5_years
- 6-7_years
- 8-9_years
- 10-11_years
- 12-13_years
- 14-15_years
- 16-17_years
- 18-19_years
- 20-24_years
- 20-29_years
- 25-29_years
- 30-34_years
- 30-39_years
- 35-39_years
- 40-44_years
- 40-49_years
- 45-49_years
- 50-54_years
- 50-59_years
- 55-59_years
- 60-64_years
- 60-69_years
- 65-69_years
- 70-79_years
- 80-89_years
- 90_plus_years
- 100_over
type: string
CollectionsFilterType:
enum:
- include
- exclude
type: string
CompositionsFilterType:
enum:
- abstract
- candid
- close_up
- copy_space
- cut_out
- full_frame
- full_length
- headshot
- looking_at_camera
- macro
- medium_shot
- part_of_a_series
- portrait
- sparse
- still_life
- three_quarter_length
- waist_up
- wide_shot
type: string
EthnicityFilterType:
enum:
- black
- white
- east_asian
- hispanic_latinx
- japanese
- middle_eastern
- multiracial_person
- multiethnic_group
- native_american_first_nations
- pacific_islander
- south_asian
- southeast_asian
type: string
CreateImageSearchFacetsFields:
enum:
- artists
- locations
type: string
CreativeImagesFieldValues:
enum:
- allowed_use
- alternative_ids
- artist
- asset_family
- call_for_image
- caption
- collection_code
- collection_id
- collection_name
- color_type
- comp
- comp_webp
- copyright
- date_camera_shot
- date_created
- date_submitted
- detail_set
- display_set
- download_product
- download_sizes
- graphical_style
- id
- istock_collection
- keywords
- largest_downloads
- license_model
- max_dimensions
- orientation
- preview
- product_types
- quality_rank
- referral_destinations
- summary_set
- thumb
- title
- uri_oembed
type: string
SearchFileType:
enum:
- eps
type: string
GraphicalStyle:
enum:
- fine_art
- illustration
- photography
- vector
type: string
GraphicalStylesFilterType:
enum:
- include
- exclude
type: string
LicenseModelImageRequest:
enum:
- rightsmanaged
- royaltyfree
type: string
TeeShirtSize:
enum:
- x_small
- small
- medium
- large
- x_large
- xx_large
- vector
type: string
MoodFilterType:
enum:
- black_and_white
- bold
- cool
- dramatic
- natural
- vivid
- warm
type: string
NumberOfPeopleFilterType:
enum:
- none
- one
- two
- group
type: string
ImageOrientationRequest:
enum:
- horizontal
- vertical
- square
- panoramic_horizontal
- panoramic_vertical
type: string
CreativeImageSortOrder:
enum:
- best_match
- most_popular
- newest
- random
type: string
ImageSearchItemCreative:
type: object
properties:
allowed_use:
$ref: '#/components/schemas/AllowedUse'
alternative_ids:
type: object
additionalProperties:
type: string
nullable: true
artist:
type: string
nullable: true
asset_family:
type: string
nullable: true
call_for_image:
type: boolean
caption:
type: string
nullable: true
collection_code:
type: string
nullable: true
collection_id:
type: integer
format: int32
nullable: true
collection_name:
type: string
nullable: true
color_type:
type: string
nullable: true
copyright:
type: string
nullable: true
date_camera_shot:
type: string
format: date-time
nullable: true
date_created:
type: string
format: date-time
nullable: true
display_sizes:
type: array
items:
$ref: '#/components/schemas/ImageSearchItemDisplaySize'
nullable: true
download_product:
type: string
nullable: true
graphical_style:
type: string
nullable: true
id:
type: string
nullable: true
keywords:
type: array
items:
$ref: '#/components/schemas/Keyword'
nullable: true
largest_downloads:
type: array
items:
$ref: '#/components/schemas/Download'
nullable: true
license_model:
type: string
nullable: true
max_dimensions:
$ref: '#/components/schemas/MaxDimensions'
orientation:
type: string
nullable: true
quality_rank:
type: integer
format: int32
referral_destinations:
type: array
items:
$ref: '#/components/schemas/ReferralDestination'
nullable: true
title:
type: string
nullable: true
uri_oembed:
type: string
nullable: true
additionalProperties: false
CreativeImageSearchResults:
type: object
properties:
result_count:
type: integer
format: int32
images:
type: array
items:
$ref: '#/components/schemas/ImageSearchItemCreative'
nullable: true
auto_corrections:
$ref: '#/components/schemas/AutoCorrections'
related_searches:
type: array
items:
$ref: '#/components/schemas/RelatedSearch'
nullable: true
additionalProperties: false
SpecificPeople:
type: object
properties:
id:
type: integer
format: int32
name:
type: string
nullable: true
additionalProperties: false
FacetEvent:
type: object
properties:
id:
type: integer
format: int32
name:
type: string
nullable: true
date:
type: string
format: date-time
additionalProperties: false
Location:
type: object
properties:
id:
type: integer
format: int32
name:
type: string
nullable: true
additionalProperties: false
Artist:
type: object
properties:
name:
type: string
nullable: true
additionalProperties: false
Entertainment:
type: object
properties:
id:
type: integer
format: int32
name:
type: string
nullable: true
additionalProperties: false
SearchFacetsResponse:
type: object
properties:
specific_people:
type: array
items:
$ref: '#/components/schemas/SpecificPeople'
nullable: true
events:
type: array
items:
$ref: '#/components/schemas/FacetEvent'
nullable: true
locations:
type: array
items:
$ref: '#/components/schemas/Location'
nullable: true
artists:
type: array
items:
$ref: '#/components/schemas/Artist'
nullable: true
entertainment:
type: array
items:
$ref: '#/components/schemas/Entertainment'
nullable: true
additionalProperties: false
SearchByImageResourceResults:
type: object
properties:
image_fingerprint:
type: string
nullable: true
related_searches:
type: array
items:
$ref: '#/components/schemas/RelatedSearch'
nullable: true
deprecated: true
result_count:
type: integer
format: int32
images:
nullable: true
facets:
$ref: '#/components/schemas/SearchFacetsResponse'
auto_corrections:
$ref: '#/components/schemas/AutoCorrections'
additionalProperties: false
EditorialImagesFieldValues:
enum:
- allowed_use
- alternative_ids
- artist
- asset_family
- call_for_image
- caption
- collection_code
- collection_id
- collection_name
- color_type
- comp
- comp_webp
- copyright
- date_camera_shot
- date_created
- date_submitted
- detail_set
- display_set
- download_product
- download_sizes
- editorial_segments
- editorial_source
- event_ids
- graphical_style
- id
- keywords
- largest_downloads
- license_model
- max_dimensions
- orientation
- people
- preview
- product_types
- quality_rank
- referral_destinations
- summary_set
- thumb
- title
- uri_oembed
type: string
EditorialGraphicalStyle:
enum:
- photography
- illustration
- vector
type: string
SortOrder:
enum:
- best_match
- most_popular
- newest
- oldest
- random
type: string
EditorialImageSearchFacetsFields:
enum:
- artists
- events
- locations
- specific_people
type: string
EditorialSource:
type: object
properties:
id:
type: integer
format: int32
additionalProperties: false
ImageSearchItemEditorial:
type: object
properties:
allowed_use:
$ref: '#/components/schemas/AllowedUse'
alternative_ids:
type: object
additionalProperties:
type: string
nullable: true
artist:
type: string
nullable: true
asset_family:
type: string
nullable: true
call_for_image:
type: boolean
caption:
type: string
nullable: true
collection_code:
type: string
nullable: true
collection_id:
type: integer
format: int32
nullable: true
collection_name:
type: string
nullable: true
color_type:
type: string
nullable: true
copyright:
type: string
nullable: true
date_camera_shot:
type: string
format: date-time
nullable: true
date_created:
type: string
format: date-time
nullable: true
display_sizes:
type: array
items:
$ref: '#/components/schemas/ImageSearchItemDisplaySize'
nullable: true
download_product:
type: string
nullable: true
editorial_segments:
type: array
items:
type: string
nullable: true
editorial_source:
$ref: '#/components/schemas/EditorialSource'
event_ids:
type: array
items:
type: integer
format: int32
nullable: true
graphical_style:
type: string
nullable: true
id:
type: string
nullable: true
keywords:
type: array
items:
$ref: '#/components/schemas/Keyword'
nullable: true
largest_downloads:
type: array
items:
$ref: '#/components/schemas/Download'
nullable: true
license_model:
type: string
nullable: true
max_dimensions:
$ref: '#/components/schemas/MaxDimensions'
orientation:
type: string
nullable: true
people:
type: array
items:
type: string
nullable: true
product_types:
type: array
items:
type: string
nullable: true
quality_rank:
type: integer
format: int32
referral_destinations:
type: array
items:
$ref: '#/components/schemas/ReferralDestination'
nullable: true
title:
type: string
nullable: true
uri_oembed:
type: string
nullable: true
additionalProperties: false
EditorialImageSearchResults:
type: object
properties:
result_count:
type: integer
format: int32
images:
type: array
items:
$ref: '#/components/schemas/ImageSearchItemEditorial'
nullable: true
related_searches:
type: array
items:
$ref: '#/components/schemas/RelatedSearch'
nullable: true
additionalProperties: false
VideoAspectRatioFilterType:
enum:
- '16:9'
- '9:16'
- '3:4'
- '4:3'
- '4:5'
- '2:1'
- '17:9'
- '9:17'
type: string
EditorialVideoType:
enum:
- raw
- produced
type: string
VideoFormatsRequest:
enum:
- sd
- hd
- 4k
- hd_web
type: string
VideoFrameRates:
enum:
- '23.98'
- '24'
- '25'
- '29.97'
- '30'
- '50'
- '59.94'
- '60'
type: string
BlendedVideosFieldValues:
enum:
- allowed_use
- artist
- aspect_ratio
- asset_family
- call_for_image
- caption
- clip_length
- collection_code
- collection_id
- collection_name
- color_type
- comp
- copyright
- date_created
- date_submitted
- detail_set
- display_set
- download_product
- download_sizes
- editorial_segments
- entity_details
- era
- event_ids
- id
- istock_collection
- keywords
- largest_downloads
- license_model
- mastered_to
- object_name
- orientation
- originally_shot_on
- preview
- product_types
- quality_rank
- referral_destinations
- shot_speed
- source
- summary_set
- thumb
- title
- istock_licenses
type: string
LicenseModelVideoRequest:
enum:
- rightsready
- royaltyfree
type: string
VideoOrientationRequest:
enum:
- horizontal
- vertical
type: string
ReleaseStatus:
enum:
- release_not_important
- fully_released
type: string
VideoSearchItemDisplaySize:
type: object
properties:
is_watermarked:
type: boolean
name:
type: string
nullable: true
uri:
type: string
nullable: true
aspect_ratio:
type: string
nullable: true
additionalProperties: false
BlendedVideoSearchItem:
type: object
properties:
source:
type: string
nullable: true
id:
type: string
nullable: true
allowed_use:
$ref: '#/components/schemas/AllowedUse'
artist:
type: string
nullable: true
asset_family:
type: string
nullable: true
caption:
type: string
nullable: true
clip_length:
type: string
nullable: true
collection_id:
type: integer
format: int32
nullable: true
collection_code:
type: string
nullable: true
collection_name:
type: string
nullable: true
color_type:
type: string
nullable: true
copyright:
type: string
nullable: true
date_created:
type: string
format: date-time
nullable: true
display_sizes:
type: array
items:
$ref: '#/components/schemas/VideoSearchItemDisplaySize'
nullable: true
download_product:
type: string
nullable: true
era:
type: string
nullable: true
event_ids:
type: array
items:
type: integer
format: int32
nullable: true
keywords:
type: array
items:
$ref: '#/components/schemas/Keyword'
nullable: true
largest_downloads:
type: array
items:
$ref: '#/components/schemas/Download'
nullable: true
license_model:
type: string
nullable: true
mastered_to:
type: string
nullable: true
originally_shot_on:
type: string
nullable: true
product_types:
type: array
items:
type: string
nullable: true
referral_destinations:
type: array
items:
$ref: '#/components/schemas/ReferralDestination'
nullable: true
shot_speed:
type: string
nullable: true
title:
type: string
nullable: true
istock_licenses:
type: array
items:
$ref: '#/components/schemas/IStockLicense'
nullable: true
additionalProperties: false
BlendedVideoSearchResults:
type: object
properties:
result_count:
type: integer
format: int32
videos:
type: array
items:
$ref: '#/components/schemas/BlendedVideoSearchItem'
nullable: true
facets:
$ref: '#/components/schemas/SearchFacetsResponse'
related_searches:
type: array
items:
$ref: '#/components/schemas/RelatedSearch'
nullable: true
additionalProperties: false
CreateVideoSearchFacetsFields:
enum:
- artists
- locations
type: string
CreativeVideosFieldValues:
enum:
- allowed_use
- artist
- aspect_ratio
- asset_family
- call_for_image
- caption
- clip_length
- collection_code
- collection_id
- collection_name
- color_type
- comp
- copyright
- date_created
- date_submitted
- detail_set
- display_set
- download_product
- download_sizes
- era
- id
- istock_collection
- keywords
- largest_downloads
- license_model
- mastered_to
- object_name
- orientation
- originally_shot_on
- preview
- product_types
- quality_rank
- referral_destinations
- shot_speed
- summary_set
- thumb
- title
type: string
ImageTechniquesFilterType:
enum:
- realtime
- time_lapse
- slow_motion
- color
- black_and_white
- animation
- selective_focus
type: string
CreativeVideoSortOrder:
enum:
- best_match
- most_popular
- newest
- random
type: string
ViewpointsFilterType:
enum:
- lockdown
- panning
- tracking_shot
- aerial_view
- high_angle_view
- low_angle_view
- tilt
- point_of_view
type: string
CreativeVideoSearchItem:
type: object
properties:
id:
type: string
nullable: true
allowed_use:
$ref: '#/components/schemas/AllowedUse'
artist:
type: string
nullable: true
asset_family:
type: string
nullable: true
caption:
type: string
nullable: true
clip_length:
type: string
nullable: true
collection_id:
type: integer
format: int32
nullable: true
collection_code:
type: string
nullable: true
collection_name:
type: string
nullable: true
color_type:
type: string
nullable: true
copyright:
type: string
nullable: true
date_created:
type: string
format: date-time
nullable: true
display_sizes:
type: array
items:
$ref: '#/components/schemas/VideoSearchItemDisplaySize'
nullable: true
download_product:
type: string
nullable: true
era:
type: string
nullable: true
event_ids:
type: array
items:
type: integer
format: int32
nullable: true
keywords:
type: array
items:
$ref: '#/components/schemas/Keyword'
nullable: true
largest_downloads:
type: array
items:
$ref: '#/components/schemas/Download'
nullable: true
license_model:
type: string
nullable: true
mastered_to:
type: string
nullable: true
originally_shot_on:
type: string
nullable: true
product_types:
type: array
items:
type: string
nullable: true
referral_destinations:
type: array
items:
$ref: '#/components/schemas/ReferralDestination'
nullable: true
shot_speed:
type: string
nullable: true
title:
type: string
nullable: true
istock_licenses:
type: array
items:
$ref: '#/components/schemas/IStockLicense'
nullable: true
additionalProperties: false
CreativeVideoSearchResults:
type: object
properties:
result_count:
type: integer
format: int32
videos:
type: array
items:
$ref: '#/components/schemas/CreativeVideoSearchItem'
nullable: true
facets:
$ref: '#/components/schemas/SearchFacetsResponse'
auto_corrections:
$ref: '#/components/schemas/AutoCorrections'
related_searches:
type: array
items:
$ref: '#/components/schemas/RelatedSearch'
nullable: true
additionalProperties: false
EditorialVideosFieldValues:
enum:
- allowed_use
- artist
- aspect_ratio
- asset_family
- call_for_image
- caption
- clip_length
- collection_code
- collection_id
- collection_name
- color_type
- comp
- copyright
- date_created
- date_submitted
- detail_set
- display_set
- download_product
- download_sizes
- editorial_segments
- era
- event_ids
- id
- istock_collection
- keywords
- largest_downloads
- license_model
- mastered_to
- object_name
- orientation
- originally_shot_on
- preview
- product_types
- quality_rank
- referral_destinations
- shot_speed
- source
- summary_set
- thumb
- title
- istock_licenses
type: string
EditorialVideoSearchFacetsFields:
enum:
- artists
- events
- locations
- specific_people
type: string
EditorialVideoSearchItem:
type: object
properties:
source:
type: string
nullable: true
id:
type: string
nullable: true
allowed_use:
$ref: '#/components/schemas/AllowedUse'
artist:
type: string
nullable: true
asset_family:
type: string
nullable: true
caption:
type: string
nullable: true
clip_length:
type: string
nullable: true
collection_id:
type: integer
format: int32
nullable: true
collection_code:
type: string
nullable: true
collection_name:
type: string
nullable: true
color_type:
type: string
nullable: true
copyright:
type: string
nullable: true
date_created:
type: string
format: date-time
nullable: true
display_sizes:
type: array
items:
$ref: '#/components/schemas/VideoSearchItemDisplaySize'
nullable: true
download_product:
type: string
nullable: true
era:
type: string
nullable: true
event_ids:
type: array
items:
type: integer
format: int32
nullable: true
keywords:
type: array
items:
$ref: '#/components/schemas/Keyword'
nullable: true
largest_downloads:
type: array
items:
$ref: '#/components/schemas/Download'
nullable: true
license_model:
type: string
nullable: true
mastered_to:
type: string
nullable: true
originally_shot_on:
type: string
nullable: true
product_types:
type: array
items:
type: string
nullable: true
referral_destinations:
type: array
items:
$ref: '#/components/schemas/ReferralDestination'
nullable: true
shot_speed:
type: string
nullable: true
title:
type: string
nullable: true
istock_licenses:
type: array
items:
$ref: '#/components/schemas/IStockLicense'
nullable: true
additionalProperties: false
EditorialVideoSearchResults:
type: object
properties:
result_count:
type: integer
format: int32
videos:
type: array
items:
$ref: '#/components/schemas/EditorialVideoSearchItem'
nullable: true
facets:
$ref: '#/components/schemas/SearchFacetsResponse'
related_searches:
type: array
items:
$ref: '#/components/schemas/RelatedSearch'
nullable: true
additionalProperties: false
BlendedImageSortOrder:
enum:
- best_match
- most_popular
- newest
- random
type: string
VideoDetailFieldValues:
enum:
- id
- allowed_use
- artist
- asset_family
- call_for_image
- caption
- city
- clip_length
- collection_code
- collection_id
- collection_name
- color_type
- comp
- copyright
- country
- date_created
- date_submitted
- detail_set
- display_set
- download_sizes
- download_product
- downloads
- editorial_segments
- entity_details
- era
- event_ids
- is_ai_editable
- istock_collection
- istock_licenses
- key_frames
- keywords
- license_model
- mastered_to
- max_dimensions
- object_name
- orientation
- originally_shot_on
- people
- preview
- product_types
- quality_rank
- referral_destinations
- shot_speed
- source
- state_province
- summary_set
- thumb
- title
type: string
AssociatedVideoDetailFieldValues:
enum:
- allowed_use
- artist
- aspect_ratio
- asset_family
- call_for_image
- caption
- clip_length
- collection_code
- collection_id
- collection_name
- color_type
- comp
- copyright
- date_created
- date_submitted
- detail_set
- display_set
- download_product
- download_sizes
- editorial_segments
- entity_details
- era
- event_ids
- id
- istock_collection
- keywords
- largest_downloads
- license_model
- mastered_to
- orientation
- originally_shot_on
- preview
- product_types
- quality_rank
- referral_destinations
- shot_speed
- source
- summary_set
- thumb
- title
- istock_licenses
type: string
asset_usage:
type: object
properties:
asset_id:
type: string
description: Specifies the Id of the asset that was used.
nullable: true
quantity:
type: integer
description: Specifies the number of times the asset was used.
format: int32
usage_date:
type: string
description: >-
Identifies the date the asset was used, in ISO 8601 format (e.g.,
YYYY-MM-DD), time is not needed.
format: date-time
additionalProperties: false
description: Specifies the id, usage Quantity, and date of when an asset was used.
report_usage_batch_request:
type: object
properties:
asset_usages:
type: array
items:
$ref: '#/components/schemas/asset_usage'
description: >-
Identifies the list of asset id, usage count and date of usage
combinations to record.
nullable: true
additionalProperties: false
description: Specifies the request information for the Batch Usages endpoint.
report_usage_batch_response:
type: object
properties:
invalid_assets:
type: array
items:
type: string
description: >-
Identifies a list of asset ids submitted that did not match known
Getty asset ids.
nullable: true
total_asset_usages_processed:
type: integer
description: >-
Specifies the number of asset usage records that were successfully
recorded.
format: int32
nullable: true
additionalProperties: false
description: Specifies the response from the Batch Usages endpoint.
ChangedAssetDetail:
type: object
properties:
asset_changed_utc_datetime:
type: string
description: Contains the date of the asset change.
format: date-time
asset_lifecycle:
type: string
description: >-
Contains the type of change this asset change is. (i.e. "New,"
"Updated" or "Deleted")
nullable: true
asset_type:
type: string
description: Contains the type of asset this asset change is (i.e. "Image").
nullable: true
id:
type: string
description: Contains the Id for the asset change.
nullable: true
uri:
type: string
description: >-
Contains the asset download URL for assets with an AssetLifecycle of
"New."
nullable: true
additionalProperties: false
AssetChanges:
type: object
properties:
change_set_id:
type: string
description: >-
Contains the identifier for the change-set resource. Passed into
ConfirmAssetChanges requests to confirm receipt of the asset changes
in the response.
nullable: true
changed_assets:
type: array
items:
$ref: '#/components/schemas/ChangedAssetDetail'
description: Contains a list of ChangedAssetList results for the query.
nullable: true
additionalProperties: false
AssetFamily:
enum:
- NotSet
- Editorial
- Creative
- Both
type: string
AssetType:
enum:
- NotSet
- Image
- Film
- Music
type: string
Channel:
type: object
properties:
ChannelId:
type: integer
format: int32
AssetFamily:
$ref: '#/components/schemas/AssetFamily'
AssetChangeType:
type: string
nullable: true
CreateDateUtc:
type: string
format: date-time
NotificationCount:
type: integer
format: int32
AssetType:
$ref: '#/components/schemas/AssetType'
OldestChangeNotificationDateUtc:
type: string
format: date-time
Metadata:
type: string
nullable: true
additionalProperties: false
BoardRelationship:
enum:
- owned
- invited
type: string
BoardSortOrder:
enum:
- date_last_updated_descending
- date_last_updated_ascending
- name_ascending
- name_decending
type: string
DisplaySize:
type: object
properties:
name:
type: string
nullable: true
uri:
type: string
nullable: true
additionalProperties: false
Asset:
type: object
properties:
id:
type: string
nullable: true
asset_type:
type: string
nullable: true
date_added:
type: string
format: date-time
display_sizes:
type: array
items:
$ref: '#/components/schemas/DisplaySize'
nullable: true
additionalProperties: false
BoardListBoard:
type: object
properties:
id:
type: string
nullable: true
asset_count:
type: integer
format: int32
date_created:
type: string
format: date-time
date_last_updated:
type: string
format: date-time
description:
type: string
nullable: true
hero_asset:
$ref: '#/components/schemas/Asset'
name:
type: string
nullable: true
board_relationship:
type: string
nullable: true
additionalProperties: false
BoardList:
type: object
properties:
boards:
type: array
items:
$ref: '#/components/schemas/BoardListBoard'
nullable: true
board_count:
type: integer
format: int32
additionalProperties: false
BoardInfo:
required:
- name
type: object
properties:
name:
type: string
description:
type: string
nullable: true
additionalProperties: false
BoardCreated:
type: object
properties:
id:
type: string
nullable: true
additionalProperties: false
BoardPermissions:
type: object
properties:
can_delete_board:
type: boolean
can_invite_to_board:
type: boolean
can_update_name:
type: boolean
can_update_description:
type: boolean
can_add_assets:
type: boolean
can_remove_assets:
type: boolean
additionalProperties: false
Links:
type: object
properties:
invitation:
type: string
nullable: true
share:
type: string
nullable: true
additionalProperties: false
BoardDetail:
type: object
properties:
id:
type: string
nullable: true
asset_count:
type: integer
format: int32
assets:
type: array
items:
$ref: '#/components/schemas/Asset'
nullable: true
date_created:
type: string
format: date-time
date_last_updated:
type: string
format: date-time
description:
type: string
nullable: true
name:
type: string
nullable: true
comment_count:
type: integer
format: int32
permissions:
$ref: '#/components/schemas/BoardPermissions'
links:
$ref: '#/components/schemas/Links'
additionalProperties: false
BoardAsset:
required:
- asset_id
type: object
properties:
asset_id:
type: string
additionalProperties: false
AddBoardAssetsResult:
type: object
properties:
assets_added:
type: array
items:
$ref: '#/components/schemas/BoardAsset'
nullable: true
assets_not_added:
type: array
items:
type: string
nullable: true
additionalProperties: false
Collaborator:
type: object
properties:
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
additionalProperties: false
CommentPermissions:
type: object
properties:
can_delete_comment:
type: boolean
additionalProperties: false
Comment:
type: object
properties:
created_by:
$ref: '#/components/schemas/Collaborator'
date_created:
type: string
format: date-time
id:
type: string
nullable: true
permissions:
$ref: '#/components/schemas/CommentPermissions'
text:
type: string
nullable: true
additionalProperties: false
BoardCommentPermissions:
type: object
properties:
can_add_comment:
type: boolean
additionalProperties: false
CommentsList:
type: object
properties:
comments:
type: array
items:
$ref: '#/components/schemas/Comment'
nullable: true
permissions:
$ref: '#/components/schemas/BoardCommentPermissions'
additionalProperties: false
CommentRequest:
type: object
properties:
text:
type: string
nullable: true
additionalProperties: false
CommentCreated:
type: object
properties:
id:
type: string
nullable: true
additionalProperties: false
SelfResult:
type: object
properties:
id:
type: string
nullable: true
name:
type: string
nullable: true
email:
type: string
nullable: true
additionalProperties: false
AssetDetail:
type: object
properties:
id:
type: string
nullable: true
additionalProperties: false
BackgroundGenerationRequest:
type: object
properties:
reference_file_registration_id:
type: string
nullable: true
prompt:
type: string
nullable: true
negative_prompt:
type: string
nullable: true
product_id:
type: integer
format: int32
nullable: true
project_code:
type: string
nullable: true
notes:
type: string
nullable: true
left_percentage:
type: number
format: float
nullable: true
right_percentage:
type: number
format: float
nullable: true
top_percentage:
type: number
format: float
nullable: true
bottom_percentage:
type: number
format: float
nullable: true
additionalProperties: false
BackgroundRemovalRequest:
type: object
properties:
reference_asset_id:
type: string
description: Asset Id to modify.
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this refine request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the request. Some products require this
value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
additionalProperties: false
description: Remove a background
Category:
enum:
- ImageReference
- CustomerProduct
type: string
DepthOfField:
enum:
- shallow
- deep
type: string
DownloadResponse:
type: object
properties:
url:
type: string
nullable: true
generated_asset_id:
type: string
nullable: true
additionalProperties: false
DownloadSizeResponse:
type: object
properties:
size_name:
type: string
nullable: true
height:
type: integer
format: int32
width:
type: integer
format: int32
additionalProperties: false
DownloadSizesResponse:
type: object
properties:
download_sizes:
type: array
items:
$ref: '#/components/schemas/DownloadSizeResponse'
nullable: true
additionalProperties: false
ExtendRequest:
type: object
properties:
reference_asset_id:
type: string
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
prompt:
type: string
nullable: true
negative_prompt:
type: string
nullable: true
product_id:
type: integer
format: int32
nullable: true
project_code:
type: string
nullable: true
notes:
type: string
nullable: true
left_percentage:
type: number
format: float
nullable: true
right_percentage:
type: number
format: float
nullable: true
top_percentage:
type: number
format: float
nullable: true
bottom_percentage:
type: number
format: float
nullable: true
additionalProperties: false
FileRegistrationRequest:
type: object
properties:
url:
type: string
description: The location of the file.
nullable: true
rights_claimed:
type: boolean
description: Acknowledgment of ownership or licensing of file.
nullable: true
category:
$ref: '#/components/schemas/Category'
additionalProperties: false
description: Parameters for registering a file
FileRegistrationResponse:
type: object
properties:
id:
type: string
nullable: true
additionalProperties: false
GenerationHistoryItemResponse:
type: object
properties:
generation_request_id:
type: string
description: The identifier for the request
nullable: true
seed:
type: integer
description: The seed used for the generation
format: int32
nullable: true
generation_date:
type: string
description: ''
format: date-time
product_revoked_date:
type: string
description: >-
If the the product against which the generation was made has been
revoked, this is the date of that revocation.
format: date-time
nullable: true
prompt:
type: string
description: The prompt that was used for the request
nullable: true
negative_prompt:
type: string
description: The negative prompt (if any) that was used for the request
nullable: true
product_id:
type: integer
description: ''
format: int32
notes:
type: string
description: ''
nullable: true
project_code:
type: string
description: ''
nullable: true
generation_type:
$ref: '#/components/schemas/GenerationType'
generation_options:
$ref: '#/components/schemas/GenerationOptions'
source_generation_request:
$ref: '#/components/schemas/SourceGenerationRequest'
original_asset:
$ref: '#/components/schemas/AssetDetail'
results:
type: array
items:
$ref: '#/components/schemas/GenerationHistoryResult'
description: ''
nullable: true
user:
$ref: '#/components/schemas/User'
additionalProperties: false
description: Detail on a specific historical generation
GenerationHistoryResponse:
type: object
properties:
generations:
type: array
items:
$ref: '#/components/schemas/GenerationHistoryItemResponse'
description: Current page of generations
nullable: true
result_count:
type: integer
description: The total count of results, ignoring paging
format: int32
additionalProperties: false
description: Full generation history response
GenerationHistoryResult:
type: object
properties:
index:
type: integer
description: The index of the result from the original generation
format: int32
is_blocked:
type: boolean
description: If `true` the result was blocked due to AI generation policy
preview_urls:
type: array
items:
$ref: '#/components/schemas/PreviewUrl'
description: The preview URLs for the result
nullable: true
additionalProperties: false
description: Individual generated result from a given generation request/response
GenerationOptions:
type: object
properties:
media_type:
$ref: '#/components/schemas/MediaType'
aspect_ratio:
type: string
nullable: true
mood:
$ref: '#/components/schemas/Mood'
additionalProperties: false
GenerationType:
enum:
- text_to_image
- variation
- extend
- refine
- background_removal
- influence_color_by_image
- influence_composition_by_image
- object_removal
- influence_outline_by_image
- background_generation
type: string
GetFileRegistrationResponse:
type: object
properties:
id:
type: string
nullable: true
preview_urls:
type: array
items:
$ref: '#/components/schemas/PreviewUrl'
nullable: true
additionalProperties: false
ImageDataResponse:
type: object
properties:
index:
type: integer
format: int32
is_blocked:
type: boolean
preview_urls:
type: array
items:
$ref: '#/components/schemas/PreviewUrl'
description: The preview URLs for the result
nullable: true
url:
type: string
nullable: true
additionalProperties: false
ImageDownloadRequest:
type: object
properties:
notes:
type: string
description: >-
The notes to use for the download request. Some products require
this value.
nullable: true
project_code:
type: string
description: >-
The project code to use for the download request. Some products
require this value.
nullable: true
size_name:
type: string
description: The size name. Valid values are 1k or 4k.
nullable: true
additionalProperties: false
description: Parameters for requesting an AI generation image download
ImageExtendRequest:
type: object
properties:
prompt:
type: string
description: This is the primary text used for the extension of the image.
nullable: true
negative_prompt:
type: string
description: Concepts to exclude from the result
nullable: true
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this extend request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the request. Some products require this
value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
left_percentage:
type: number
description: The percentage to add to the left side of the image.
format: float
nullable: true
right_percentage:
type: number
description: The percentage to add to the right side of the image.
format: float
nullable: true
top_percentage:
type: number
description: The percentage to add to the top of the image.
format: float
nullable: true
bottom_percentage:
type: number
description: The percentage to add to the bottom of the image.
format: float
nullable: true
additionalProperties: false
description: Payload with all image extend parameters
ImageGenerationsRequest:
type: object
properties:
prompt:
type: string
description: >-
The only required parameter, this is the primary text used for the
generation of the images.
nullable: true
seed:
type: integer
description: >-
The seed to use for generation. This is not used for most generation
cases but is available for use to ensure a repeatable result.
format: int32
nullable: true
negative_prompt:
type: string
description: Concepts to exclude from the result
nullable: true
aspect_ratio:
type: string
description: >-
Aspect ratio of the result images. Must be one of 1:1, 3:4, 4:3,
9:16, or 16:9
nullable: true
media_type:
$ref: '#/components/schemas/MediaType'
mood:
$ref: '#/components/schemas/Mood'
lens_type:
$ref: '#/components/schemas/LensType'
depth_of_field:
$ref: '#/components/schemas/DepthOfField'
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this generation request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the generation request. Some products
require this value.
nullable: true
notes:
type: string
description: >-
The notes to use for the generation request. Some products require
this value.
nullable: true
additionalProperties: false
description: Payload with all generation request parameters
ImageGenerationsResponse:
type: object
properties:
generation_request_id:
type: string
nullable: true
seed:
type: integer
format: int32
nullable: true
results:
type: array
items:
$ref: '#/components/schemas/ImageDataResponse'
nullable: true
original_asset:
$ref: '#/components/schemas/AssetDetail'
additionalProperties: false
ImageRefineRequest:
type: object
properties:
prompt:
type: string
description: This is the primary text used for refining the images.
nullable: true
negative_prompt:
type: string
description: Concepts to exclude from the result
nullable: true
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this refine request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the request. Some products require this
value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
mask_url:
type: string
description: The location of the mask.
nullable: true
additionalProperties: false
description: Payload with all image refine parameters
ImageVariationRequest:
type: object
properties:
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this generation request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the generation request. Some products
require this value.
nullable: true
notes:
type: string
description: >-
The notes to use for the generation request. Some products require
this value.
nullable: true
additionalProperties: false
description: Payload with all images variation parameters
InfluenceColorByImageRequest:
type: object
properties:
reference_asset_id:
type: string
description: Asset Id to modify.
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
reference_file_registration_id:
type: string
description: File Id to modify.
nullable: true
prompt:
type: string
description: This is the primary text used for refining the images.
nullable: true
negative_prompt:
type: string
description: Concepts to exclude from the result.
nullable: true
noise_level:
type: number
description: >-
Accepted values are 0-1. Higher values will increase differences
between the reference and generated images.
format: float
nullable: true
media_type:
$ref: '#/components/schemas/MediaType'
mood:
$ref: '#/components/schemas/Mood'
seed:
type: integer
description: The seed used for the generation
format: int32
nullable: true
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this refine request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the request. Some products require this
value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
additionalProperties: false
description: Payload with all influence color by image parameters
InfluenceCompositionByImageRequest:
type: object
properties:
reference_asset_id:
type: string
description: Asset Id to modify.
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
reference_file_registration_id:
type: string
description: File Id to modify.
nullable: true
prompt:
type: string
description: This is the primary text used for refining the images.
nullable: true
negative_prompt:
type: string
description: Concepts to exclude from the result.
nullable: true
influence_level:
type: number
description: >-
Accepted values are 0-1. Higher values will increase the
similarities between the reference and generated images.
format: float
nullable: true
media_type:
$ref: '#/components/schemas/MediaType'
mood:
$ref: '#/components/schemas/Mood'
seed:
type: integer
description: The seed used for the generation
format: int32
nullable: true
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this refine request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the request. Some products require this
value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
additionalProperties: false
description: Payload with all influence composition by image parameters
InfluenceOutlineByImageRequest:
type: object
properties:
reference_file_registration_id:
type: string
description: File Id to modify.
nullable: true
seed:
type: integer
description: The seed used for the generation
format: int32
nullable: true
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this refine request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the request. Some products require this
value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
additionalProperties: false
description: Payload with all influence outline by image parameters
LensType:
enum:
- wide_angle
- telephoto
type: string
MediaType:
enum:
- photography
- illustration
type: string
Mood:
enum:
- black_and_white
- warm
- cool
- natural
- vivid
- dramatic
- bold
type: string
PendingImageGenerationResponse:
type: object
properties:
generation_request_id:
type: string
nullable: true
additionalProperties: false
PreviewUrl:
type: object
properties:
preview_size:
type: string
nullable: true
image_url:
type: string
nullable: true
width:
type: integer
format: int32
height:
type: integer
format: int32
additionalProperties: false
ReDownloadRequest:
type: object
properties:
generated_asset_id:
type: string
description: The identifier of the previously-downloaded generated asset.
nullable: true
product_id:
type: integer
description: The product ID to use for the download.
format: int32
size_name:
type: string
description: The size name. Valid values are 1k or 4k.
nullable: true
project_code:
type: string
description: >-
The project code to use for the download request. Some products
require this value.
nullable: true
notes:
type: string
description: >-
The notes to use for the download request. Some products require
this value.
nullable: true
additionalProperties: false
description: Parameters for requesting an AI generation re-download
ReferenceGeneration:
type: object
properties:
generation_request_id:
type: string
description: The id from a previous request to generate images.
nullable: true
index:
type: integer
description: The index of the image from the specific images generation.
format: int32
additionalProperties: false
RefineRequest:
required:
- mask_url
type: object
properties:
reference_asset_id:
type: string
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
prompt:
type: string
nullable: true
negative_prompt:
type: string
nullable: true
product_id:
type: integer
format: int32
nullable: true
project_code:
type: string
nullable: true
notes:
type: string
nullable: true
mask_url:
minLength: 1
type: string
additionalProperties: false
RemoveObjectRequest:
type: object
properties:
reference_asset_id:
type: string
description: Asset Id to modify.
nullable: true
reference_generation:
$ref: '#/components/schemas/ReferenceGeneration'
product_id:
type: integer
description: >-
If you have multiple Getty products, indicate which one you would
like to use for this refine request
format: int32
nullable: true
project_code:
type: string
description: >-
The project code to use for the request. Some products require this
value.
nullable: true
notes:
type: string
description: The notes to use for the request. Some products require this value.
nullable: true
mask_url:
type: string
description: The location of the mask.
nullable: true
additionalProperties: false
description: Payload with all parameters for removing objects from an image
SourceGenerationRequest:
type: object
properties:
source_generation_request_id:
type: string
nullable: true
source_generation_result_index:
type: integer
format: int32
additionalProperties: false
securitySchemes:
Api-Key:
type: apiKey
name: Api-Key
in: header
OAuth2:
type: oauth2
flows:
password:
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
refreshUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}
clientCredentials:
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}
authorizationCode:
authorizationUrl: https://api.gettyimages.com/v4/oauth2/auth
tokenUrl: https://api.gettyimages.com/v4/oauth2/token
refreshUrl: https://api.gettyimages.com/v4/oauth2/token
scopes: {}
security:
- Api-Key: []
- OAuth2: []