# Topaz Upscale Image Generative API

> Kaiwhakanuia taumira atahanga whakaputa me ngā tauira maha, te whakarei kanohi me te aratau Redefine e ārahina ana e te tohutohu

Ka whakanui i tētahi atahanga mai i te 1x ki te 4x mā te kōwhiringa `model`, tae atu ki Wonder 3.5, Wonder 3, Recover 3, Redefine, Recovery V2. Kei te whakarei kanohi ōna retireti kaha me te auahatanga. Mā Redefine e tāpiri he `prompt` ki te 1024 pūāhua, me `creativity`, `texture`, `sharpen`, `denoise`. He pai mō ngā pūtake iti, pōhewa rānei.

- Model id: `topaz/upscale/image/generative`
- Made by: Topaz Labs
- Category: Upscale
- Output: image
- Price per megapixel of your output image: from $0.01 / megapixel of output image (cheapest run $0.01 (10 API credits))
- Run: `POST https://api.doitong.ru/v1/run/topaz/upscale/image/generative`
- Quote: `POST https://api.doitong.ru/v1/quote/topaz/upscale/image/generative`
- Docs page: https://doitong.com/mi/developers/models/topaz/upscale/image/generative

## Pricing

Price: **from $0.01 / megapixel of output image** (the lowest tier; the quote prices your exact input). Price per megapixel of your output image: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

