Upscale Generation

Scenario’s Upscale generation endpoint lets you programmatically enhance the resolution of your images.
You can apply presets for quick results or fine‑tune parameters such as style and creativity decay to achieve the desired balance between fidelity and creativity.

Model‑specific parameters

The parameter fields described below are common to many of Scenario’s image upscaling models. Each model may expose additional parameters or omit certain fields depending on its architecture. For the most accurate list of supported parameters, consult the individual model reference pages (see Image Upscale Models and Video Upscale Models).

Endpoint

POST https://api.cloud.scenario.com/v1/generate/custom/{modelId}

Use this endpoint to upscale an image using a specific upscale model. Replace {modelId} with the identifier of the upscale model you want to use (for example model_sc-upscale-flux or model_upscale-v3). The request must include an image (by asset ID), and you can optionally specify parameters to control the upscaling behaviour.

Path parameter

Name	Type	Description
modelId	string (required)	Identifier of the upscale model. See the Upscale Models article for available model IDs.

Query parameter

Name	Type	Description
dryRun	string	If present, performs a test run without actually generating an upscale. Useful for verifying parameters and cost.

Body parameters

The payload for the custom endpoint will vary depending on the modelId and the type of generation (video or Image).

Image Upscale Models: https://docs.scenario.com/docs/image-upscale-models-parameters-reference#/
Video Upscale Models: https://docs.scenario.com/docs/video-upscale-models-parameters-reference#/

Job Polling: Retrieving Asynchronous Results

Unlike instant image generation, video and 3D model generation are asynchronous processes. This means that when you make a request to the custom endpoint, you will receive a jobId immediately, but the actual generation will happen in the background. You then need to periodically poll a separate endpoint to check the status and retrieve the final asset.

Polling Endpoint

GET https://api.cloud.scenario.com/v1/jobs/{jobId} - API Reference

Polling Response

The response from the polling endpoint will contain the current status of your job. You should continue polling until the status field indicates success or failed.

{
  "job": {
    "jobId": "job_abc123def456",
    "status": "processing", // Can be \"queued\", \"processing\", \"success\", \"failed\", \"canceled\"
    "progress": 0.5, // Optional: progress percentage
    "metadata": {
      "assetIds": []
    }
  },
  "creativeUnitsCost": 5
}

Once the status is success, the metadata.assetIds field will contain the IDs to your generated image or video assets.

Code Examples: Upscale Generation with Seed VR2 Image Upscale

Below are sample requests in cURL, Node and Python showing how to call the Upscale generation endpoint. Replace YOUR_API_KEY with your Scenario API token and ASSET_ID with the image you want to upscale.

cURL

curl -X POST https://api.cloud.scenario.com/v1/generate/custom/YOUR_UPSCALE_MODEL_ID \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl":"asset_nLSAU1UrvHrMz4NwULxheLaT",
    "upscaleMode":"factor",
    "upscaleFactor":5,
    "targetResolution":"2160p",
    "noiseScale":0.1
  }'

Python

import requests
import time

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"
project_id = "your_project_id"

# Step 1: Initiate Upscale Generation
custom_upscale_model_id = "your_upscale_model_id" # Replace with actual upscale model ID
initial_url = f"https://api.cloud.scenario.com/v1/generate/custom/{custom_upscale_model_id}?projectId={project_id}"
headers = {"Content-Type": "application/json"}

payload = {
    "imageUrl":"asset_nLSAU1UrvHrMz4NwULxheLaT",
    "upscaleMode":"factor",
    "upscaleFactor":5,
    "targetResolution":"2160p",
    "noiseScale":0.1
}

print("Initiating upscale generation...")
initial_response = requests.post(initial_url, headers=headers, json=payload, auth=(api_key, api_secret))

