Upscayl API: AI Image Upscaler API for Developers

01

Upscayl API Quick Facts

Capability	Current documented behavior
API type	Asynchronous image-processing API
Base server	`https://api.upscayl.org`
Authentication	API key through `X-API-Key`
Direct uploads	Supported
Multipart uploads	Supported through presigned URLs
Input formats	JPG, PNG and WebP
Output formats	JPG, PNG and WebP
Scale options	2×, 4× and 8×
Face enhancement	Optional parameter
Batch mode	Represented in the task model
Task states	Pending, processing, completed and failed
Results	Completed file details and download links
Billing information	Credit status and deductions represented in task data

These details reflect the current public Upscayl OpenAPI specification. Validate the live specification before implementation.

Open the Current API Reference

02

What Is the Upscayl API?

The Upscayl API is a hosted image-processing interface for developers.

It allows a product or internal system to submit an image for AI-assisted upscaling without installing the Upscayl Desktop application or operating a dedicated local graphics-processing environment.

A typical integration has five parts

Authenticate with an API key.

Submit an image and processing settings.

Receive a task ID.

check the task until it reaches a final state.

Retrieve and validate the completed output.

This asynchronous approach is useful because image processing may take longer than a standard web request. Your application can continue other work while Upscayl processes the task.

03

Why Use an Image Upscaler API?

Automate Repetitive Image Work

Manual image processing does not scale well when a catalog, user upload system or creative pipeline contains hundreds or thousands of images.

An API can move the same image-upscaling rules into a repeatable workflow.

Avoid Maintaining GPU Infrastructure

Building an internal image-upscaling service can require

GPU-compatible compute
Model deployment
Queue management
Storage
Monitoring
Worker scaling
Driver maintenance
Security controls
Failure recovery

The Upscayl API moves the documented processing task to hosted infrastructure. Your team remains responsible for integration logic, user authorization, input validation and output review.

Match Processing to the Image

The API exposes several model options rather than forcing one model onto every source.

This is useful when a product handles different classes of images, such as photographs, illustrations and ecommerce assets.

Keep the Workflow Inside Your Product

Users can submit an image and receive a processed output without being sent through a separate manual application.

Build Predictable Task Handling

The task-status endpoint exposes processing state and progress, allowing an application to present a queue, progress indicator or background job.

Choose the Output Format

JPG, PNG and WebP outputs let the integration match different delivery requirements.

Use JPG for suitable photographic delivery, PNG where lossless output or transparency behavior is required, and WebP for supported web workflows. Verify exact transparency handling through a first-party test.

04

Upscayl API Features

Direct Image Uploads

The documented start-task operation accepts a direct binary file upload through a multipart request.

Direct upload is useful for

Single-image tools
User profile images
Product image forms
Admin dashboards
Low-volume internal workflows

Keep the API key on the server. Do not expose it in client-side JavaScript, mobile application code or a public repository.

Multipart Uploads

The current API includes operations for obtaining multipart upload URLs and completing a multipart upload.

This workflow is suitable for larger files or upload flows that benefit from sending the file in parts.

A production integration should handle

Expired upload URLs
Failed parts
Part-number ordering
ETags
Upload cancellation
Duplicate completion attempts
Network interruption
Final upload confirmation

Asynchronous Processing

The API returns a task ID instead of requiring the client to keep one request open until image processing finishes.

Your application can use that task ID to check

Current status
Processing progress
Selected model
Scale
Face-enhancement setting
Processed files
Errors
Credit information
Download links

The official task-status endpoint documents pending, processing, completed and failed states. Get Task Status documentation.

Multiple AI Upscaling Models

The current specification lists model options intended for different image characteristics.

Do not expose raw model identifiers without guidance. Add a user-facing model name, recommended source type, example crop and limitation summary.

Face Enhancement

An optional face-enhancement setting is documented for the start-task operation.

Use it selectively for portraits, older photographs and appropriate group images. It should not be enabled automatically for every image.

AI face enhancement can create plausible detail that was not present in the source. Applications should not present the output as a factual reconstruction.

2×, 4× and 8× Upscaling

The documented API supports 2×, 4× and 8× scale parameters.

Choose the smallest scale that meets the final requirement. Larger output dimensions can increase credit use, processing time, storage and artifact visibility.

JPG, PNG and WebP Outputs

The API currently documents these output options

jpg
png
webp

The application should select an output based on intended use rather than applying one format to every image.

Batch Workflows

The documented task model includes batch-mode behavior and arrays of processed files.

Before building a large batch system, verify

Maximum files per task
Maximum combined upload size
Credit calculation
Partial-failure behavior
Output expiration
Rate limits
Retry policy

05

