---
title: "Enlarge a finished render"
method: POST
path: "/renders/{render}/upscale"
tags: ["Renders"]
---

# Enlarge a finished render

`POST /renders/{render}/upscale`

## Request

- Base URL: `https://api.getfacade.ai/api/v1`
- URL: `https://api.getfacade.ai/api/v1/renders/{render}/upscale`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.getfacade.ai/oauth/authorize`, token URL `https://api.getfacade.ai/oauth/token`, scopes: `agent`)

Costs tokens and is asynchronous, exactly like a render: poll the returned job. A render
that is not finished, or already upscaled, is refused with the API's own explanation.

## Path parameters

- `render` string, required

## Headers

- `Idempotency-Key` string, required

## Response `200`

The render is already upscaled; its file URL is returned and nothing was charged.

- object
  - `data` Render: JSON:API resource. `id` is a top-level field, never inside `attributes`.
    - `type` string, required
    - `id` string, required
    - `attributes` object
      - `status` string
      - `started_at` string, date-time, nullable
      - `typical_duration` integer, nullable: Seconds this render usually takes end to end. Use it to pace polling.
      - `file_url` string, nullable: Permanent public link to the finished image. No signature, no expiry.
      - `error_message` string, nullable: Why the render failed, in the account's language. Present only on a failed render.
      - `error_code` string, nullable: Stable machine code for the failure (provider_error, timeout, style_transfer_error, ...).
      - `mode` 'explore' | 'refine'
      - `is_refine` boolean
      - `settings` object
        - `seed` integer
    - `relationships` object
      - `concept_angle` object
        - `data` ToOne
          - `data` object
            - `type` string, required
            - `id` string, required
        - `meta` object: The design this render landed in — a refine of a main view forks a new one.
          - `concept_id` string
          - `project_id` string
      - `parent_render` object: The render this one iterates on, null outside refine mode.
        - `data` object, nullable

## Other responses

- `202`: Upscale queued
- `402`: Admission refused before any work was queued. `AGENT_KEY_CAP_REACHED` — this key has spent its cap, issue a new one or raise it. `AGENT_CREDITS_EXHAUSTED` — the account has no `api`-scope credits left. Neither is retryable: back off and report the `detail` text as it stands.
- `409`: An upscale of this render is already running (its job id is in the body), or `IDEMPOTENCY_IN_PROGRESS` — the first call under this `Idempotency-Key` has not answered yet. Both mean the same thing in practice: poll, do not order again.
- `422`: The request was understood and refused. The message is the API's own text; show it unchanged. `IDEMPOTENCY_KEY_REQUIRED` — a paid call from an agent key with no `Idempotency-Key` header; nothing was queued, send it again with one. `IDEMPOTENCY_KEY_REUSED` — that header value already names a different request; a new order needs a new value.
- `429`: Rate limited on this key's own bucket, separate from the human sessions of the same account. Refusal is deliberately cheap: back off, do not retry in a tight loop.

---

[API](https://skmtc.dev/getfacade/apis/getfacade-agent-api.md) · [All operations](https://skmtc.dev/getfacade/apis/getfacade-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getfacade/apis/getfacade-agent-api/revisions/2b52eda7362c?raw)