# AI Image Upscaler & Photo Restoration – Face Enhance, 2x/4x (`gazidev/image-upscaler`) Actor Upscale and restore photos 2x-4x with Real-ESRGAN AI plus GFPGAN face restoration: fix old, blurry or low-res pictures, sharpen faces, product shots and anime art. Bulk URLs, JPG/PNG/WebP. From $0.005 per image, no GPU or subscription. - **URL**: https://apify.com/gazidev/image-upscaler.md - **Developed by:** [Cemal Atakli](https://apify.com/gazidev) (community) - **Categories:** AI, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 image upscaleds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## AI Image Upscaler & Photo Restoration – Face Enhance, 2x / 3x / 4x Upscale, sharpen and **restore photos in bulk**: Real-ESRGAN super-resolution for the whole image plus **GFPGAN AI face restoration** for portraits, old family photos and blurry selfies. Paste image URLs (or chain a dataset from any scraper) and get 2x, 3x or 4x larger, cleaner images back as JPG, PNG or WebP files with direct download links. - **Old, blurry or low-res photos**: the `general` model (realesr-general-x4v3) restores detail and removes JPEG artefacts and scan noise, with an adjustable **denoise strength**. - **Face restoration (new)**: faces are detected automatically and rebuilt with GFPGAN v1.4: sharper eyes, skin, teeth and hair. Black-and-white photos stay black-and-white. Images without faces cost nothing extra. - **Anime, cartoons, illustrations, logos**: the `anime` model keeps lines crisp and colours flat. - **Transparency kept**: PNG/WebP with alpha stay transparent. - **Bulk & automation friendly**: lists, CSV, Google Sheets, or `datasetId` from another Actor; API, schedules, webhooks, Make/Zapier/n8n. - **Pay per image, no GPU, no subscription, no desktop app**: an API alternative to desktop photo-enhancer tools. Failed downloads and invalid files are never charged. ### What it costs | Event | Price | When | |---|---|---| | `image-upscaled` | **$0.005** | per successfully upscaled image, includes up to **0.25 MP of input** (e.g. 500×500 px → 2000×2000 output) | | `extra-input-block` | **$0.003** | per additional started 0.25 MP of input | | `face-restored` | **$0.008** | per face restored (only when `faceEnhance` is on and a face was found; up to `maxFaces` per image) | Examples: 400×400 thumbnail → $0.005 · old 700×460 portrait with 2 faces → $0.005 + $0.003 (1 extra block) + $0.016 (2 faces) = $0.024 · 800×600 photo (0.48 MP) → $0.008 · 1000×1000 (1 MP) → $0.014 · 1920×1080 (2.07 MP) → $0.029. Errors and skipped images are free. Set **Max input size** to guard your budget; the run also stops cleanly at your *maximum cost per run*. ### Input | Field | Default | Notes | |---|---|---| | `imageUrls` | – | Direct image links (JPEG, PNG, WebP, HEIC, AVIF, TIFF, GIF, BMP) | | `bulkText` / `sourceFileUrl` / `datasetId` | – | Bulk sources (one URL per line, CSV with a `url` column, or another dataset) | | `scale` | `4` | `2`, `3` or `4`. 2x/3x are downsampled from the 4x result | | `model` | `general` | `general` (photos) or `anime` (illustrations) | | `denoiseStrength` | `0.5` | 0 = keep grain/texture, 1 = strongest noise & artefact removal (`general` only) | | `faceEnhance` | `true` | Detect and restore faces with GFPGAN (charged per restored face) | | `faceEnhanceStrength` | `0.8` | 1 = full restoration, lower = keep more of the original look | | `maxFaces` | `5` | Faces restored per image, largest first | | `targetWidth` / `targetHeight` | – | Exact output size instead of a factor (aspect kept, max 4x) | | `outputFormat` | `jpg` | `jpg`, `png` or `webp`; `quality` 50–100 | | `maxInputMegapixels` | `4` | Bigger inputs are skipped for free | | `maxOutputMegapixels` | `32` | Factor is reduced to stay below this | Example: ```json { "imageUrls": ["https://example.com/product-small.jpg"], "scale": "4", "model": "general", "denoiseStrength": 0.5, "outputFormat": "jpg" } ``` ### Output Every image becomes one dataset row; the file itself is stored in the run's key-value store and linked in `outputUrl`. ```json { "url": "https://example.com/product-small.jpg", "status": "ok", "outputUrl": "https://api.apify.com/v2/key-value-stores//records/upscaled-0001-product-small-1a2b3c.jpg", "inputWidth": 500, "inputHeight": 500, "outputWidth": 2000, "outputHeight": 2000, "outputMegapixels": 4.0, "scale": 4, "model": "general", "denoiseStrength": 0.5, "format": "jpg", "outputBytes": 812345, "facesDetected": 1, "facesRestored": 1, "chargedBlocks": 1, "processingSeconds": 6.1 } ``` Errors look like `{"url": "...", "status": "error", "errorCode": "HTTP_404", "error": "HTTP 404 (not charged)"}`. Codes: `INVALID_URL`, `HTTP_4xx/5xx`, `TIMEOUT`, `TOO_LARGE`, `INPUT_TOO_LARGE`, `NOT_AN_IMAGE`, `DECODE_ERROR`, `OUT_OF_MEMORY`. ### Use cases - **E-commerce**: enlarge supplier/product photos for Shopify, Amazon, Etsy zoom requirements (e.g. 2000 px minimum). - **Print on demand & Etsy sellers**: upscale artwork to print resolution. - **Real estate & marketplaces**: sharpen small listing photos. - **Old family photos & genealogy**: restore scanned prints and faded portraits before printing or sharing. - **Profile pictures & headshots**: sharpen small or blurry face photos. - **Content & social media**: rescue low-res images, screenshots and memes. - **Anime & game art**: clean 4x upscales of illustrations and sprites. - **Pipelines**: scrape images with any Actor, then pass the dataset to this one. ### Speed & memory Runs on CPU. With the default 2 GB a 500×500 image takes roughly 10–15 s, plus about 5–9 s per restored face; 4 GB is about twice as fast, 8 GB faster still. Memory does not change the price per image. Very large outputs (>32 MP) need 8 GB+. ### Limits & honest notes - Upscaling invents plausible detail; it cannot recover text that is not in the original. Face restoration generates a plausible sharp face from the blurry one: very small or heavily damaged faces can look slightly different from the real person. Lower `faceEnhanceStrength` (or turn `faceEnhance` off) when exact likeness matters. - Only process images you have the right to use. Downloads use a descriptive User-Agent. - Platform pages (Instagram, Google Images, etc.) are not image files: pass direct image URLs. ### Credits Models: [Real-ESRGAN](https://github.com/xinntao/Real-ESRGAN) by Xintao Wang et al. (BSD-3-Clause); [GFPGAN](https://github.com/TencentARC/GFPGAN) v1.4 by Tencent ARC (Apache-2.0, clean architecture without the NVIDIA CUDA ops); [YuNet](https://github.com/opencv/opencv_zoo) face detector (MIT). All converted to ONNX and run with ONNX Runtime. This Actor is not affiliated with these authors. ### Related Actors by gazidev Image Downloader · Image Metadata & EXIF Extractor · Image OCR · Video Frame Extractor · Website Screenshot # Actor input Schema ## `imageUrls` (type: `array`): Direct links to JPEG, PNG, WebP, HEIC/HEIF, AVIF, TIFF, GIF (first frame) or BMP files. Duplicates are removed; invalid values and failed downloads are reported for free. ## `bulkText` (type: `string`): One URL per line, or a CSV with a `url` / `image` column. ## `sourceFileUrl` (type: `string`): Public .txt or .csv link (Google Sheets 'Publish to web → CSV' works). ## `datasetId` (type: `string`): Chain after a scraper (e.g. product images) or our Image Downloader. ## `datasetField` (type: `string`): Arrays of URLs are accepted too. ## `scale` (type: `string`): Real-ESRGAN works at 4x; 2x and 3x are downsampled from the 4x result (cleaner than a direct 2x). Ignored when you set a target width or height. ## `model` (type: `string`): Both models are fast enough for CPU. Use 'anime' for flat colours and line art. ## `denoiseStrength` (type: `number`): 0 keeps grain and fine texture, 1 removes noise and JPEG artefacts most strongly. Only used by the 'general' model. ## `faceEnhance` (type: `boolean`): Detects faces and restores them with GFPGAN v1.4 (sharper eyes, skin and hair on old, blurry or low-res portraits). Images without faces are not affected and cost nothing extra. Charged per restored face. ## `faceEnhanceStrength` (type: `number`): How much of the restored face is blended in. 1 = full GFPGAN result, 0.5 = half restored and half plain upscale (keeps more of the original look). ## `maxFaces` (type: `integer`): Restores up to this many faces per image, largest first. Group photos: raise it. Each restored face is charged. ## `targetWidth` (type: `integer`): Resize to this width instead of using the factor (aspect ratio kept, at most 4x the original). ## `targetHeight` (type: `integer`): Resize to this height instead of using the factor. With both width and height, the image fits inside the box. ## `outputFormat` (type: `string`): JPG is smallest for photos. PNG and WebP keep transparency (JPG puts transparent areas on white). ## `quality` (type: `integer`): Ignored for PNG. ## `maxInputMegapixels` (type: `number`): Larger images are skipped for free (cost guard). Upscaling is billed per 0.25 MP of input, so a 2 MP photo costs 8 blocks. ## `maxOutputMegapixels` (type: `number`): The factor is reduced so the result stays below this size (and fits in memory). ## `maxImages` (type: `integer`): 0 = no limit. ## `maxFileSizeMb` (type: `integer`): Downloads above this size are skipped for free. ## `proxyConfiguration` (type: `object`): Only needed if an image host blocks datacenter IPs. ## Actor input object example ```json { "imageUrls": [ "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/0014.jpg", "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/ADE_val_00000114.jpg" ], "datasetField": "url", "scale": "4", "model": "general", "denoiseStrength": 0.5, "faceEnhance": true, "faceEnhanceStrength": 0.8, "maxFaces": 5, "outputFormat": "jpg", "quality": 92, "maxInputMegapixels": 4, "maxOutputMegapixels": 32, "maxImages": 0, "maxFileSizeMb": 30 } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `results` (type: `string`): No description ## `files` (type: `string`): No description ## `summary` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "imageUrls": [ "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/0014.jpg", "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/ADE_val_00000114.jpg" ] }; // Run the Actor and wait for it to finish const run = await client.actor("gazidev/image-upscaler").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "imageUrls": [ "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/0014.jpg", "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/ADE_val_00000114.jpg", ] } # Run the Actor and wait for it to finish run = client.actor("gazidev/image-upscaler").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "imageUrls": [ "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/0014.jpg", "https://raw.githubusercontent.com/xinntao/Real-ESRGAN/master/inputs/ADE_val_00000114.jpg" ] }' | apify call gazidev/image-upscaler --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,gazidev/image-upscaler" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/rKyVxjGzRZETIXd0a/builds/AOUIvhfI1cyQejoAf/openapi.json