How the Upscayl API Works

01ValidateFile, user and credits

02SubmitServer-side API request

03TrackStore task ID

04ProcessPending or processing

05RetrieveValidate output

Step 1: Create Server-Side API Access

Obtain an API key through the current Upscayl account or developer-access process.

Store it in

A server-side environment variable
A managed secrets service
An encrypted deployment configuration

Never put a production API key inside public frontend code.

Step 2: Validate the Source Image

Before sending a file, check

MIME type
File size
Image dimensions
Filename
Decode validity
User permission
Plan limits
Available credits

The current API specification documents JPEG, PNG and WebP input MIME types and a 100 MB maximum file-size field. Confirm these values against the live API specification before enforcing them in production.

Step 3: Select Processing Settings

Choose

AI model
2×, 4× or 8× scale
Output format
Face-enhancement status
Single-file or batch workflow

Model selection should be based on image type, not the most dramatic model name.

Step 4: Start the Task

Submit the source image and selected settings to the documented start-task operation.

A successful request returns a task identifier.

Start Upscaling Task documentation.

Step 5: Save the Task ID

Store the task ID with your internal job record.

Useful fields include

Internal job ID
Upscayl task ID
User or account ID
Original asset ID
Requested model
Requested scale
Submission time
Current status
Retry count

Step 6: Check Processing Status

Poll the task-status operation at a controlled interval.

Do not issue continuous status requests. Use backoff, stop polling when the task reaches a final state and respect documented rate limits.

Step 7: Retrieve and Validate the Output

When the job is complete

Retrieve the documented download link.

Download the file to controlled storage.

Confirm its MIME type and dimensions.

Scan or validate the output where required.

Attach it to the correct internal asset.

Apply your own retention policy.

Remove temporary data when no longer needed.

Do not assume that a completed API status means the output is visually suitable.

06

Example Upscayl API Workflow

The following example is intentionally conceptual. Copy the exact request structure from the current API documentation before deployment.

Your application
↓
Validate image and user permissions
↓
Start Upscayl task with API key
↓
Receive and store task ID
↓
Check task status with controlled backoff
↓
Pending → Processing → Completed or Failed
↓
Retrieve output and run application-level validation
↓
Store result and show it to the user

Server-side request pattern

POST /upscale
X-API-Key: ••••••••••••••••

file: product-image.webp
model: photography
scale: 4
output_format: webp
face_enhancement: false

→ { "task_id": "task_…" }

Authentication Pattern

The current specification documents API-key authentication through

X-API-Key: YOUR_SERVER_SIDE_API_KEY

The API key must be sent from trusted server-side code.

Start-Task Parameters

The current specification describes parameters for

Direct file or previously uploaded files
Model
Scale
Output format
Face enhancement

Status Response

The documented task status can include

Model
Scale
Progress
Status
Processed files
Error information
Credit-deduction status
Download links

Implementation note: the public endpoint documentation and OpenAPI examples should be checked for request-shape consistency before code is copied into production.

07

Choose the Right Upscayl API Model

A model should be selected through testing with representative source images.

Photography source example for selecting an Upscayl API model — Photography and portraits

Illustration source example for selecting an Upscayl API model — Digital art and illustration

Product source example for selecting an Upscayl API model — Ecommerce product imagery

General Photographs

Start with a restrained photography-oriented model.

Evaluate

Skin
Hair
Foliage
Fabric
Architecture
Background noise
High-contrast edges

Reject results with strong halos, plastic skin or repeating texture.

Digital Art and Illustrations

Use a model intended to preserve

Clean linework
Flat-color boundaries
Smooth curves
Controlled gradients
Intended texture
Repeated patterns

The current API specification includes model identifiers for digital-art workflows, but the production UI should explain their visual behavior instead of relying on identifiers alone.

Nature and Wildlife

Inspect

Fur
Feathers
Leaves
Grass
Water
Distant detail
Fine natural variation

Watch for repeated or synthetic-looking texture.

Ecommerce Product Images

Prioritize

Accurate silhouettes
Consistent backgrounds
Realistic materials
Controlled reflections
Product colors
Packaging edges
Labels and logos

AI enhancement should not alter the appearance of the actual product.

Portraits

Test the base upscale before enabling face enhancement.

When face enhancement is used, review

Identity
Eyes
Teeth
Hairlines
Eyeglasses
Jewelry
Small background faces

Compare API Models and Example Crops

08

Build Reliable Image Upscaling into Production

1ApplicationValidate and authorize

→

2Job queueControl concurrency

→

3Upscayl APIHosted processing

→

4Quality checkTechnical + visual

Keep API Keys Private

Use server-side requests and a managed secrets system.

Rotate keys when

