# Matting

Extract subjects from images using advanced AI matting technology. Generate alpha masks or segmentation maps to isolate objects from their backgrounds with precision.

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`
* `mode`
* `output_format`

Please see the reference for further details.

## Matting

> Returns \`process\_id\` and \`eta\` to use as an efficient way to track the progress of the image matting 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":"Matting","description":"Extract subjects from images using advanced AI matting technology. Generate alpha masks or segmentation maps to isolate objects from their backgrounds with precision.\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  - `mode`\n  - `output_format`\n\nPlease see the reference for further details.\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":{"MattingGANRequest":{"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":["Object"],"default":"Object"},"output_format":{"type":"string","description":"The desired format of the output image.","enum":["png"],"default":"png"},"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":{"/matting/async":{"post":{"tags":["Matting"],"summary":"Matting","operationId":"postMatting","description":"Returns `process_id` and `eta` to use as an efficient way to track the progress of the image matting 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/MattingGANRequest"}}}},"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 processed 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"}}}}}}
```