Name: Image Upscaler API: Clarity Upscaler by philz1337x
Brand: magicapi
SKU: api-magicapi-high-resolution-image-upscaler
Availability: InStock
Author: API Market

Shashank Agarwal

# 🔍 High-Resolution Image Upscaler API (philz1337x Clarity Upscaler)

## Overview
Clarity Upscaler is an image upscaler and enhancer published by philz1337x. Its developer describes it as a high resolution image upscaler and enhancer. It re-renders the image with a Stable Diffusion checkpoint, so it adds detail rather than only enlarging pixels.

Send an `image` URL and a `scale_factor` (default 2). A `prompt` steers the added detail, and `creativity` and `resemblance` balance new detail against faithfulness to the original. Each request returns a list with the URL of the upscaled image.

## Features
- **Upscaling**: `scale_factor` sets the enlargement (default 2).
- **Detail controls**: `creativity` (0 to 1, default 0.35; its developer suggests 0.3 to 0.9), `resemblance` (0 to 3, default 0.6; suggested 0.3 to 1.6) and `dynamic` for HDR (1 to 50, default 6; suggested 3 to 9).
- **Prompts**: `prompt` and `negative_prompt` steer the added detail. The default prompt includes the LoRA tags `<lora:more_details:0.5>` and `<lora:SDXLrender_v2.0:1>`.
- **Checkpoints and LoRAs**: choose `sd_model` from three checkpoints, name a `custom_sd_model`, or add LoRA files with `lora_links` (comma separated links).
- **Fractality**: `tiling_width` (default 112) and `tiling_height` (default 144) take values from 16 to 256 in steps of 16. Lower tiles give a higher fractality.
- **Hand fixing**: `handfix` can be `disabled` (default), `hands_only` or `image_and_hands`.
- **Masks**: `mask` takes an image that marks areas to preserve during upscaling.
- **Seamless patterns**: set `pattern` to `true` to upscale a tileable pattern.
- **Downscale first**: `downscaling` (default `false`) shrinks the input to `downscaling_resolution` (default 768) before upscaling, which its developer says can help large but low quality images.
- **Sharpening and output**: `sharpen` from 0 to 10 (default 0); `output_format` `png` (default), `jpg` or `webp`.

## Use Cases
1. **Product and listing photos**: enlarge small images for zoom views and print.
2. **AI-generated images and renders**: raise resolution and add fine detail before publishing.
3. **Textures and patterns**: upscale tileable textures with `pattern` set to `true`.
4. **Portraits with hands**: fix hands in generated images with `handfix`.

## Visual Examples
### Example Input
The request upscales this image 2x with the default settings written out in full:

