# Upscale images

> Enlarge one image 2x or 4x, up to 4096x4096, for a flat price per effort. No model or prompt to choose.

> **Note**
>
> Upscaling is in beta. The request shape is settled, but the models behind each effort may change
> as we see real traffic.

`POST /image/upscale` takes one image URL and returns it larger. There is no
`model` field and no prompt. You pick a size and an effort, and Mynth picks
the model.

**SDK**

```ts
import Mynth from "@mynthio/sdk";

const mynth = new Mynth();

const upscaled = await mynth.image.upscale({
  url: "https://cdn.example.com/product.jpg",
  size: "2x",
  effort: "low",
});

console.log(upscaled.image.url);
```

**CLI**

```bash
npx @mynthio/cli image upscale https://cdn.example.com/product.jpg --size 2x --effort low -o ./out
```

**REST**

```bash
curl https://api.mynth.io/image/upscale \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://cdn.example.com/product.jpg","size":"2x","effort":"low"}'
```

## Fields

| Field           | Notes                                                                          |
| --------------- | ------------------------------------------------------------------------------ |
| `url`           | Required. A public http(s) image URL                                           |
| `size`          | Required. `"2x"` or `"4x"`, or `{ "type": "scale", "factor": 2 }` with 2 or 4  |
| `effort`        | Required. `"low"` or `"high"`. It sets the price, so there is no default       |
| `output.format` | `png`, `jpg`, or `webp`. Omit it for the provider's format                     |
| `destination`   | A destination name. See [destinations](https://mynth.io/docs/concepts/destinations.md)            |
| `webhook`       | Per-request URLs. See [webhooks](https://mynth.io/docs/concepts/webhooks.md#per-request-webhooks) |
| `metadata`      | A JSON object up to 2048 bytes                                                 |
| `access`        | `{ "pat": { "enabled": false } }` skips the browser token                      |

For a local file, pass `file` instead of `url` in the SDK, or a path in the
CLI. Both upload it first. The CLI takes `--size 2x` or `--size 4x` only.

## Pick an effort

| `effort` | Good for                                                                   | Price |
| -------- | -------------------------------------------------------------------------- | ----- |
| `low`    | Fast and sharp. Product shots, generated images, anything already clean    | $0.03 |
| `high`   | Rebuilds fine detail: small text, skin, fur, leaves, soft or damaged input | $0.15 |

> **Warning**
>
> `high` can rebuild faces on old or damaged photos, which can change a person's likeness. Use `low`
> when the face must stay exactly as it is.

## Size limit

The upscaled image can be at most 4096x4096 pixels (16.8 MP), counted in
pixels rather than per side. That means:

- `2x` takes images up to about 4.2 MP, such as 2048x2048 or 1600x2600.
- `4x` takes images up to about 1 MP, such as 1024x1024 or 800x1300.

A larger request is accepted at create, then fails with `OUTPUT_TOO_LARGE`
before any work starts. It is not charged.

The result comes back at whatever size the provider returns, which can be a
few pixels off the source times the factor. Read `size` for the real
dimensions.

## What comes back

```json
{
  "image": {
    "id": "img_Hn4cW8pLx2RsT6vYb0QjM9kE3dAf7ZuG",
    "url": "https://cdn.mynth.io/images/img_Hn4cW8pLx2RsT6vYb0QjM9kE3dAf7ZuG.png",
    "mynth_url": "https://cdn.mynth.io/images/img_Hn4cW8pLx2RsT6vYb0QjM9kE3dAf7ZuG.png",
    "size": "3072x4608",
    "format": "png"
  }
}
```

There is one image and no per-item status. If the work fails, the task is
`failed`. With a destination, `image` also carries a `destination` block that
says whether the upload worked. See
[destinations](https://mynth.io/docs/concepts/destinations.md#what-comes-back).

The create response includes a `pat_` token, so a browser can poll this task
the same way it polls a generation. See
[poll for results](https://mynth.io/docs/guides/poll-for-results.md#from-a-browser).

## Price

$0.03 for `low` and $0.15 for `high`, per image, whatever the `size`. The
price is held at create and charged when the task succeeds. See
[pricing](https://mynth.io/docs/pricing.md#tool-prices).

## Next steps

- [Remove background](https://mynth.io/docs/guides/remove-background.md): cut the subject out first, then upscale.
- [Destinations](https://mynth.io/docs/concepts/destinations.md): write the result to your own storage.