# Topaz Upscale Image Generative API

> 다양한 모델, 얼굴 개선 및 프롬프트 기반 Redefine 모드를 지원하는 생성형 이미지 업스케일러

Wonder 3.5, Wonder 3, Recover 3, Redefine 및 Recovery V2를 포함한 `model`을 선택해 이미지를 1x~4x로 업스케일합니다. 얼굴 개선에는 별도의 강도 및 창의성 슬라이더가 있습니다. Redefine은 최대 1024자의 `prompt`와 `creativity`, `texture`, `sharpen` 및 `denoise`를 추가합니다. 작거나 흐릿한 원본에 적합합니다.

- 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.com/v1/run/topaz/upscale/image/generative`
- Quote: `POST https://api.doitong.com/v1/quote/topaz/upscale/image/generative`
- Docs page: https://doitong.com/ko/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.com/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입니다. |
| `model` |  | enum (string) | no | `Wonder 3` | `Wonder 3.5`, `Wonder 3`, `Wonder 2`, `Wonder`, `Recover 3`, `Standard MAX`, `Redefine`, `Recovery V2`, `Recovery` | 생성형 업스케일링 모델 선택입니다. Recovery와 Recovery V2는 매우 낮은 해상도의 이미지를 재구성하고, Redefine은 프롬프트로 창의적 디테일을 유도하며, Standard MAX는 정밀도와 높은 품질을 우선하고, Recover 3는 자연스러운 디테일을 재구성합니다. Wonder 제품군에서는 Wonder와 Wonder 2가 가장 고급 생성형 사실성 모델인 Wonder 3보다 이전 버전입니다. 최신 릴리스인 Wonder 3.5는 패턴 반복을 줄이면서 더 세밀한 디테일을 제공합니다. |
| `upscale_factor` |  | number | no | `2` | 1 – 4 | 이미지 확대 배율입니다. 예를 들어 2.0은 두 치수를 모두 2배로 확대합니다. |
| `crop_to_fill` |  | boolean | no | `false` |  |  |
| `output_format` |  | enum (string) | no | `jpeg` | `jpeg`, `png` | 업스케일된 이미지에 사용할 형식입니다. |
| `subject_detection` |  | enum (string) | no | `All` | `All`, `Foreground`, `Background` | Recovery V2, Wonder 3 또는 Recovery로 이미지를 보정할 때 피사체를 감지하는 방식을 제어합니다. |
| `face_enhancement` |  | boolean | no | `true` |  | 이미지의 얼굴 보정 토글입니다. |
| `face_enhancement_creativity` |  | number | no | `0` | 0 – 1 | 얼굴 보정이 활성화된 경우에만 작동하는 얼굴 보정 창의성 제어입니다. 최대 창의성에는 1.0, 창의성 없음에는 0.0을 설정하세요. |
| `face_enhancement_strength` |  | number | no | `0.8` | 0 – 1 | 얼굴 보정이 활성화된 경우에만 작동하는 얼굴 보정 강도 제어입니다. 최대 보정에는 1.0, 보정 없음에는 0.0을 설정하세요. |
| `enhancement_strength` |  | enum (string) \| null | no |  | `low`, `medium`, `high` | 생성형 업스케일링 보정 강도입니다. 지정하지 않으면 자동으로 구성되며, Wonder 3.5와 Wonder 3에서 지원됩니다. |
| `creativity` |  | integer \| null | no |  | 1 – 6 | Redefine만 지원하는 1~6 범위의 생성형 업스케일링 창의성입니다. 값을 높이면 더 상상력이 풍부하거나 환각적인 디테일이 추가됩니다. |
| `texture` |  | integer \| null | no |  | 1 – 5 | Redefine의 생성형 업스케일링 전용 텍스처 디테일 제어로, 1~5 수준을 허용합니다. |
| `prompt` |  | string \| null | no |  | ≤ 1024 characters | 생성형 업스케일링 안내 텍스트입니다. 1024자로 제한되며 Redefine에서만 지원됩니다. |
| `autoprompt` |  | boolean \| null | no |  |  | Redefine의 생성형 업스케일링에서만 사용할 수 있는 자동 프롬프트 생성 토글입니다. |
| `sharpen` |  | number \| null | no |  | 0 – 1 | 0.0~1.0 범위의 선명화 강도이며 Redefine에서만 지원됩니다. |
| `denoise` |  | number \| null | no |  | 0 – 1 | 0.0~1.0 범위의 노이즈 제거 강도이며 Redefine에서만 지원됩니다. |
| `detail` |  | number \| null | no |  | 0 – 1 | 0.0~1.0 범위의 디테일 복원 강도이며 Recovery V2에서만 지원됩니다. |
| `enable_safety_checker` |  | boolean | no | `true` |  | 호출자에게 권한이 있으면 false로 설정해 검사를 완화할 수 있습니다. |

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.com/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.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/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.com/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.com/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.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `image` | object {url, content_type, file_name, file_size} | 업스케일링으로 생성된 이미지입니다. |

## 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.com/v1/models/topaz/upscale/image/generative