# Topaz Image Upscale

> Image upscaling and enhancement with Topaz AI — Standard, Hi-Fi, CGI, Recovery and Wonder models.

## Overview

- **Model ID**: `topaz-upscale-image`
- **Workflow**: `topaz/upscale/image`
- **Provider**: Topaz
- **Origin**: Partner Model
- **Category**: Image → Image (image)
- **Output**: One or more image URLs.
- **Tags**: upscale, image required
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/topaz/upscale/image/execute` (vendor's own parameters)
- **Execution**: sync (`/execute`) returns the result in one call; async is also available
- **Model page**: https://picsart.com/api-platform/models/topaz-upscale-image

## Pricing

Live pricing for this model is not published yet. See https://picsart.com/pricing/ or the Pricing tab of the model page (https://picsart.com/api-platform/models/topaz-upscale-image#pricing).

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK (TypeScript)** — `@picsart/ai-sdk` (Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **SDK (Python)** — `picsart-ai-sdk` (Python 3.10+, async). The same surface in snake_case: `await ai.generate()` / `await ai.generate_text()`, with a typed input per model.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK (TypeScript)
pip install picsart-ai-sdk       # SDK (Python)
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('topaz-upscale-image', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

### Input parameters

- **`imageUrls`** (`list<string>`, _required_): Input images, as URLs: the image to edit, or references for subject, style or composition.
  - Accepts: image URLs (max 1)
- **`model`** (`string`, _optional_): Model
  - Default: `"Standard V2"`
  - Options: `Standard V2`, `Standard MAX`, `Low Resolution V2`, `High Fidelity V2`, `CGI`, `Text Refine`, `Redefine`, `Recovery`, `Recovery V2`, `Wonder`, `Wonder 3`

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "imageUrls"
  ],
  "properties": {
    "imageUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "image URL"
      },
      "maxItems": 1,
      "description": "Input images, as URLs: the image to edit, or references for subject, style or composition."
    },
    "model": {
      "type": "string",
      "enum": [
        "Standard V2",
        "Standard MAX",
        "Low Resolution V2",
        "High Fidelity V2",
        "CGI",
        "Text Refine",
        "Redefine",
        "Recovery",
        "Recovery V2",
        "Wonder",
        "Wonder 3"
      ],
      "default": "Standard V2",
      "description": "Model"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "topaz-upscale-image",
    "params": {
      "imageUrls": [
        "https://cdn.example.com/input.jpg"
      ]
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Asset models return `url` plus an `items` array of results.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "url": "https://cdn.picsart.com/…/result",
      "items": [
        {
          "url": "https://cdn.picsart.com/…/result"
        }
      ],
      "model": "topaz-upscale-image"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "items": [
    {
      "url": "https://cdn.picsart.com/…/result"
    }
  ],
  "model": "topaz-upscale-image"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const result = await ai.generate('topaz-upscale-image', {
  imageUrls: [
    "https://cdn.example.com/input.jpg"
  ]
});

console.log(result.url); // image URL
```

#### Python (SDK)

