Image Upscaling API

Enhance the resolution and quality of your images using Runware's advanced upscaling API. Transform low-resolution images into sharp, high-definition visuals.

Introduction

Upscaling refers to the process of enhancing the resolution and overall quality of images. This technique is particularly useful for improving the visual clarity and detail of lower-resolution images, making them suitable for various high-definition applications.

Remember that the outputFormat parameter only supports PNG format for images with transparency. For all other formats, the transparency will be removed.

Playground

Upscale
Get one! 
 
 
 
  
  
  
  
  
  
 
 
 
 
  
  
  
  
 
  
  
  
  
  
  
 
 
 
 
 
  
  
  
  
  
  
  
  
 
 
  
  
  
  
 
 
 
 
 
   


Request
Our API always accepts an array of objects as input, where each object represents a specific task to be performed. The structure of the object varies depending on the type of the task. For this section, we will focus on the parameters related to the image upscaling task.
The following JSON snippets shows the basic structure of a request object. All properties are explained in detail in the next section.
[
  {
    "taskType": "imageUpscale",
    "taskUUID": "19abad0d-6ec5-40a6-b7af-203775fa5b7f",
    "inputImage": "fd613011-3872-4f37-b4aa-0d343c051a27",
    "outputType": "URL",
    "outputFormat": "jpg",
    "upscaleFactor": 2
  }
]
 
  
 
 taskType 
 
 string required     
 
 
 
  
The type of task to be performed. For this task, the value should be imageUpscale.
  
 
    
 
  
 
 taskUUID 
 
 string required UUID v4    
 
 
 
  
When a task is sent to the API you must include a random UUID v4 string using the taskUUID parameter. This string is used to match the async responses to their corresponding tasks.


If you send multiple tasks at the same time, the taskUUID will help you match the responses to the correct tasks.


The taskUUID must be unique for each task you send to the API.
  
 
    
 
  
 
 inputImage 
 
 string required     
 
 
 
  
Specifies the input image to be processed. The image can be specified in one of the following formats:


    

  • An UUID v4 string of a previously uploaded image or a generated image.
    • 

  • A data URI string representing the image. The data URI must be in the format data:<mediaType>;base64, followed by the base64-encoded image. For example: data:image/png;base64,iVBORw0KGgo....
    • 

  • A base64 encoded image without the data URI prefix. For example: iVBORw0KGgo....
    • 

  • A URL pointing to the image. The image must be accessible publicly.
    • 



Supported formats are: PNG, JPG and WEBP.


The maximum size of the upscaled result is 4096x4096 pixels. If the combination of input size and upscale factor would exceed this limit, the input image will be automatically resized. For example, a 2048x2048 image with an upscaleFactor of 4 will first be reduced to 1024x1024 to ensure the final result stays within limits.
  
 
    
 
  
 
 outputType 
 
 "base64Data" | "dataURI" | "URL"     Default: URL 
 
 
 
  
Specifies the output type in which the image is returned. Supported values are: dataURI, URL, and base64Data.


    

  • base64Data: The image is returned as a base64-encoded string using the imageBase64Data parameter in the response object.
    • 

  • dataURI: The image is returned as a data URI string using the imageDataURI parameter in the response object.
    • 

  • URL: The image is returned as a URL string using the imageURL parameter in the response object.
    • 

  
 
    
 
  
 
 outputFormat 
 
 "JPG" | "PNG" | "WEBP"     Default: JPG 
 
 
 
  
Specifies the format of the output image. Supported formats are: PNG, JPG and WEBP.
  
 
    
 
  
 
 outputQuality 
 
 integer   Min: 20 Max: 99 Default: 95 
 
 
 
  
Sets the compression quality of the output image. Higher values preserve more quality but increase file size, lower values reduce file size but decrease quality.
  
 
    
 
  
 
 webhookURL 
 
 string      
 
 
 
  
Specifies a webhook URL where JSON responses will be sent via HTTP POST when generation tasks complete. For batch requests with multiple results, each completed item triggers a separate webhook call as it becomes available.


Webhooks can be secured using standard authentication methods supported by your endpoint, such as tokens in query parameters or API keys.


// Basic webhook endpoint
https://api.example.com/webhooks/runware

// With authentication token in query
https://api.example.com/webhooks/runware?token=your_auth_token

// With API key parameter
https://api.example.com/webhooks/runware?apiKey=sk_live_abc123

// With custom tracking parameters
https://api.example.com/webhooks/runware?projectId=proj_789&userId=12345


