---
title: "AI Image Upscaler"
method: POST
path: "/v1/ai-image-upscaler"
tags: ["Image Projects"]
---

# AI Image Upscaler

`POST /v1/ai-image-upscaler`

Upscale your image using AI. Each 2x upscale costs 50 credits for balanced/creative modes, and 25 credits for preserve. 4x upscale costs 200 and 100 credits respectively.

## Request body

- object
  - `name` string — Give your image a custom name for easy identification.
  - `scale_factor` number, required — How much to scale the image. Must be either 2 or 4. Note: 4x upscale is only available on Creator, Pro, or Business tier.
  - `style` object — Style settings for the upscale. Use `mode` (`"preserve"`, `"balanced"`, or `"creative"`). Defaults to `"balanced"`.
    - `mode` 'pro' | 'preserve' | 'balanced' | 'creative' — The upscaling mode. `"preserve"` uses the fast pro pipeline (1× credit multiplier). `"balanced"` and `"creative"` use the creative pipeline (2× credit multiplier). `"pro"` is deprecated and maps to `"preserve"`. Defaults to `"balanced"`.
    - `prompt` string — A prompt to guide the final image. Only used when mode is `creative`.
  - `assets` object, required — Provide the assets for upscaling
    - `image_file_path` string, required — The image to upscale. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls). See the [file upload guide](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) for details. . The maximum input image size is 4096x4096px.

## Response `200`

Success

- object — Success
  - `id` string, required — Unique ID of the image. Use it with the [Get image Project API](https://docs.magichour.ai/api-reference/image-projects/get-image-details) to fetch status and downloads.
  - `credits_charged` integer, required — The amount of credits deducted from your account to generate the image. We charge credits right when the request is made. If an error occurred while generating the image(s), credits will be refunded and this field will be updated to include the refund.

## Other responses

- `400` — Invalid Request
- `401` — Unauthorized
- `402` — Payment Required
- `404` — Not Found
- `422` — Unprocessable Entity
- `500` — Internal Server Error

## Changes

- **2026-09-02** `9aeb9397c62a` — 8 info
  - added the non-success response with the status `500`
  - removed the `Not Found` enum value from the `message` response property for the response status `404`
  - removed the `Unauthorized` enum value from the `message` response property for the response status `401`
  - added the required property `code` to the response with the `400` status
  - …4 more
- **2026-07-15** `83f2dc10312e` — 1 warning, 2 info
  - removed the request property `style/enhancement`
  - the `style` request property default value `{}` was added
  - the `mode` request property default value `balanced` was removed
- **2026-07-14** `c71f647a7794` — 5 info
  - the request property `style` became optional
  - the `mode` request property default value `balanced` was added
  - request property `style/enhancement` deprecated
  - added the new `balanced` enum value to the request property `style/mode`
  - …1 more
- **2026-06-05** `19fc042442ba` — 2 info
  - added the new optional request property `style/mode`
  - the request property `style/enhancement` became optional
- **2026-03-06** `1f72d520ddc6` — 1 info
  - added the non-success response with the status `402`

[Full history](https://skmtc.dev/magichourhq/apis/magic-hour-api/changes/v1/ai-image-upscaler/post.md)

---

[API](https://skmtc.dev/magichourhq/apis/magic-hour-api.md) · [All operations](https://skmtc.dev/magichourhq/apis/magic-hour-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magichourhq/apis/magic-hour-api/revisions/6e3bb11fd050?raw)