Introduction

Welcome to the Upsampler API! Our API lets you integrate creative upscaling (Flux, Stable Diffusion) and precise upscaling (SeedVR2, GAN) into your applications. This API operates over HTTPS and uses JSON for request and response bodies. The input parameter structures are nearly identical to the settings you can choose in the web app.

Use the API version toggle below to view either the legacy v1 endpoints or the new v2 paths. v1 remains supported for existing integrations.

All tasks are processed asynchronously. You can provide a webhook URL to be notified when processing is complete, or you can poll the status endpoint. Please note that all returned image URLs are temporary and will expire after 3 hours.

Pricing

Like in the web app, credits are consumed based on the size of the output image:

• For creative upscaling (Flux / Stable Diffusion):
  1 credit per megapixel of the output image with a minimum cost of 1 credit
• For precise upscaling (SeedVR2 / GAN):
  1 credit per 4 megapixels of the output image with a minimum cost of 1 credit

Authentication

All API requests require authentication. Include your API key in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

API Version

Select the API version you want to use. v2 introduces clearer endpoint naming while keeping request payloads nearly identical. New integrations should use v2 by default.

Base URL

All API requests should be made to the following base URL:

https://upsampler.com/api/v2

General Request Structure

All POST requests to the upscaling endpoints share a common structure:

{
  "webhook": "YOUR_WEBHOOK_URL", // Optional
  "input": { /* Schema-specific input parameters as detailed below */ }
}

• webhook (string, optional): A HTTPS URL where a POST request with the results (or error) will be sent upon completion or failure of the upscaling job. We will attempt to deliver the webhook notification up to 3 times with exponential backoff if the initial attempts fail. Your endpoint should respond with a 2xx status code to acknowledge receipt.
• input (object, required): An object containing the specific parameters for the chosen endpoint. The schema for this object varies by endpoint (see below).

Endpoints

Click on an endpoint below to see its request structure and code examples.

Legacy: Image Restoration

The image restoration tool is retired and closed to new integrations. The endpoint below stays active with unchanged behavior and pricing, so existing integrations keep working, and its reference documentation is kept here for those users. Authentication, the general request structure, the status endpoint, response handling, and rate limits all apply to it unchanged.

Restoration is billed as a fixed cost per image that varies by model, from 4 to 22 credits. The price is set by the model you choose (see the input schema below for the full list of models). If you omit it, requests default to Nano Banana Pro (18 credits).

Response Handling

Upon submitting a valid request to an upscale endpoint, you will receive an initial synchronous response confirming that the job has been started or queued. Make sure you store the id from this response, as it is the key to associating the final, asynchronous result with your initial request. The actual results, including image URLs or any processing errors, are delivered asynchronously. If you provide a webhook URL, the final results will be send there. Otherwise, you must use the GET /status/{id} endpoint to retrieve the results.

Initial Synchronous Response:

// Synchronous Response on Success
{
  "id": "xxxxxxxxxxxx",
  "status": "IN_PROGRESS", // or "IN_QUEUE"
  "creditCost": x
}

// Synchronous Response on Failure
{
  "status": "FAILED",
  "error": "ERROR MESSAGE"
}

Asynchronous Results:

Once the job is complete, you can retrieve the final results in one of two ways:

1. Webhook: Our server will send a POST request to the provided `webhook` URL with the final result.
2. Status endpoint: You can call the GET /status/{id} endpoint with the job ID.

Important: The compressedImageUrl and imageUrl are temporary and will only be valid for 3 hours. Please download and store the images.

Final Result Payloads (via Webhook or GET):

// Payload on Success
{
  "id": "xxxxxxxxxxxx",
  "status": "SUCCESS",
  "compressedImageUrl": "URL_TO_COMPRESSED_IMAGE", // display-sized rendition
  "imageUrl": "URL_TO_FULL_QUALITY_IMAGE", // full-quality output (PNG for upscales)
  "creditCost": x
}

// Payload on Failure
{
  "id": "xxxxxxxxxxxx",
  "status": "FAILED",
  "error": "Failed to process image due to an internal error. Your credits have been refunded."
}

Error Handling (Synchronous)

Errors that occur before a job is started or queued (e.g., authentication issues, invalid request structure, validation errors) will be returned synchronously. The API uses standard HTTP status codes.

• 400 Bad Request: The request JSON was malformed or contained semantic errors (e.g., upscaleFactor out of range).
• 401 Unauthorized: No API key was provided, or the API key is invalid.
• 403 Forbidden: API key inactive or insufficient credits.
• 404 Not Found: The requested job ID does not exist (applies to the GET /status/{id} endpoint).
• 413 Payload Too Large: The request payload exceeds the maximum allowed size.
• 429 Too Many Requests: You have exceeded the rate limit, or your account already has as many jobs running and queued as your plan allows.
• 500 Internal Server Error: An unexpected error occurred on our side before the job could be started or queued.

Processing errors that occur after a job has been queued will be reported via the webhook.

Rate Limits

To ensure service stability, API requests are rate-limited per API key. The current limit for the upscaling endpoints is 90 requests per minute and 6000 requests per hour. For the GET /status/{id} endpoint, the limit is 240 requests per minute. Exceeding these limits will result in a 429 Too Many Requests error. Keep in mind that your subscription plan’s concurrent job and queue size limits apply as well: jobs beyond the concurrent limit are queued, and a full queue also returns 429.

Support

If you have any questions, encounter issues, or need assistance with the API, please do not hesitate to contact us.