---
title: "Register a client provided file for use with AIGenerator endpoints"
method: POST
path: "/v3/ai/file-registrations"
tags: ["AiGenerator"]
---

# Register a client provided file for use with AIGenerator endpoints

`POST /v3/ai/file-registrations`

## Request

- Base URL: `https://api.gettyimages.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gettyimages.com/v3/ai/file-registrations`
- Auth: one of:
  - API key in header `Api-Key`
  - OAuth 2
    - Authorization code: `https://authentication.gettyimages.com/oauth2/auth`
    - Client credentials
    - Password
    - Token URL: `https://authentication.gettyimages.com/oauth2/token`
- TypeScript: <https://skmtc.dev/gettyimages/apis/getty-images-api/docs/v3/ai/file-registrations/post.ts> (a function with typed inputs; its response is checked against the schema)

# 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.

## 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.

## Request body

- FileRegistrationRequest: Parameters for registering a file
  - `url` string, nullable: The location of the file.
  - `rights_claimed` boolean, nullable: Acknowledgment of ownership or licensing of file.
  - `category` 'ImageReference' | 'CustomerProduct'

## Response `200`

Returns the response

- FileRegistrationResponse
  - `id` string, nullable

## Other responses

- `400`: The request was invalid
- `403`: Not authorized

## Changes

- **2025-11-20** `81cb0e852242`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gettyimages/apis/getty-images-api/changes/v3/ai/file-registrations/post.md)

---

[API](https://skmtc.dev/gettyimages/apis/getty-images-api.md) - [All operations](https://skmtc.dev/gettyimages/apis/getty-images-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gettyimages/apis/getty-images-api/revisions/f20ce986456b?raw)