A developer leaves the project
A key is accidentally logged
A repository exposure occurs
Suspicious usage appears
The organization’s security policy requires rotation

Use a Job Queue

Do not make a user’s browser wait for the complete upscaling operation.

Create an internal job record and process status updates in the background.

Apply Controlled Polling

Use a reasonable initial delay followed by backoff.

Stop polling when the job is

Completed
Failed
Canceled by your system
Older than your maximum allowed task duration

A webhook would reduce polling, but the reviewed public specification does not document one. Do not claim webhook support unless it is added to the current reference.

Make Retries Safe

Retry only failures that are likely to be temporary.

Do not blindly resubmit every timeout. A request may have started successfully even when the client did not receive the response.

Before production launch, confirm whether the API supports idempotency keys or another duplicate-task safeguard. The reviewed specification does not clearly document one.

Validate Credits Before Large Jobs

A task can fail when the account has insufficient credits. The current specification documents an insufficient-credit error and credit information in task status.

For batch workflows

Estimate cost before submission.

Alert before the balance becomes too low.

Prevent partially funded batches.

Record credits used per internal job.

Reconcile API usage with billing records.

Store Original and Output Separately

Never overwrite the source automatically.

Store

Original asset
Upscaled output
Model
Scale
Output format
Processing date
API or model version when available
Review status

Monitor Quality, Not Only Availability

A technically successful API response can still produce an unsuitable image.

Create a review process for

Faces
Text
Product details
Brand marks
Fine patterns
Historical material
Factual imagery

09

Upscayl API Use Cases

Ecommerce Catalogs

Automatically create larger product assets for storefronts, marketplaces, zoom views and campaign layouts.

Use a product-specific quality check to ensure that labels, materials and colors remain accurate.

User-Generated Content Platforms

Offer optional image enhancement after a user uploads a small or compressed image.

Keep processing asynchronous and show a clear job state.

Digital Asset Management

Create higher-resolution derivatives when images enter an asset library.

Store the original, processed version and transformation metadata together.

Print-On-Demand Platforms

Prepare larger working images before validating them against print dimensions and output requirements.

Upscaling does not guarantee that every source is suitable for print.

Social Media Tools

Generate larger versions of thumbnails, campaign images and creative assets.

Preserve editable text and logos separately whenever possible.

Real Estate and Marketplace Listings

Standardize image dimensions while retaining realistic property or item details.

Do not use AI enhancement to misrepresent a property, vehicle or product.

Photo Archiving Services

Create larger working copies of scanned photographs before restoration.

Keep the archival scan untouched.

AI Art Platforms

Provide optional 2×, 4× or 8× exports for generated artwork.

Use models that preserve linework, gradients and the intended artistic style.

Agency Automation

Connect image upscaling with client intake, content approval and export workflows.

Confirm that client agreements permit Cloud processing.

10

Who Should Use the Upscayl API?

The Upscayl API may suit

SaaS product teams
Web application developers
Ecommerce platforms
Digital agencies
Print-on-demand services
Social media tools
Creator platforms
Asset-management systems
Marketplace operators
AI image applications
Internal content teams
Workflow-automation developers

It may not be the right choice when

A user needs only occasional manual upscaling.

Images cannot leave local infrastructure.

A compatible Desktop installation already meets the workflow.

The project requires undocumented latency or uptime guarantees.

The organization needs self-hosting.

Current rate or file limits do not meet expected volume.

11

Upscayl API vs Cloud vs Desktop

Upscayl Cloud browser interface — Cloud: manual hosted workflow

Upscayl Desktop local application — Desktop: manual local workflow

Requirement	API	Cloud	Desktop
Primary interface	Programmatic requests	Web browser	Installed application
Best for	Product integration	Manual online workflow	Manual local workflow
Processing	Hosted	Hosted	Compatible local hardware
API key	Required	No developer key for normal UI use	Not required
Image upload	Required	Required	Not required for local jobs
Automation	Strongest option	Limited to product UI	Manual or local workflow
Credits	API/Cloud billing	Plan-based credits	No hosted processing credits
Local GPU	Not required by client	Not required by client	Normally required
Batch potential	Programmatic	Cloud interface-dependent	Desktop batch workflow
Data control	Governed by API service and your storage	Governed by Cloud service	Local user control

Choose the API When

Upscaling must happen inside your product.

Tasks need to run automatically.

You need task IDs and processing status.

Your system manages many user or catalog images.

Hosted processing fits your data requirements.

Choose Cloud When

A person wants to upscale images through a browser.

No integration is required.

Cloud editing or generation tools are useful.

Choose Desktop When

Local processing is important.

A compatible computer is available.

The user wants a free, open-source application.