if initial_response.status_code == 200:
    initial_data = initial_response.json()
    job_id = initial_data.get("job").get("jobId")
    if job_id:
        print(f"Upscale generation job initiated. Job ID: {job_id}")
        
        # Step 2: Poll for Job Status
        polling_url = f"https://api.scenario.com/v1/jobs/{job_id}"
        status = "queued"
        while status not in ["success", "failure", "canceled"]:
            print(f"Polling job {job_id}... Current status: {status}")
            time.sleep(3) # Wait for 3 seconds before polling again
            
            polling_response = requests.get(polling_url, auth=(api_key, api_secret))
            if polling_response.status_code == 200:
                polling_data = polling_response.json()
                status = polling_data.get("job").get("status")
                progress = polling_data.get("job").get("progress", 0) * 100
                print(f"Progress: {progress:.2f}%")
                
                if status == "success":
                    asset_ids = polling_data.get("job").get("metadata").get("assetIds", [])
                    print(f"Video generation completed! Asset IDs: {asset_ids}")
                elif status in ["failure", "canceled"]:
                    print(f"Video generation failed or canceled: {polling_data.get("job").get("error")}")
            else:
                print(f"Error polling job status: {polling_response.status_code} - {polling_response.text}")
                break
    else:
        print("Error: No jobId returned in the initial response.")
else:
    print(f"Error initiating upscale generation: {initial_response.status_code} - {initial_response.text}")

Node.js

const fetch = require("node-fetch");

const apiKey = "YOUR_API_KEY";
const apiSecret = "YOUR_API_SECRET";
const projectId = "yourprojectid";

const credentials = Buffer.from(`${apiKey}:${apiSecret}`).toString("base64");

async function generateUpscale() {
  const customUpscaleModelId = "your_upscale_model_id"; // Replace with actual upscale model ID
  const initialUrl = `https://api.cloud.scenario.com/v1/generate/custom/${customUpscaleModelId}?projectId=${projectId}`;
  const headers = {
    "Content-Type": "application/json",
    Authorization: `Basic ${credentials}`,
  };

  const payload = {
    imageUrl: "asset_nLSAU1UrvHrMz4NwULxheLaT", // Your Asset ID to upscale
    noiseScale: 0.1,
    upscaleFactor: 2,
		upscaleMode: "factor"
  };

  console.log("Initiating upscale generation...");
  try {
    const initialResponse = await fetch(initialUrl, {
      method: "POST",
      headers: headers,
      body: JSON.stringify(payload),
    });

    const initialData = await initialResponse.json();

    if (initialResponse.ok) {
      const jobId = initialData.job.jobId;
      if (jobId) {
        console.log(`Upscale generation job initiated. Job ID: ${jobId}`);

        const pollingUrl = `https://api.scenario.com/v1/jobs/${jobId}`;
        let status = "queued";

        while (!["success", "failure", "canceled"].includes(status)) {
          console.log(`Polling job ${jobId}... Current status: ${status}`);
          await new Promise(resolve => setTimeout(resolve, 3000)); // Wait for 3 seconds

          const pollingResponse = await fetch(pollingUrl, {
            headers: { Authorization: `Basic ${credentials}` },
          });
          const pollingData = await pollingResponse.json();

          if (pollingResponse.ok) {
            status = pollingData.job.status;
            const progress = (pollingData.job.progress || 0) * 100;
            console.log(`Progress: ${progress.toFixed(2)}%`);

            if (status === "success") {
              const asset_ids = polling_data.get("job").get("metadata").get("assetIds", []);
              console.log("Video generation completed! Asset IDs:", asset_ids);
            } else if (["failure", "canceled"].includes(status)) {
              console.error(`Video generation failed or canceled: ${pollingData.job.error}`);
            }
          } else {
            console.error(`Error polling job status: ${pollingResponse.status} - ${JSON.stringify(pollingData)}`);
            break;
          }
        }
      } else {
        console.error("Error: No jobId returned in the initial response.");
      }
    } else {
      console.error(`Error initiating upscale generation: ${initialResponse.status} - ${JSON.stringify(initialData)}`);
    }
  } catch (error) {
    console.error("Network or other error:", error);
  }
}

generateUpscale();

👉 Download OpenAPI spec