Powerful Public API for Advanced AI Image Upscaling

Introduction

Welcome to the Upsampler API! Our API allows you to integrate Smart Upscale, Dynamic Upscale, Precise Upscale, and Image Restoration 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.

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 Smart Upscale and Dynamic Upscale:
  1 credit per megapixel of the output image with a minimum cost of 1 credit
• For Precise Upscale:
  1 credit per 4 megapixels of the output image with a minimum cost of 1 credit
• For Image Restoration:
  fixed cost of 8 credits per restoration

Authentication

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

Authorization: Bearer YOUR_API_KEY

Base URL

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

https://upsampler.com/api/v1

General Request Structure

All POST requests to the upscaling and restoration 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.

Response Handling

Upon submitting a valid request to an upscale or restoration 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_JPG",
  "imageUrl": "URL_TO_FULL_QUALITY_PNG",
  "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).
• 429 Too Many Requests: You have exceeded the rate limit or queue size.
• 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 fair usage and service stability, API requests are rate-limited per API key. The current limit for the upscaling and restoration 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.

Support

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