The webhook POST body contains the JSON response for the completed task according to your request configuration.
  
 
    
 
  
 
 deliveryMethod 
 
 "sync" | "async" required    Default: sync 
 
 
 
  
Determines how the API delivers task results. Choose between immediate synchronous delivery or polling-based asynchronous delivery depending on your task requirements.


Sync mode ("sync"):


Returns complete results directly in the API response when processing completes within the timeout window. For long-running tasks like video generation or model uploads, the request will timeout before completion, though the task continues processing in the background and results remain accessible through the dashboard.


Async mode ("async"):


Returns an immediate acknowledgment with the task UUID, requiring you to poll for results using getResponse once processing completes. This approach prevents timeout issues and allows your application to handle other operations while waiting.


Polling workflow (async):


    

  1. Submit request with deliveryMethod: "async".
    2. 

  2. Receive immediate response with the task UUID.
    3. 

  3. Poll for completion using getResponse task.
    4. 

  4. Retrieve final results when status shows "success".
    5. 



When to use each mode:


    

  • Sync: Fast image generation, simple processing tasks.
    • 

  • Async: Video generation, model uploads, or any task that usually takes more than 60 seconds.
    • 



Async mode is required for computationally intensive operations to avoid timeout errors.
  
 
    
 
  
 
 uploadEndpoint 
 
 string      
 
 
 
  
Specifies a URL where the generated content will be automatically uploaded using the HTTP PUT method. The raw binary data of the media file is sent directly as the request body. For secure uploads to cloud storage, use presigned URLs that include temporary authentication credentials.


Common use cases:


    

  • Cloud storage: Upload directly to S3 buckets, Google Cloud Storage, or Azure Blob Storage using presigned URLs.
    • 

  • CDN integration: Upload to content delivery networks for immediate distribution.
    • 



// S3 presigned URL for secure upload
https://your-bucket.s3.amazonaws.com/generated/content.mp4?X-Amz-Signature=abc123&X-Amz-Expires=3600

// Google Cloud Storage presigned URL
https://storage.googleapis.com/your-bucket/content.jpg?X-Goog-Signature=xyz789

// Custom storage endpoint
https://storage.example.com/uploads/generated-image.jpg


The content data will be sent as the request body to the specified URL when generation is complete.
  
 
    
 
  
 
 includeCost 
 
 boolean     Default: false 
 
 
 
  
If set to true, the cost to perform the task will be included in the response object.
  
 
    
 
  
 
 upscaleFactor 
 
 integer required  Min: 2 Max: 4  
 
 
 
  
This value is the level of upscaling performed.


Each will increase the size of the image by the corresponding factor.


For instance, an upscaleFactor of 2 will 2x image size.
  
 
    


Response
Results will be delivered in the format below.
{
  "data": [
    {
      "taskType": "imageUpscale",
      "taskUUID": "19abad0d-6ec5-40a6-b7af-203775fa5b7f",
      "imageUUID": "e0b6ed2b-311d-4abc-aa01-8f3fdbdb8860",
      "inputImageUUID": "fd613011-3872-4f37-b4aa-0d343c051a27",
      "imageURL": "https://im.runware.ai/image/ws/0.5/ii/e0b6ed2b-311d-4abc-aa01-8f3fdbdb8860.jpg",
      "cost": 0
    }
  ]
}
 
  
 
 taskType 
 
 string      
 
 
 
  
The API will return the taskType you sent in the request. In this case, it will be imageUpscale. This helps match the responses to the correct task type.
  
 
    
 
  
 
 taskUUID 
 
 string  UUID v4    
 
 
 
  
The API will return the taskUUID you sent in the request. This way you can match the responses to the correct request tasks.
  
 
    
 
  
 
 imageUUID 
 
 string  UUID v4    
 
 
 
  
A unique identifier for the output image. This UUID can be used to reference the image in subsequent operations or for tracking purposes.


The imageUUID is different from the taskUUID. While taskUUID identifies the request, imageUUID identifies the specific image output.
  
 
    
 
  
 
 imageURL 
 
 string      
 
 
 
  
If outputType is set to URL, this parameter contains the URL of the image to be downloaded.
  
 
    
 
  
 
 imageBase64Data 
 
 string      
 
 
 
  
If outputType is set to base64Data, this parameter contains the base64-encoded image data.
  
 
    
 
  
 
 imageDataURI 
 
 string      
 
 
 
  
If outputType is set to dataURI, this parameter contains the data URI of the image.
  
 
    
 
  
 
 cost 
 
 float      
 
 
 
  
if includeCost is set to true, the response will include a cost field for each task object. This field indicates the cost of the request in USD.