> For the complete documentation index, see [llms.txt](https://developer.topazlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.topazlabs.com/getting-started/request-parameters/image.md).

# Image

Find the request-level parameters for all image endpoints

All image processing endpoints are `POST` requests to `https://api.topazlabs.com/image/v1/...` with a `multipart/form-data` body. Every endpoint accepts the common parameters. Three endpoints also accept output size parameters.

| Endpoint             | Common Parameters | Output Size Parameters | Output Formats                |
| -------------------- | ----------------- | ---------------------- | ----------------------------- |
| `/enhance/async`     | ✓                 | ✓                      | `jpeg`, `png`, `tiff`         |
| `/enhance-gen/async` | ✓                 | ✓                      | `jpeg`, `png`, `tiff`         |
| `/sharpen/async`     | ✓                 | —                      | `jpeg`, `png`, `tiff`         |
| `/sharpen-gen/async` | ✓                 | —                      | `jpeg`, `png`, `tiff`         |
| `/denoise/async`     | ✓                 | —                      | `jpeg`, `png`, `tiff`         |
| `/denoise-gen/async` | ✓                 | —                      | `jpeg`, `png`, `tiff`         |
| `/restore-gen/async` | ✓                 | —                      | `jpeg`, `png`, `tiff`         |
| `/lighting/async`    | ✓                 | —                      | `jpeg`, `png`, `tiff`         |
| `/matting/async`     | ✓                 | —                      | `png` only                    |
| `/tool/async`        | ✓                 | ✓                      | `png` only (`png` input only) |

## Common Parameters

Accepted by every image endpoint. Provide the source image with exactly one of `image`, `sourceId`, or `sourceUrl`; send only one per request.

| Parameter      | Type     | Required / Default                                        | Accepted values                     | Description                                                                                                                                                                                             |
| -------------- | -------- | --------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`        | `file`   | Optional                                                  | `jpeg`, `jpg`, `png`, `tiff`, `tif` | The image file to process. Required unless you send `sourceId` or `sourceUrl`.                                                                                                                          |
| `sourceId`     | `string` | Optional                                                  | —                                   | ID of an image you've already uploaded, returned as `source_id` by a previous request. Reuse it to run another model on the same image without uploading it again.                                      |
| `sourceUrl`    | `string` | Optional                                                  | —                                   | Publicly reachable URL of the source image.                                                                                                                                                             |
| `model`        | `string` | <p>Optional<br>Default: <code>endpoint default</code></p> | —                                   | The model to run. Each endpoint has a default model, used when `model` is omitted. Accepted values for each endpoint are listed on the family pages, and each model page shows its exact `model` value. |
| `outputFormat` | `string` | <p>Optional<br>Default: <code>jpeg</code></p>             | `jpeg`, `jpg`, `png`, `tiff`, `tif` | Format of the output image. `/matting/async` and `/tool/async` always return `png`.                                                                                                                     |
| `webhookUrl`   | `string` | Optional                                                  | —                                   | URL we `POST` a JSON notification to whenever the job's status changes or completes.                                                                                                                    |

## Output Size Parameters

Accepted by `/enhance/async`, `/enhance-gen/async`, and `/tool/async`. If you set only one dimension, the other scales to keep the aspect ratio. If you set neither, the model's default scale is used.

| Parameter      | Type      | Required / Default                             | Accepted values | Description                                                                                                                        |
| -------------- | --------- | ---------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `outputWidth`  | `integer` | Optional                                       | `1` to `32000`  | Output width in pixels.                                                                                                            |
| `outputHeight` | `integer` | Optional                                       | `1` to `32000`  | Output height in pixels.                                                                                                           |
| `cropToFill`   | `boolean` | <p>Optional<br>Default: <code>false</code></p> | —               | When both dimensions are set and their aspect ratio differs from the source, crop the output to fill them instead of letterboxing. |

## Model Parameters

Model-specific settings are sent as additional form fields in the same request, in camelCase, for example `-F "sharpenStrength=0.5"`. They're listed on each model's page. Any setting you don't send uses the model's default.

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://api.topazlabs.com/image/v1/enhance-gen/async" \
  -H "X-API-Key: $TOPAZ_API_KEY" \
  -F "image=@photo.jpg" \
  -F "model=Wonder 3.5" \
  -F "outputWidth=3840" \
  -F "outputFormat=png" \
  -F "webhookUrl=https://example.com/topaz-webhook"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import fs from 'node:fs';
import FormData from 'form-data';

const form = new FormData();
form.append('image', fs.createReadStream('photo.jpg'));
form.append('model', 'Wonder 3.5');
form.append('outputWidth', '3840');
form.append('outputFormat', 'png');
form.append('webhookUrl', 'https://example.com/topaz-webhook');

const response = await fetch(
  'https://api.topazlabs.com/image/v1/enhance-gen/async',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.TOPAZ_API_KEY,
      ...form.getHeaders(),
    },
    body: form,
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

console.log(await response.json());
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

with open("photo.jpg", "rb") as image:
    response = requests.post(
        "https://api.topazlabs.com/image/v1/enhance-gen/async",
        headers={"X-API-Key": os.environ["TOPAZ_API_KEY"]},
        data={
            "model": "Wonder 3.5",
            "outputWidth": 3840,
            "outputFormat": "png",
            "webhookUrl": "https://example.com/topaz-webhook"
        },
        files={"image": image}
    )

response.raise_for_status()
print(response.json())
```

{% endtab %}
{% endtabs %}

The response returns `process_id`, `source_id`, and `eta` (also sent as the `X-Process-ID`, `X-Source-ID`, and `X-ETA` headers). Poll `GET /status/{process_id}` and download the result from `GET /download/{process_id}`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.topazlabs.com/getting-started/request-parameters/image.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.