```python
import asyncio
import os

from picsart_ai_sdk import create_client


async def main() -> None:
    async with create_client(
        api_key=os.environ["PICSART_API_KEY"],
        api_url="https://api.picsart.com",
    ) as ai:
        result = await ai.generate("topaz-upscale-image", {
            "imageUrls": [
                "https://cdn.example.com/input.jpg",
            ],
        })

        print(result.url)  # image URL


asyncio.run(main())
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "topaz-upscale-image",
    "params": {
      "imageUrls": [
        "https://cdn.example.com/input.jpg"
      ]
    }
  }
}'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info topaz-upscale-image  # this model's parameters
gen-ai pricing topaz-upscale-image  # quote before spending credits
gen-ai generate -m topaz-upscale-image \
  -i ./input.jpg
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `topaz/upscale/image` workflow takes Topaz's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/topaz/upscale/image/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('topaz/upscale/image', params, { mode })` in TypeScript, `ai.apis.run("topaz/upscale/image", params, mode=…)` in Python — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `crop_to_fill` | `boolean` | no | `false` | — |
| `fix_compression` | `number` | no | — | Compression artifact removal level (0.0-1.0). Applies to Standard V2, Low Resolution V2, High Fidelity V2, and Text Refine models. · 0–1 |
| `sharpen` | `number` | no | — | Sharpening level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models. · 0–1 |
| `creativity` | `integer` | no | — | Creativity level for generative upscaling (1-6). Higher values produce more creative/hallucinated details. Applies to Redefine model only. · 1–6 |
| `image_url` | `string` | yes | — | Url of the image to be upscaled · min 1 chars · e.g. `https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg` |
| `face_enhancement` | `boolean` | no | `true` | Whether to apply face enhancement to the image. Applies to standard enhance and Recovery V2 models. |
| `face_enhancement_creativity` | `number` | no | `0` | Creativity level for face enhancement. 0.0 means no creativity, 1.0 means maximum creativity. Ignored if face enhancement is disabled. · 0–1 |
| `strength` | `number` | no | — | Enhancement strength (0.01-1.0). Applies to Text Refine model only. · 0.01–1 |
| `model` | `string` | no | `Standard V2` | Model to use for image enhancement, grouped by family. Precision — Standard V2 fits most photos, High Fidelity V2 preserves detail in professional shots, Low Resolution V2 recovers compressed sources, CGI targets art and rendered graphics, Text Refine keeps text and shapes crisp. Generative — Wonder 3 is Topaz's most advanced generative model, Redefine adds prompt-guided creative detail, Standard MAX maximizes quality, Recovery/Recovery V2 rebuild extreme low-resolution images. · Options: `Standard V2`, `High Fidelity V2`, `Low Resolution V2`, `CGI`, `Text Refine`, `Wonder 3`, `Wonder`, `Standard MAX`, `Redefine`, `Recovery V2`, `Recovery` |
| `denoise` | `number` | no | — | Denoising level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models. · 0–1 |
| `enhancement_strength` | `string` | no | — | Enhancement strength for generative upscaling. Applies to Wonder 3 model only. When omitted, Topaz auto-configures it. · Options: `low`, `medium`, `high` |
| `detail` | `number` | no | — | Detail recovery level (0.0-1.0). Applies to Recovery V2 model only. · 0–1 |
| `enable_safety_checker` | `boolean` | no | `true` | Authorized callers may set false to request relaxed screening. |
| `output_format` | `string` | no | `jpeg` | Output format of the upscaled image. · Options: `jpeg`, `png` |
| `upscale_factor` | `number` | no | `2` | Factor to upscale the image by (e.g. 2.0 doubles width and height) · 1–4 |
| `subject_detection` | `string` | no | `All` | Subject detection mode for the image enhancement. Applies to standard enhance and Recovery V2 models. · Options: `All`, `Foreground`, `Background` |
| `autoprompt` | `boolean` | no | — | Enable automatic prompt generation for generative upscaling. Applies to Redefine model only. |
| `texture` | `integer` | no | — | Texture detail level for generative upscaling (1-5). Applies to Redefine model only. · 1–5 |
| `prompt` | `string` | no | — | Text prompt to guide generative upscaling (max 1024 chars). Applies to Redefine model only. · max 1024 chars |
| `face_enhancement_strength` | `number` | no | `0.8` | Strength of the face enhancement. 0.0 means no enhancement, 1.0 means maximum enhancement. Ignored if face enhancement is disabled. · 0–1 |
| `options` | `object` | no | — | Platform-specific options for safety checks and Picsart Drive integration. |
| └ `safety_checks` | `object` | no | — | Safety check configuration. |
| └   `enabled` | `boolean` | no | `true` | Enable or disable text safety checks. Defaults to true. |
| └ `drive` | `object` | no | — | Picsart Drive storage options. When provided, the result will be saved to the user's Drive. |
| └   `name` | `string` | yes | — | Filename to save the result as in Picsart Drive. |
| └   `attributes` | `object` | no | — | Additional file metadata attributes. |
| └   `folder` | `object` | no | — | Destination folder in Picsart Drive. |

### Example request body

```json
{
  "params": {
    "image_url": "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg",
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'topaz/upscale/image' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('topaz/upscale/image', {
  image_url: "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg",
  prompt: "A serene mountain lake at golden hour, ultra detailed"
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### Python (`ai.apis.run`)

```python
import asyncio
import os

from picsart_ai_sdk import ApiRunMode, create_client


async def main() -> None:
    async with create_client(
        api_key=os.environ["PICSART_API_KEY"],
        api_url="https://api.picsart.com",
    ) as ai:
        # Calls the 'topaz/upscale/image' workflow directly — params are sent as-is.
        response = await ai.apis.run("topaz/upscale/image", {
            "image_url": "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg",
            "prompt": "A serene mountain lake at golden hour, ultra detailed",
        }, mode=ApiRunMode.SYNC)

        print(response["result"])  # workflow-specific output
        print((response.get("usage") or {}).get("credits"))  # amount charged, in $


asyncio.run(main())
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/topaz/upscale/image/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "image_url": "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg",
    "prompt": "A serene mountain lake at golden hour, ultra detailed"
  }
}'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "id": "wf_abc123",
    "status": "COMPLETED",
    "result": {
      "image": {
        "file_size": 4404019,
        "file_name": "z9RV14K95DvU.png",
        "url": "https://cdn.picsart.com/…/result.jpg",
        "content_type": "image/png"
      }
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "image": {
      "file_size": 4404019,
      "file_name": "z9RV14K95DvU.png",
      "url": "https://cdn.picsart.com/…/result.jpg",
      "content_type": "image/png"
    }
  }
}
```

## Additional resources

- Model page (playground): https://picsart.com/api-platform/models/topaz-upscale-image
- SDK and REST API (unified): https://picsart.com/api-platform/models/topaz-upscale-image#api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/topaz-upscale-image#advanced
- Pricing: https://picsart.com/api-platform/models/topaz-upscale-image#pricing
- This document: https://picsart.com/api-platform/models/topaz-upscale-image/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction