Getty Images Files API
The Files API from Getty Images — 3 operation(s) for files.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Files API
version: '3'
description: '
Developer resources for the Getty Images API including SDK, documentation,
release notes, status, notifications and sample code.'
security:
- Api-Key: []
- OAuth2: []
tags:
- name: Files
paths:
/beta/ai/file-registrations:
post:
tags:
- Files
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:
- Files
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/search/by-image/uploads/{file-name}:
put:
tags:
- Files
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
components:
schemas:
GetFileRegistrationResponse:
type: object
properties:
id:
type: string
nullable: true
preview_urls:
type: array
items:
$ref: '#/components/schemas/PreviewUrl'
nullable: true
additionalProperties: false
Category:
enum:
- ImageReference
- CustomerProduct
type: string
FileRegistrationResponse:
type: object
properties:
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
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
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: {}