# Topaz Upscale Image Generative API

> Công cụ nâng cấp hình ảnh tạo sinh với nhiều mô hình, cải thiện khuôn mặt và chế độ Redefine được định hướng bằng lời nhắc

Nâng cấp ảnh từ 1x đến 4x với lựa chọn `model`, gồm Wonder 3.5, Wonder 3, Recover 3, Redefine và Recovery V2. Tăng cường khuôn mặt có các thanh trượt riêng cho cường độ và độ sáng tạo. Redefine thêm `prompt` tối đa 1024 ký tự cùng `creativity`, `texture`, `sharpen` và `denoise`. Phù hợp với nguồn ảnh nhỏ hoặc bị mờ.

- 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/vi/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 hình ảnh nguồn để nâng độ phân giải. |
| `model` |  | enum (string) | no | `Wonder 3` | `Wonder 3.5`, `Wonder 3`, `Wonder 2`, `Wonder`, `Recover 3`, `Standard MAX`, `Redefine`, `Recovery V2`, `Recovery` | Lựa chọn mô hình nâng độ phân giải tạo sinh: Recovery và Recovery V2 tái tạo hình ảnh có độ phân giải cực thấp; Redefine dùng lời nhắc để định hướng chi tiết sáng tạo; Standard MAX ưu tiên độ chính xác và chất lượng cao; Recover 3 tái tạo chi tiết tự nhiên. Trong dòng mô hình Wonder, Wonder và Wonder 2 ra mắt trước Wonder 3, mô hình tạo sinh chân thực tiên tiến nhất; bản phát hành mới nhất Wonder 3.5 cung cấp chi tiết tinh hơn với ít lặp lại họa tiết hơn. |
| `upscale_factor` |  | number | no | `2` | 1 – 4 | Hệ số phóng to hình ảnh; ví dụ, 2.0 tăng gấp đôi cả hai kích thước. |
| `crop_to_fill` |  | boolean | no | `false` |  |  |
| `output_format` |  | enum (string) | no | `jpeg` | `jpeg`, `png` | Định dạng dùng cho hình ảnh đã nâng độ phân giải. |
| `subject_detection` |  | enum (string) | no | `All` | `All`, `Foreground`, `Background` | Kiểm soát cách phát hiện chủ thể khi nâng cao hình ảnh bằng Recovery V2, Wonder 3 hoặc Recovery. |
| `face_enhancement` |  | boolean | no | `true` |  | Nút bật/tắt nâng cao khuôn mặt cho hình ảnh. |
| `face_enhancement_creativity` |  | number | no | `0` | 0 – 1 | Điều khiển độ sáng tạo khi nâng cao khuôn mặt, chỉ hoạt động khi tính năng nâng cao khuôn mặt được bật: đặt 1.0 để đạt độ sáng tạo tối đa hoặc 0.0 để tắt. |
| `face_enhancement_strength` |  | number | no | `0.8` | 0 – 1 | Điều khiển cường độ nâng cao khuôn mặt, chỉ hoạt động khi tính năng nâng cao khuôn mặt được bật: đặt 1.0 để nâng cao tối đa hoặc 0.0 để tắt. |
| `enhancement_strength` |  | enum (string) \| null | no |  | `low`, `medium`, `high` | Cường độ nâng cao khi nâng độ phân giải tạo sinh, được tự động cấu hình nếu không chỉ định; các mô hình được hỗ trợ là Wonder 3.5 và Wonder 3. |
| `creativity` |  | integer \| null | no |  | 1 – 6 | Độ sáng tạo khi nâng độ phân giải tạo sinh, từ 1 đến 6, chỉ được Redefine hỗ trợ. Tăng giá trị này sẽ thêm nhiều chi tiết giàu tưởng tượng hoặc do mô hình suy diễn. |
| `texture` |  | integer \| null | no |  | 1 – 5 | Điều khiển chi tiết kết cấu dành riêng cho tính năng nâng độ phân giải tạo sinh của Redefine, chấp nhận các mức từ 1 đến 5. |
| `prompt` |  | string \| null | no |  | ≤ 1024 characters | Văn bản hướng dẫn nâng độ phân giải tạo sinh, giới hạn ở 1024 ký tự và chỉ được Redefine hỗ trợ. |
| `autoprompt` |  | boolean \| null | no |  |  | Nút bật/tắt tạo lời nhắc tự động, chỉ có trong tính năng nâng độ phân giải tạo sinh của Redefine. |
| `sharpen` |  | number \| null | no |  | 0 – 1 | Cường độ làm sắc nét từ 0.0 đến 1.0, chỉ được Redefine hỗ trợ. |
| `denoise` |  | number \| null | no |  | 0 – 1 | Cường độ khử nhiễu từ 0.0 đến 1.0, chỉ được Redefine hỗ trợ. |
| `detail` |  | number \| null | no |  | 0 – 1 | Cường độ phục hồi chi tiết từ 0.0 đến 1.0, chỉ được Recovery V2 hỗ trợ. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Có thể nới lỏng việc kiểm duyệt bằng cách đặt thành false, nếu người gọi được cấp quyền. |

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} | Hình ảnh được tạo bằng cách phóng to. |

## 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