Image upload is not appropriate.

CTAs

12

Upscayl API Pricing and Credits

The documented API task flow includes credit checks and credit deductions.

API cost may depend on factors such as

Input dimensions
Output dimensions
Scale
Selected model
Face enhancement
Number of images
Plan
Business agreement

Do not estimate cost using unverified assumptions.

The API page should provide a live calculator with

Number of images
Average input dimensions
Selected scale
Model
Face enhancement
Expected monthly volume
Estimated credits
Estimated plan

Current Cloud pricing includes trials, subscriptions, one-time credit options and custom plans, but API pricing should be confirmed separately before presenting Cloud plan prices as API rates. Current Upscayl pricing.

View API Pricing Contact API Sales

13

Upscayl API Privacy and Security

An API integration uploads user images to hosted infrastructure. Privacy and security information must be visible before implementation.

The current Upscayl Cloud policies state that

Users retain ownership of uploaded content.

Uploaded images are not used to train AI models.

Inputs are generally retained for a limited period.

Generated outputs have a separate retention period.

Cloud service providers assist with authentication and storage.

Encryption in transit and at rest is provided through the service infrastructure.

However, the API page should publish API-specific confirmation of

Input retention
Output retention
Download-link expiration
Multipart-upload expiration
Log retention
Backup deletion
Processing regions
Subprocessors
Encryption
Access controls
Incident notification
Deletion requests
Enterprise agreements

Review the current privacy policy and terms of service, then confirm whether every Cloud policy applies identically to API jobs.

Developer Security Checklist

Keep keys server-side.

Validate file types and dimensions.

Limit upload size before sending.

Authenticate the user initiating the task.

Record who submitted each image.

Avoid logging API keys or signed download URLs.

Rotate compromised credentials.

Download outputs into controlled storage.

Apply your own deletion policy.

Do not expose another user’s task ID or output.

Review sensitive images before Cloud processing.

Read API Security and Data Handling

14

Limitations of an AI Image Upscaler API

The Upscayl API cannot guarantee that it will

Recover detail that was never captured
Correct every out-of-focus photograph
Preserve small text accurately
Maintain every face without change
Remove all compression artifacts
Repair missing image regions
Preserve factual product details automatically
Produce the same quality from every model
Complete every task within a fixed time
Remain available without interruption
Prevent all integration or network failures

A production system needs both technical error handling and visual quality control.

15

Frequently Asked Questions

The Upscayl API is a hosted image upscaler API for starting image-upscaling tasks, checking processing status and retrieving completed outputs.

Use the current developer-access or account process to obtain an API key. The production page should link directly to the current key-management interface.

The current OpenAPI specification documents an API key sent in the X-API-Key request header.

No. Send requests through trusted server-side code and store the key in a secrets-management system.

The current specification identifies JPEG, PNG and WebP MIME types. Confirm the live documentation before enforcing format restrictions.

The current start-task operation lists JPG, PNG and WebP outputs.

The current specification documents 2×, 4× and 8× options.

Yes. The current start-task specification includes an optional face-enhancement parameter.

The API task schemas represent batch mode and multiple files. Verify current per-task file limits, combined size limits and credit behavior before building a batch system.

Store the task ID returned when a job starts and use the task-status operation to check progress and final state.

The reviewed public specification does not clearly document webhook delivery. Use controlled status polling unless the current documentation confirms webhook support.

The task model includes a failed state and error information. Record the error, classify it and retry only when the failure is likely to be temporary.

Yes. The current OpenAPI specification documents endpoint rate limits. Treat those values as changeable and read the current API reference before setting production throughput.

The current uploaded-file schema lists a 100 MB maximum. Other pixel, plan or batch limits may also apply.

Credit cost can depend on the processing request and current pricing rules. Show an estimate before submission when possible.

The current Upscayl service terms state that uploaded images are not used to train AI models. Confirm that the same provision applies to your API agreement.

Commercial use depends on your API agreement, selected models and rights to the source images. Review the current terms before launch.

No. It can generate a larger interpretation and may improve certain edges or textures, but it cannot recover every missing detail.

The reviewed documentation provides request examples, but a maintained official SDK matrix was not clearly documented. Do not advertise official SDKs unless they are published and supported.

The reviewed material describes a hosted API. Do not promise self-hosting unless a separate supported product or license is documented.

16

Add Upscayl API to Your Image Workflow

Automate image upscaling with hosted processing, multiple models, task tracking and supported output formats.

Start with a small set of representative images. Measure output quality, processing time, credit use and failure behavior before moving a production catalog or user workflow to the API.

Get Upscayl API Access Read the API Documentation

Upscayl API for Automated AI Image Upscaling