> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Topaz Upscale - Image

> Use the powerful and accurate topaz image enhancer to enhance your images.

<Info>
  Pricing: **\$0.08/image**. Endpoint: `POST /v1/models/topaz/upscale/image/runs`.
</Info>

Use the powerful and accurate topaz image enhancer to enhance your images.

## Overview

* **Endpoint**: [https://api.runflow.io/v1/models/topaz/upscale/image/runs](https://api.runflow.io/v1/models/topaz/upscale/image/runs)
* **Model ID**: topaz/upscale/image
* **Provider**: Topaz Labs
* **License**: commercial
* **Last Updated**: 2026-04-08

## Pricing

* **Base price**: \$0.08/image
* **Note**: Up to 24MP

# Topaz Upscale - Image API

**Endpoint:** `POST /v1/models/topaz/upscale/image/runs`

## Run the model

### Python

```python theme={"dark"}
import requests

response = requests.post(
    "https://api.runflow.io/v1/models/topaz/upscale/image/runs",
    headers={"Authorization": "Bearer RUNFLOW_API_KEY"},
    json={
        "input": {
            "model": "Standard V2",
            "image_url": "https://public.runflow.io/images/models/photalabs/phota/example-output-0.webp",
            "autoprompt": True,
            "output_format": "png",
            "upscale_factor": 4,
            "face_enhancement": True,
            "subject_detection": "Foreground",
            "face_enhancement_strength": 0.8,
            "face_enhancement_creativity": 0.1
        },
        "callback_url": "https://your-server.com/webhook"
    },
)

data = response.json()
print(data)
```

### Node.js

```javascript theme={"dark"}
const response = await fetch(
  "https://api.runflow.io/v1/models/topaz/upscale/image/runs",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer RUNFLOW_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "input": {
            "model": "Standard V2",
            "image_url": "https://public.runflow.io/images/models/photalabs/phota/example-output-0.webp",
            "autoprompt": true,
            "output_format": "png",
            "upscale_factor": 4,
            "face_enhancement": true,
            "subject_detection": "Foreground",
            "face_enhancement_strength": 0.8,
            "face_enhancement_creativity": 0.1
        },
        "callback_url": "https://your-server.com/webhook"
    }),
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash theme={"dark"}
curl -X POST https://api.runflow.io/v1/models/topaz/upscale/image/runs \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
    "input": {
        "model": "Standard V2",
        "image_url": "https://public.runflow.io/images/models/photalabs/phota/example-output-0.webp",
        "autoprompt": true,
        "output_format": "png",
        "upscale_factor": 4,
        "face_enhancement": true,
        "subject_detection": "Foreground",
        "face_enhancement_strength": 0.8,
        "face_enhancement_creativity": 0.1
    },
    "callback_url": "https://your-server.com/webhook"
}
JSON
```

## Request parameters

| Parameter      | Type           | Required | Description                                                 |
| -------------- | -------------- | -------- | ----------------------------------------------------------- |
| `input`        | object         | required | Model input parameters. See "Input schema" below.           |
| `callback_url` | string \| null | optional | Webhook URL - POSTed when the run reaches a terminal state. |
| `metadata`     | object \| null | optional | Arbitrary key-value pairs attached to the run.              |

## Input schema

| Field                         | Type    | Required | Allowed values                                                                                                                                | Description                                                                                                                                |
| ----------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt`                      | string  | optional | Any                                                                                                                                           | Text prompt to guide generative upscaling (max 1024 chars). Applies to Redefine model only.                                                |
| `face_enhancement_creativity` | float   | optional | Any                                                                                                                                           | Creativity level for face enhancement. 0.0 means no creativity, 1.0 means maximum creativity. Ignored if face enhancement is disabled.     |
| `face_enhancement`            | boolean | optional | Any                                                                                                                                           | Whether to apply face enhancement to the image. Applies to standard enhance and Recovery V2 models.                                        |
| `model`                       | string  | optional | `Low Resolution V2`, `Standard V2`, `CGI`, `High Fidelity V2`, `Text Refine`, `Recovery`, `Redefine`, `Recovery V2`, `Standard MAX`, `Wonder` | Model to use for image enhancement.                                                                                                        |
| `crop_to_fill`                | boolean | optional | Any                                                                                                                                           |                                                                                                                                            |
| `upscale_factor`              | float   | optional | Any                                                                                                                                           | Factor to upscale the image by (e.g. 2.0 doubles width and height)                                                                         |
| `face_enhancement_strength`   | float   | optional | Any                                                                                                                                           | Strength of the face enhancement. 0.0 means no enhancement, 1.0 means maximum enhancement. Ignored if face enhancement is disabled.        |
| `sharpen`                     | float   | optional | Any                                                                                                                                           | Sharpening level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models.            |
| `detail`                      | float   | optional | Any                                                                                                                                           | Detail recovery level (0.0-1.0). Applies to Recovery V2 model only.                                                                        |
| `denoise`                     | float   | optional | Any                                                                                                                                           | Denoising level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models.             |
| `output_format`               | string  | optional | `jpeg`, `png`                                                                                                                                 | Output format of the upscaled image.                                                                                                       |
| `subject_detection`           | string  | optional | `All`, `Foreground`, `Background`                                                                                                             | Subject detection mode for the image enhancement. Applies to standard enhance and Recovery V2 models.                                      |
| `strength`                    | float   | optional | Any                                                                                                                                           | Enhancement strength (0.01-1.0). Applies to Text Refine model only.                                                                        |
| `texture`                     | integer | optional | Any                                                                                                                                           | Texture detail level for generative upscaling (1-5). Applies to Redefine model only.                                                       |
| `image_url`                   | image   | required | Any                                                                                                                                           | Url of the image to be upscaled                                                                                                            |
| `autoprompt`                  | boolean | optional | Any                                                                                                                                           | Enable automatic prompt generation for generative upscaling. Applies to Redefine model only.                                               |
| `creativity`                  | integer | optional | Any                                                                                                                                           | Creativity level for generative upscaling (1-6). Higher values produce more creative/hallucinated details. Applies to Redefine model only. |
| `fix_compression`             | float   | optional | Any                                                                                                                                           | Compression artifact removal level (0.0-1.0). Applies to Standard V2, Low Resolution V2, High Fidelity V2, and Text Refine models.         |

## Output schema

| Field           | Type | Description                                                                                      |
| --------------- | ---- | ------------------------------------------------------------------------------------------------ |
| `outputs`       | json | Unified output array - one entry per generated artifact with url/type/width/height/duration/etc. |
| `nsfw_detected` | json | true if the provider flagged output as NSFW, false if cleared, null if not checked.              |
| `seed`          | json | Deterministic seed used for generation, or null if the provider doesn't return one.              |
| `timing`        | json | Provider timing info (inference\_ms etc.), or null.                                              |

## Callback payload

When you provide a `callback_url`, Runflow POSTs to it once the run reaches a terminal state.

| Field          | Type           | Description                                                    |
| -------------- | -------------- | -------------------------------------------------------------- |
| `event`        | string         | Event type: "run.completed", "run.failed", or "run.cancelled". |
| `run_id`       | string         | The unique identifier of the run.                              |
| `status`       | string         | Terminal status: "succeeded", "failed", or "cancelled".        |
| `output`       | object \| null | The run output. Null if the run failed or was cancelled.       |
| `duration_ms`  | number \| null | Total run duration in milliseconds.                            |
| `created_at`   | string \| null | ISO 8601 timestamp when the run was created.                   |
| `completed_at` | string \| null | ISO 8601 timestamp when the run reached terminal state.        |
| `metadata`     | object \| null | The metadata object passed at run creation, if any.            |

* **Retries:** 3 attempts with exponential backoff (1s, 2s). Retries on 5xx / network errors only.
* **Headers:** `Runflow-Request-Id` is always sent. `Runflow-Signature` is sent if a signing secret is configured.

## Additional Resources

* [Playground](https://app.runflow.io/models/topaz/upscale/image)
* [API Reference](https://app.runflow.io/models/topaz/upscale/image?tab=api)
* [Documentation](https://docs.runflow.io)
* [OpenAPI](https://docs.runflow.io/api/openapi.public.json)

## Related

<CardGroup cols={2}>
  <Card title="Browse all models" icon="grid" href="/models">Browse the catalog.</Card>
  <Card title="Run lifecycle" icon="play" href="/concepts/runs">Callbacks, polling, statuses.</Card>
  <Card title="Callbacks" icon="webhook" href="/concepts/callbacks">Handle async results.</Card>
  <Card title="Pricing" icon="coin" href="/concepts/pricing">How requests bill out.</Card>
</CardGroup>