# Enhance

Enhance images by removing noise, sharpening, and upscaling while preserving the details of your image, including the faces of important subjects.

Just pass in an image and our **Autopilot** will automatically determine the best settings for the highest quality.

Additional configuration can be optionally provided, specifically:

* `model`
* `output_height`
* `output_width`
* `output_format`
* `crop_to_fill`

Please see the reference for further details. Check out the [available models](https://developer.topazlabs.com/image-api/available-models) to see which model options you have.

## Enhance

> Returns \`process\_id\` and \`eta\` to use as an efficient way to track the progress of the image enhancement job:\
>   \- Use the \`Status\` endpoints to check the status of this job using the returned \`process\_id\`.\
>   \- Use the \`Download\` endpoints to download the input or processed image (once it is ready).\
>   \- Use the \`Cancel\` endpoint to cancel the job while it is in progress.\
> \
> The same \`process\_id\` and \`eta\` are also returned in the response headers as \`X-Process-ID\` and \`X-ETA\` respectively.\
> \
> \> The \`eta\` represents when the job is expected to finish in Unix time. We recommend using this to know when you can expect your (bulk) jobs to finish processing.<br>

```json
{"openapi":"3.1.2","info":{"title":"Image API","version":"1.2.0"},"tags":[{"name":"Enhance","description":"Enhance images by removing noise, sharpening, and upscaling while preserving the details of your image, including the faces of important subjects.\n\nJust pass in an image and our **Autopilot** will automatically determine the best settings for the highest quality.\n\nAdditional configuration can be optionally provided, specifically:\n  - `model`\n  - `output_height`\n  - `output_width`\n  - `output_format`\n  - `crop_to_fill`\n\nPlease see the reference for further details. Check out the [available models](https://developer.topazlabs.com/image-api/available-models) to see which model options you have.\n"}],"servers":[{"url":"https://api.topazlabs.com/image/v1","description":"Production Base URL"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Authentication via the Topaz generated key in the `X-API-Key` header.\n"}},"schemas":{"EnhanceGANRequest":{"type":"object","properties":{"image":{"type":"string","contentMediaType":"application/octet-stream","description":"The image file to be processed. Supported formats:\n  - jpeg (or jpg)\n  - png\n  - tiff (or tif)\n"},"source_id":{"type":"string","description":"Unique identifier of the source image."},"source_url":{"type":"string","description":"The URL of the source image."},"model":{"type":"string","description":"The model to use for processing the image.","enum":["Standard V2","Low Resolution V2","CGI","High Fidelity V2","Text Refine"],"default":"Standard V2"},"output_height":{"type":"integer","description":"The desired height of the output image in pixels. Your image will automatically be upscaled to this specified value. If only one of `output_height` and `output_width` is set, then the other dimension is scaled proportionally.","minimum":1,"maximum":32000},"output_width":{"type":"integer","description":"The desired width of the output image in pixels. Your image will automatically be upscaled to this specified value. If only one of `output_height` and `output_width` is set, then the other dimension is scaled proportionally.","minimum":1,"maximum":32000},"crop_to_fill":{"type":"boolean","description":"Default behavior is to letterbox the image if a differing aspect ratio is chosen. Enable `crop_to_fill` by setting this to `true` if you instead want to crop the image to fill the dimensions.","default":false},"output_format":{"type":"string","description":"The desired format of the output image.","enum":["jpeg","jpg","png","tiff","tif"],"default":"jpeg"},"webhook_url":{"type":"string","description":"The URL to send the webhook to. When provided, a POST request with a JSON payload will be sent to this URL when the job status changes or completes.\n\n**Request Body:**\nThe webhook will be sent as a POST request with `Content-Type: application/json` containing the following fields:\n  - `notification_id` (string, ULID): Unique identifier for this notification. Can be used to order messages in case they are received out of order; see the [ULID specification](https://github.com/ulid/spec)\n  - `process_id` (string, UUID): Unique identifier of the image processing job.\n  - `status` (string): Current status of the job (i.e., \"Pending\", \"Processing\", \"Completed\", \"Cancelled\", \"Failed\").\n  - `creation_time` (integer): Unix timestamp in seconds when the job was created.\n  - `modification_time` (integer): Unix timestamp in seconds when the job was last modified.\n  - `progress` (integer): Progress of the job as a percentage (0-100).\n  - `download_url` (string, optional): Presigned GET URL for the processed image. Only present once the job is completed.\n  - `head_url` (string, optional): Presigned HEAD URL for the processed image. Only present once the job is completed.\n  - `input_download_url` (string): Presigned GET URL for the input image.\n  - `input_head_url` (string): Presigned HEAD URL for the input image.\n\n**Retry Behavior:**\nIf the webhook endpoint returns a 5xx server error, the system will retry the webhook with exponential backoff. The backoff starts at 5 seconds and doubles with each retry attempt (5s, 10s, 20s, 40s, etc.), up to a maximum of 15 minutes. Client errors (4xx status codes) are not retried and the notification is discarded.\n"}},"additionalProperties":{"type":"string","description":"Additional key-value pairs to be used as model settings. Only pairs relevant for your chosen model are used. Please see the [available models](https://developer.topazlabs.com/image-api/available-models) for more details."}},"AsyncResponse":{"type":"object","required":["process_id","source_id","eta"],"properties":{"process_id":{"type":"string","description":"Unique identifier of the image processing job."},"source_id":{"type":"string","description":"Unique identifier of the source image."},"eta":{"type":"integer","description":"Estimated time of arrival (ETA) for the process to complete in Unix time."}}}},"responses":{"BadRequestImage":{"description":"The request contains malformed data in the body, path, or query parameters.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"Unauthorized":{"description":"Authentication is required and has failed or has not yet been provided.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"PaymentRequired":{"description":"Payment is required to access the resource.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"Forbidden":{"description":"The API key doesn't have permissions to perform the request.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"PreconditionFailed":{"description":"The preconditions to process the request were not met.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"RequestEntityTooLarge":{"description":"The request is larger than the server is willing or able to process.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"UnsupportedMediaType":{"description":"The request entity has a media type which the server or resource does not support.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"UnprocessableEntity":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"TooEarly":{"description":"The request was sent too early to be processed. Please wait before retrying.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"TooManyRequests":{"description":"Too many requests hit the API too quickly. A backoff (e.g. exponential) is recommended for your requests.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"InternalServerError":{"description":"Unexpected error on our end.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}}}},"paths":{"/enhance/async":{"post":{"tags":["Enhance"],"summary":"Enhance","operationId":"postEnhance","description":"Returns `process_id` and `eta` to use as an efficient way to track the progress of the image enhancement job:\n  - Use the `Status` endpoints to check the status of this job using the returned `process_id`.\n  - Use the `Download` endpoints to download the input or processed image (once it is ready).\n  - Use the `Cancel` endpoint to cancel the job while it is in progress.\n\nThe same `process_id` and `eta` are also returned in the response headers as `X-Process-ID` and `X-ETA` respectively.\n\n> The `eta` represents when the job is expected to finish in Unix time. We recommend using this to know when you can expect your (bulk) jobs to finish processing.\n","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/EnhanceGANRequest"}}}},"responses":{"200":{"description":"Image processing request has been successfully created.","headers":{"X-Process-ID":{"description":"Unique identifier of the image processing job.","schema":{"type":"string"}},"X-Source-ID":{"description":"Unique identifier of the source image.","schema":{"type":"string"}},"X-ETA":{"description":"Estimated time of arrival (ETA) for the process to complete in Unix time.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}},"links":{"GetStatusByProcessId":{"description":"Retrieve the status of your image processing job using the `process_id`.","operationId":"getStatus","parameters":{"process_id":"$response.header.X-Process-ID"}},"DownloadInputByProcessId":{"description":"Access the download link for the input image once the job is completed.","operationId":"getDownloadInput","parameters":{"process_id":"$response.header.X-Process-ID"}},"DownloadOutputByProcessId":{"description":"Access the download link for the enhanced image once the job is completed.","operationId":"getDownloadOutput","parameters":{"process_id":"$response.header.X-Process-ID"}},"CancelByProcessId":{"description":"Cancel the image processing job if it is still in progress.","operationId":"cancelTask","parameters":{"process_id":"$response.header.X-Process-ID"}}}},"400":{"$ref":"#/components/responses/BadRequestImage"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/RequestEntityTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"425":{"$ref":"#/components/responses/TooEarly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Enhance Generative

> Returns \`process\_id\` and \`eta\` to use as an efficient way to track the progress of the image enhancement job:\
> &#x20; \- Use the \`Status\` endpoints to check the status of this job using the returned \`process\_id\`.\
> &#x20; \- Use the \`Download\` endpoints to download the input or processed image (once it is ready).\
> &#x20; \- Use the \`Cancel\` endpoint to cancel the job while it is in progress.\
> \
> The same \`process\_id\` and \`eta\` are also returned in the response headers as \`X-Process-ID\` and \`X-ETA\` respectively.\
> \
> \> The \`eta\` represents when the job is expected to finish in Unix time. We recommend using this to know when you can expect your (bulk) jobs to finish processing.<br>

```json
{"openapi":"3.1.2","info":{"title":"Image API","version":"1.2.0"},"tags":[{"name":"Enhance","description":"Enhance images by removing noise, sharpening, and upscaling while preserving the details of your image, including the faces of important subjects.\n\nJust pass in an image and our **Autopilot** will automatically determine the best settings for the highest quality.\n\nAdditional configuration can be optionally provided, specifically:\n  - `model`\n  - `output_height`\n  - `output_width`\n  - `output_format`\n  - `crop_to_fill`\n\nPlease see the reference for further details. Check out the [available models](https://developer.topazlabs.com/image-api/available-models) to see which model options you have.\n"}],"servers":[{"url":"https://api.topazlabs.com/image/v1","description":"Production Base URL"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Authentication via the Topaz generated key in the `X-API-Key` header.\n"}},"schemas":{"EnhanceGenRequest":{"type":"object","properties":{"image":{"type":"string","contentMediaType":"application/octet-stream","description":"The image file to be processed. Supported formats:\n  - jpeg (or jpg)\n  - png\n  - tiff (or tif)\n"},"source_id":{"type":"string","description":"Unique identifier of the source image."},"source_url":{"type":"string","description":"The URL of the source image."},"model":{"type":"string","description":"The model to use for processing the image.","enum":["Standard MAX","Recovery V2","Wonder","Redefine"],"default":"Redefine"},"output_height":{"type":"integer","description":"The desired height of the output image in pixels. Your image will automatically be upscaled to this specified value. If only one of `output_height` and `output_width` is set, then the other dimension is scaled proportionally.","minimum":1,"maximum":32000},"output_width":{"type":"integer","description":"The desired width of the output image in pixels. Your image will automatically be upscaled to this specified value. If only one of `output_height` and `output_width` is set, then the other dimension is scaled proportionally.","minimum":1,"maximum":32000},"crop_to_fill":{"type":"boolean","description":"Default behavior is to letterbox the image if a differing aspect ratio is chosen. Enable `crop_to_fill` by setting this to `true` if you instead want to crop the image to fill the dimensions.","default":false},"output_format":{"type":"string","description":"The desired format of the output image.","enum":["jpeg","jpg","png","tiff","tif"],"default":"jpeg"},"webhook_url":{"type":"string","description":"The URL to send the webhook to. When provided, a POST request with a JSON payload will be sent to this URL when the job status changes or completes.\n\n**Request Body:**\nThe webhook will be sent as a POST request with `Content-Type: application/json` containing the following fields:\n  - `notification_id` (string, ULID): Unique identifier for this notification. Can be used to order messages in case they are received out of order; see the [ULID specification](https://github.com/ulid/spec)\n  - `process_id` (string, UUID): Unique identifier of the image processing job.\n  - `status` (string): Current status of the job (i.e., \"Pending\", \"Processing\", \"Completed\", \"Cancelled\", \"Failed\").\n  - `creation_time` (integer): Unix timestamp in seconds when the job was created.\n  - `modification_time` (integer): Unix timestamp in seconds when the job was last modified.\n  - `progress` (integer): Progress of the job as a percentage (0-100).\n  - `download_url` (string, optional): Presigned GET URL for the processed image. Only present once the job is completed.\n  - `head_url` (string, optional): Presigned HEAD URL for the processed image. Only present once the job is completed.\n  - `input_download_url` (string): Presigned GET URL for the input image.\n  - `input_head_url` (string): Presigned HEAD URL for the input image.\n\n**Retry Behavior:**\nIf the webhook endpoint returns a 5xx server error, the system will retry the webhook with exponential backoff. The backoff starts at 5 seconds and doubles with each retry attempt (5s, 10s, 20s, 40s, etc.), up to a maximum of 15 minutes. Client errors (4xx status codes) are not retried and the notification is discarded.\n"}},"additionalProperties":{"type":"string","description":"Additional key-value pairs to be used as model settings. Only pairs relevant for your chosen model are used. Please see the [available models](https://developer.topazlabs.com/image-api/available-models) for more details."}},"AsyncResponse":{"type":"object","required":["process_id","source_id","eta"],"properties":{"process_id":{"type":"string","description":"Unique identifier of the image processing job."},"source_id":{"type":"string","description":"Unique identifier of the source image."},"eta":{"type":"integer","description":"Estimated time of arrival (ETA) for the process to complete in Unix time."}}}},"responses":{"BadRequestImage":{"description":"The request contains malformed data in the body, path, or query parameters.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"Unauthorized":{"description":"Authentication is required and has failed or has not yet been provided.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"PaymentRequired":{"description":"Payment is required to access the resource.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"Forbidden":{"description":"The API key doesn't have permissions to perform the request.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"PreconditionFailed":{"description":"The preconditions to process the request were not met.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"RequestEntityTooLarge":{"description":"The request is larger than the server is willing or able to process.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"UnsupportedMediaType":{"description":"The request entity has a media type which the server or resource does not support.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"UnprocessableEntity":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"TooEarly":{"description":"The request was sent too early to be processed. Please wait before retrying.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"TooManyRequests":{"description":"Too many requests hit the API too quickly. A backoff (e.g. exponential) is recommended for your requests.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}},"InternalServerError":{"description":"Unexpected error on our end.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"code":{"type":"integer","description":"The HTTP status code."},"message":{"type":"string","description":"A human readable error message."}}}}}}}},"paths":{"/enhance-gen/async":{"post":{"tags":["Enhance"],"summary":"Enhance Generative","operationId":"postEnhanceGen","description":"Returns `process_id` and `eta` to use as an efficient way to track the progress of the image enhancement job:\n  - Use the `Status` endpoints to check the status of this job using the returned `process_id`.\n  - Use the `Download` endpoints to download the input or processed image (once it is ready).\n  - Use the `Cancel` endpoint to cancel the job while it is in progress.\n\nThe same `process_id` and `eta` are also returned in the response headers as `X-Process-ID` and `X-ETA` respectively.\n\n> The `eta` represents when the job is expected to finish in Unix time. We recommend using this to know when you can expect your (bulk) jobs to finish processing.\n","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/EnhanceGenRequest"}}}},"responses":{"200":{"description":"Image processing request has been successfully created.","headers":{"X-Process-ID":{"description":"Unique identifier of the image processing job.","schema":{"type":"string"}},"X-Source-ID":{"description":"Unique identifier of the source image.","schema":{"type":"string"}},"X-ETA":{"description":"Estimated time of arrival (ETA) for the process to complete in Unix time.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncResponse"}}},"links":{"GetStatusByProcessId":{"description":"Retrieve the status of your image processing job using the `process_id`.","operationId":"getStatus","parameters":{"process_id":"$response.header.X-Process-ID"}},"DownloadInputByProcessId":{"description":"Access the download link for the input image once the job is completed.","operationId":"getDownloadInput","parameters":{"process_id":"$response.header.X-Process-ID"}},"DownloadOutputByProcessId":{"description":"Access the download link for the enhanced image once the job is completed.","operationId":"getDownloadOutput","parameters":{"process_id":"$response.header.X-Process-ID"}},"CancelByProcessId":{"description":"Cancel the image processing job if it is still in progress.","operationId":"cancelTask","parameters":{"process_id":"$response.header.X-Process-ID"}}}},"400":{"$ref":"#/components/responses/BadRequestImage"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"412":{"$ref":"#/components/responses/PreconditionFailed"},"413":{"$ref":"#/components/responses/RequestEntityTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"425":{"$ref":"#/components/responses/TooEarly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```