![Clarity Upscaler example input: a low resolution image](https://blog.api.market/wp-content/uploads/2026/10/docs-027c520bd6ac-13_before-4.png)

```json
{
  "seed": 1337,
  "image": "https://blog.api.market/wp-content/uploads/2026/10/docs-027c520bd6ac-13_before-4.png",
  "prompt": "masterpiece, best quality, highres, <lora:more_details:0.5> <lora:SDXLrender_v2.0:1>",
  "dynamic": 6,
  "sd_model": "juggernaut_reborn.safetensors [338b85bc4f]",
  "scheduler": "DPM++ 3M SDE Karras",
  "creativity": 0.35,
  "lora_links": "",
  "downscaling": false,
  "resemblance": 0.6,
  "scale_factor": 2,
  "tiling_width": 112,
  "tiling_height": 144,
  "custom_sd_model": "",
  "negative_prompt": "(worst quality, low quality, normal quality:2) JuggernautNegative-neg",
  "num_inference_steps": 18,
  "downscaling_resolution": 768
}
```

### Example Output
![Clarity Upscaler example output: the image upscaled 2x with added detail](https://blog.api.market/wp-content/uploads/2026/10/clarity-upscaler-output-md990ysn-api-market.jpg)

The prediction returns `output` as a list containing the URL of the upscaled image, at twice the input's width and height (`scale_factor` 2).

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `image` | string (URL) | Yes |  |  | Image URL to upscale |
| `prompt` | string | No | `masterpiece, best quality, highres, <lora:more_details:0.5> <lora:SDXLrender_v2.0:1>` |  | Prompt that steers the detail added during upscaling |
| `negative_prompt` | string | No | `(worst quality, low quality, normal quality:2) JuggernautNegative-neg` |  | What to avoid in the added detail |
| `scale_factor` | number | No | `2` |  | Upscaling factor |
| `dynamic` | number | No | `6` | `1` to `50` | HDR, try from 3 to 9 |
| `creativity` | number | No | `0.35` | `0` to `1` | Creativity, try from 0.3 to 0.9 |
| `resemblance` | number | No | `0.6` | `0` to `3` | Resemblance to the input, try from 0.3 to 1.6 |
| `tiling_width` | integer | No | `112` | `16`, `32`, `48`, `64`, `80`, `96`, `112`, `128`, `144`, `160`, `176`, `192`, `208`, `224`, `240`, `256` | Fractality, set lower tile width for a high Fractality |
| `tiling_height` | integer | No | `144` | `16`, `32`, `48`, `64`, `80`, `96`, `112`, `128`, `144`, `160`, `176`, `192`, `208`, `224`, `240`, `256` | Fractality, set lower tile height for a high Fractality |
| `sd_model` | string | No | `juggernaut_reborn.safetensors [338b85bc4f]` | `epicrealism_naturalSinRC1VAE.safetensors [84d76a0328]`, `juggernaut_reborn.safetensors [338b85bc4f]`, `flat2DAnimerge_v45Sharp.safetensors` | Stable Diffusion model checkpoint |
| `scheduler` | string | No | `DPM++ 3M SDE Karras` | `DPM++ 2M Karras`, `DPM++ SDE Karras`, `DPM++ 2M SDE Exponential`, `DPM++ 2M SDE Karras`, `Euler a`, `Euler`, `LMS`, `Heun`, `DPM2`, `DPM2 a`, `DPM++ 2S a`, `DPM++ 2M`, `DPM++ SDE`, `DPM++ 2M SDE`, `DPM++ 2M SDE Heun`, `DPM++ 2M SDE Heun Karras`, `DPM++ 2M SDE Heun Exponential`, `DPM++ 3M SDE`, `DPM++ 3M SDE Karras`, `DPM++ 3M SDE Exponential`, `DPM fast`, `DPM adaptive`, `LMS Karras`, `DPM2 Karras`, `DPM2 a Karras`, `DPM++ 2S a Karras`, `Restart`, `DDIM`, `PLMS`, `UniPC` | Sampling scheduler |
| `num_inference_steps` | integer | No | `18` | `1` to `100` | Number of denoising steps |
| `seed` | integer | No | `1337` |  | Random seed. Leave blank to randomize the seed |
| `downscaling` | boolean | No | `false` |  | Downscale the image before upscaling. Can improve quality and speed for images with high resolution but lower quality |
| `downscaling_resolution` | integer | No | `768` |  | Downscaling resolution |
| `lora_links` | string | No | `""` |  | Link to a LoRA file to use in the upscaling. Multiple links are possible, separated by commas |
| `custom_sd_model` | string | No | `""` |  | Custom Stable Diffusion model. Leave empty to use `sd_model` |
| `sharpen` | number | No | `0` | `0` to `10` | Sharpen the image after upscaling. The higher the value, the more sharpening is applied. 0 for no sharpening |
| `mask` | string (URL) | No | none |  | Mask image to mark areas that should be preserved during upscaling |
| `handfix` | string | No | `disabled` | `disabled`, `hands_only`, `image_and_hands` | Fix hands in the image |
| `pattern` | boolean | No | `false` |  | Upscale a pattern with seamless tiling |
| `output_format` | string | No | `png` | `webp`, `jpg`, `png` | Format of the output image |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.02 per API unit.
- **1 API unit = 1 successful request covering up to 15 seconds of processing**; longer requests use one unit per started 15 seconds. For example, a request that takes 20 seconds of processing uses 2 units ($0.04).
- Processing time grows with the input size, `scale_factor` and `num_inference_steps`; the other settings do not change the price.
- **The example request** costs $0.02 when it finishes within 15 seconds of processing.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/high-resolution-image-upscaler`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/high-resolution-image-upscaler/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "dfad41707589d68ecdccd1dfa600d55a208f9310748e44bfe35b4a6291453d5e",
    "input": {
      "seed": 1337,
      "image": "https://blog.api.market/wp-content/uploads/2026/10/docs-027c520bd6ac-13_before-4.png",
      "prompt": "masterpiece, best quality, highres, <lora:more_details:0.5> <lora:SDXLrender_v2.0:1>",
      "dynamic": 6,
      "sd_model": "juggernaut_reborn.safetensors [338b85bc4f]",
      "scheduler": "DPM++ 3M SDE Karras",
      "creativity": 0.35,
      "lora_links": "",
      "downscaling": false,
      "resemblance": 0.6,
      "scale_factor": 2,
      "tiling_width": 112,
      "tiling_height": 144,
      "custom_sd_model": "",
      "negative_prompt": "(worst quality, low quality, normal quality:2) JuggernautNegative-neg",
      "num_inference_steps": 18,
      "downscaling_resolution": 768
    }
  }'
```

Response (201 Created):
```json
{
  "id": "md990ysn2srnc0d1c1tt04zha4",
  "version": "dfad41707589d68ecdccd1dfa600d55a208f9310748e44bfe35b4a6291453d5e",
  "status": "starting",
  "created_at": "2026-10-21T21:54:16.681Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/high-resolution-image-upscaler/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "md990ysn2srnc0d1c1tt04zha4",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/clarity-upscaler-output-md990ysn-api-market.jpg"
  ],
  "error": null,
  "created_at": "2026-10-21T21:54:16.681Z",
  "started_at": "2026-10-21T21:54:17.681Z",
  "completed_at": "2026-10-21T21:54:30.681Z"
}
```

`output` is a list of URLs containing the upscaled image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `image`, a `creativity` above 1 or a `tiling_width` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
Requests are rate limited to keep usage fair. If you receive a 429 response, wait and retry with exponential backoff.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/high-resolution-image-upscaler";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "dfad41707589d68ecdccd1dfa600d55a208f9310748e44bfe35b4a6291453d5e", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

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

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
    "seed": 1337,
    "image": "https://blog.api.market/wp-content/uploads/2026/10/docs-027c520bd6ac-13_before-4.png",
    "prompt": "masterpiece, best quality, highres, <lora:more_details:0.5> <lora:SDXLrender_v2.0:1>",
    "dynamic": 6,
    "sd_model": "juggernaut_reborn.safetensors [338b85bc4f]",
    "scheduler": "DPM++ 3M SDE Karras",
    "creativity": 0.35,
    "lora_links": "",
    "downscaling": false,
    "resemblance": 0.6,
    "scale_factor": 2,
    "tiling_width": 112,
    "tiling_height": 144,
    "custom_sd_model": "",
    "negative_prompt": "(worst quality, low quality, normal quality:2) JuggernautNegative-neg",
    "num_inference_steps": 18,
    "downscaling_resolution": 768
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/high-resolution-image-upscaler"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "dfad41707589d68ecdccd1dfa600d55a208f9310748e44bfe35b4a6291453d5e", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


print(create_and_wait_for_prediction({
    "seed": 1337,
    "image": "https://blog.api.market/wp-content/uploads/2026/10/docs-027c520bd6ac-13_before-4.png",
    "prompt": "masterpiece, best quality, highres, <lora:more_details:0.5> <lora:SDXLrender_v2.0:1>",
    "dynamic": 6,
    "sd_model": "juggernaut_reborn.safetensors [338b85bc4f]",
    "scheduler": "DPM++ 3M SDE Karras",
    "creativity": 0.35,
    "lora_links": "",
    "downscaling": False,
    "resemblance": 0.6,
    "scale_factor": 2,
    "tiling_width": 112,
    "tiling_height": 144,
    "custom_sd_model": "",
    "negative_prompt": "(worst quality, low quality, normal quality:2) JuggernautNegative-neg",
    "num_inference_steps": 18,
    "downscaling_resolution": 768
}))
```

## FAQ
- **How much larger is the output?**
  - The width and height are multiplied by `scale_factor`. The default is 2.
- **How do I keep the result closer to the original?**
  - Lower `creativity` and raise `resemblance`. Higher `creativity` adds more new detail.
- **Can I protect parts of the image?**
  - Yes. Pass a `mask` image that marks the areas to preserve during upscaling.
- **Why did a request use more than one unit?**
  - One unit covers up to 15 seconds of processing. Large inputs, a high `scale_factor` or many `num_inference_steps` take longer and use one more unit per started 15 seconds.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page.


Clarity Upscaler returns an upscaled image with added detail, plus adjustable scale, creativity and resemblance. Pay as you go on api.market.