The full example input below costs $0.08 = 80 API credits (8 MP output image × $0.01).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.ru/v1/quote/topaz/upscale/image/generative` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `image_url` | `image` | string (image URL) | yes |  | ≥ 1 characters | URL atahanga pūtake mō te whakanuinga taumira. |
| `model` |  | enum (string) | no | `Wonder 3` | `Wonder 3.5`, `Wonder 3`, `Wonder 2`, `Wonder`, `Recover 3`, `Standard MAX`, `Redefine`, `Recovery V2`, `Recovery` | Kōwhiringa tauira whakanuinga whakaputa: ka hanga anō a Recovery me Recovery V2 i ngā atahanga taumira-iti rawa; ka whakamahi a Redefine i ngā tohutohu hei ārahi i ngā taipitopito auaha; ka aro a Standard MAX ki te tika me te kounga teitei; ka hanga anō a Recover 3 i ngā taipitopito māori. I roto i te whānau Wonder, ko Wonder me Wonder 2 kei mua i Wonder 3, te tauira whakaputa tino matatau mō te whakaahua-tūturu; ko te putanga hou, Wonder 3.5, he taipitopito pai ake, he iti ake te tukurua tauira. |
| `upscale_factor` |  | number | no | `2` | 1 – 4 | Whakarea whakarahinga atahanga; hei tauira, mā 2.0 ka rearua ngā ahunga e rua. |
| `crop_to_fill` |  | boolean | no | `false` |  |  |
| `output_format` |  | enum (string) | no | `jpeg` | `jpeg`, `png` | Hōputu mō te atahanga kua whakanuia. |
| `subject_detection` |  | enum (string) | no | `All` | `All`, `Foreground`, `Background` | Ka whakahaere me pēhea te kimi kaupapa ina whakarei atahanga ki Recovery V2, Wonder 3, Recovery rānei. |
| `face_enhancement` |  | boolean | no | `true` |  | Whakakā whakarei kanohi mō te atahanga. |
| `face_enhancement_creativity` |  | number | no | `0` | 0 – 1 | Mana auahatanga whakarei kanohi, ka hohe anake ina whakahohea te whakarei kanohi: whakaritea ki te 1.0 mō te auahatanga mōrahi, ki te 0.0 rānei mō te kore. |
| `face_enhancement_strength` |  | number | no | `0.8` | 0 – 1 | Mana kaha whakarei kanohi, ka hohe anake ina whakahohea te whakarei kanohi: whakaritea ki te 1.0 mō te whakarei mōrahi, ki te 0.0 rānei mō te kore. |
| `enhancement_strength` |  | enum (string) \| null | no |  | `low`, `medium`, `high` | Te kaha whakarei whakanuinga whakaputa; ka whirihora aunoa mēnā kāore i whakaritea. Ko ngā tauira tautoko ko Wonder 3.5 me Wonder 3. |
| `creativity` |  | integer \| null | no |  | 1 – 6 | Auahatanga whakanuinga whakaputa mai i te 1 ki te 6, e tautokona ana e Redefine anake. Mā te whakanui ka tāpiri taipitopito pohewa, pohewa-hē rānei. |
| `texture` |  | integer \| null | no |  | 1 – 5 | Mana taipitopito kakano motuhake mō te whakanuinga whakaputa a Redefine, e whakaae ana ki ngā taumata 1 ki te 5. |
| `prompt` |  | string \| null | no |  | ≤ 1024 characters | Kuputuhi aratohu mō te whakanuinga whakaputa, ka herea ki te 1024 pūāhua, ā, e tautokona ana e Redefine anake. |
| `autoprompt` |  | boolean \| null | no |  |  | Whakakā whakaputa tohutohu aunoa, e wātea ana mō te whakanuinga whakaputa a Redefine anake. |
| `sharpen` |  | number \| null | no |  | 0 – 1 | Kaha whakakoi mai i 0.0 ki te 1.0, e tautokona ana e Redefine anake. |
| `denoise` |  | number \| null | no |  | 0 – 1 | Kaha tango haruru mai i 0.0 ki te 1.0, e tautokona ana e Redefine anake. |
| `detail` |  | number \| null | no |  | 0 – 1 | Kaha whakaora taipitopito mai i 0.0 ki te 1.0, e tautokona ana e Recovery V2 anake. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Ka taea te whakangāwari i te tātari mā te tautuhi false, mēnā he mana tō te kaiwhakatuwhera. |

File parameters (`image`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "image": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

A fuller example:

```json
{
  "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.ru/v1/run/topaz/upscale/image/generative?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.ru/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.ru/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/topaz/upscale/image/generative?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/topaz/upscale/image/generative", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.ru/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "topaz/upscale/image/generative",
      "input": {
        "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "topaz/upscale/image/generative",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 80,
    "usd": "0.08",
    "charged": 80,
    "refunded": 0
  },
  "input": {
    "image_url": "https://content.doitong.com/images/showcase/v3/gen_fox_cartoon.jpg"
  },
  "output": {
    "image": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    }
  },
  "outputs": [
    {
      "type": "image",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "width": 1024,
      "height": 768,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `image` | object {url, content_type, file_name, file_size} | Te atahanga i whakaputaina mā te whakarahi. |

## Related models

- [Topaz Image Upscale](https://doitong.com/developers/models/topaz/upscale/image/precision.md) (`topaz/upscale/image/precision`): $0.08 / 24 megapixels of output image
- [Topaz Upscale Image Creative](https://doitong.com/developers/models/topaz/upscale/image/creative.md) (`topaz/upscale/image/creative`): $0.08 / 2 megapixels of output image
- [Topaz Upscale Image Transparent](https://doitong.com/developers/models/topaz/upscale/image/transparent.md) (`topaz/upscale/image/transparent`): $0.08 / 24 megapixels of output image
- [Topaz Video Upscale](https://doitong.com/developers/models/topaz/upscale/video/precision.md) (`topaz/upscale/video/precision`): from $0.00667 / second of input video
- [Topaz Upscale Video Creative](https://doitong.com/developers/models/topaz/upscale/video/creative.md) (`topaz/upscale/video/creative`): from $0.30 / second of input video
- [Topaz Upscale Video Generative](https://doitong.com/developers/models/topaz/upscale/video/generative.md) (`topaz/upscale/video/generative`): from $0.06 / second of input video
- [AuraSR](https://doitong.com/developers/models/aura-sr.md) (`aura-sr`): $0.001111 / second of processing time
- [Bria Increase Resolution](https://doitong.com/developers/models/bria/increase-resolution.md) (`bria/increase-resolution`): $0.04 / image

## Links

- HTML page: https://doitong.com/developers/models/topaz/upscale/image/generative
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=topaz/upscale/image/generative
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.ru/v1/models/topaz/upscale/image/generative