The Upscaling Step You Don't Want to Build — and the API That Replaces It.

Why Not Build It Yourself?

Let's be specific about what "building upscaling yourself" means in 2026:

• GPU compute: Real-ESRGAN inference on a 4K job takes 2–8 seconds on an A100. On a CPU, that's 3–5 minutes. You need GPU instances — on AWS, an g4dn.xlarge (NVIDIA T4) costs $0.526/hour. A single up to 8K job at peak takes 4 seconds, so you can run ~900 jobs/hour per instance. At scale, you're managing instance fleets, cold start latency, and spot instance interruptions.
• Model management: Real-ESRGAN is the general benchmark, but for faces you need a different model, for video a different pipeline entirely. Maintaining 14 models with version pinning and the ability to route by content type is non-trivial infrastructure.
• Queue and async pattern: Users don't wait synchronously for a 30-second job. You need a job queue, worker pool, status polling or webhooks, and result storage with TTL.
• File handling: 50 MB images. Chunked upload. CDN for results with signed URLs. Automatic deletion after N days. This is 2–3 days of engineering before you process a single image.

The UpRes API ships all of this already built. Here's how to use it.

The API in Three Steps

The complete integration for a basic upscaling feature is three API calls:

1. POST /v1/jobs — submit an upscale job with a source URL and model
2. GET /v1/jobs/{id} — poll until status is completed
3. Read result_url and serve it to your user

Step 1 — Submit a job

curl -X POST https://api.upres.ai/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-storage.com/user-upload.jpg",
    "model": "lumen",
    "scale": 4
  }'

# Response:
# { "id": "job_abc123", "status": "queued", "createdAt": "2026-04-17T..." }

Step 2 — Poll for completion

curl https://api.upres.ai/v1/jobs/job_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# When status == "completed":
# { "id": "job_abc123", "status": "completed", "result_url": "https://cdn.upres.ai/..." }

Step 3 — Store and serve the result

The result URL is a signed CDN link valid for 7 days. Download it to your own storage before it expires if you need longer retention. The original file is deleted 24 hours after job completion for privacy.

Choosing a Model via API

All 14 public aliases are available via the model field. The most commonly used via API:

Poll until the job finishes

The public jobs API does not send a completion webhook. Submit the job, then poll GET /v1/jobs/{id} until status is completed, then read result_url.

Error Handling and Retry Logic

The API returns standard HTTP status codes. Handle these cases:

• 429 (rate limit): Back off with exponential delay. Retry after the Retry-After header value.
• 402 (quota exceeded): Monthly quota exhausted. Add PAYG credits from the billing dashboard or wait for the next cycle.
• 422 (invalid source): The source URL is unreachable or the file is too large. Validate before submitting.
• Job status "failed": Retry once with the same parameters. If it fails again, the source file has a permanent issue (corrupt, wrong format, too small for the requested upscale factor).

Integration Example: Node.js / TypeScript

const BASE = 'https://api.upres.ai/v1';
const KEY = process.env.UPRES_API_KEY!;

async function upscaleImage(imageUrl: string, model = 'lumen') {
  const res = await fetch(`${BASE}/jobs`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ image_url: imageUrl, model, scale: 4 }),
  });
  if (!res.ok) throw new Error(`Submit failed: ${res.status}`);
  const { id } = await res.json() as { id: string };

  // Poll until complete (max 60 attempts × 5s = 5 minutes)
  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));
    const poll = await fetch(`${BASE}/jobs/${id}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    const job = await poll.json() as { status: string; result_url?: string };
    if (job.status === 'completed') return job.result_url!;
    if (job.status === 'failed') throw new Error('Job failed');
  }
  throw new Error('Timeout');
}

// Usage:
const resultUrl = await upscaleImage('https://your-cdn.com/photo.jpg');
// Download result_url and store it before it expires (7 days)

FAQ