> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitstudio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upscale an image

> Upscale an image to a 4K target with SeedVR.

Use a completed image as the source. This endpoint uses SeedVR with a **4K (2160p) target**. Send an empty JSON object to use the defaults:

```json theme={null}
{}
```

Read `result.width` and `result.height` for the actual output dimensions. Check fine product details in the result before publishing.

A successful request returns HTTP `202` with a `jobs` array. Save each `id`, then [get the job](/api-reference/jobs/get) until it finishes. Read the completed media from `result.url` and its reusable ID from `result.id`. Use an [Idempotency-Key](/api-reference/errors) when submitting work that may be retried.


## OpenAPI

````yaml api-reference/openapi.json POST /v1/images/{id}/upscale
openapi: 3.0.3
info:
  title: bitStudio public API
  version: 1.0.0
  description: >-
    Public v1 operations. Create work with a focused endpoint, then retrieve its
    job. Media IDs are opaque; API clients do not manage Studio versions. New
    response fields may be added; clients should ignore fields they do not
    recognize.
servers:
  - url: https://api.bitstudio.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/images/{id}/upscale:
    post:
      summary: Upscale an image
      operationId: upscale
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Source resource ID.
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[!-~]+$
          description: >-
            Use a unique key for each intended creation. Retry the same method,
            path and JSON with the same key to replay its response for 24 hours
            after completion. Conflicting requests and unfinished or uncertain
            outcomes return 409. An uncertain receipt is never automatically
            rerun.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicUpscaleRequest'
            example:
              target_resolution: 4k
      responses:
        '202':
          description: Accepted; poll each job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
              example:
                jobs:
                  - id: 11111111-1111-4111-8111-111111111111
                    status: pending
                    task: upscale
                    created_at: '2026-09-15T12:00:00Z'
                    result: null
                    error: null
                    credits_used: 2
        default:
          description: Request failed; inspect code and message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PublicUpscaleRequest:
      type: object
      additionalProperties: false
      properties:
        target_resolution:
          type: string
          enum:
            - 4k
          default: 4k
          description: >-
            Output target. Defaults to 4K (2160p) using SeedVR. Read
            result.width and result.height for the actual dimensions.
    Submission:
      type: object
      required:
        - jobs
      properties:
        jobs:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Job'
    Error:
      type: object
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
        message:
          type: string
        request_id:
          type: string
          format: uuid
        error:
          type: string
          description: Compatibility error description.
        cta:
          type: boolean
          description: Account action is required.
        next_action:
          type: string
    Job:
      type: object
      required:
        - id
        - status
        - task
        - created_at
        - result
        - error
        - credits_used
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - generating
            - completed
            - failed
            - policy_blocked
        task:
          type: string
          nullable: true
          description: >-
            Processing task. This may be more specific than the submitted
            operation.
        created_at:
          type: string
          format: date-time
        result:
          $ref: '#/components/schemas/JobResult'
        error:
          $ref: '#/components/schemas/JobError'
        credits_used:
          type: number
          minimum: 0
          description: >-
            Credits currently charged for this output, in display credits: 1
            means one Studio credit. Fractional amounts are preserved. A
            completed refund is reflected as 0 when polling. Creation and
            idempotency replay responses are snapshots; poll for the latest
            charge.
          example: 1.5
    JobResult:
      type: object
      nullable: true
      required:
        - image_id
        - url
        - width
        - height
        - id
        - type
      properties:
        image_id:
          type: string
          format: uuid
          description: Compatibility alias for id. Use id for new integrations.
        url:
          type: string
          format: uri
          description: Completed media URL.
        width:
          type: integer
          nullable: true
        height:
          type: integer
          nullable: true
        id:
          type: string
          format: uuid
          description: >-
            Opaque media ID. Pass an image result ID into the next image
            operation.
        type:
          type: string
          enum:
            - image
            - video
    JobError:
      type: object
      nullable: true
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Safe failure classification. Handle unknown or new values with a
            general failure message.
        message:
          type: string
          description: Safe, readable failure description.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Create an API key in Studio → account menu → API Keys. Keep it on your
        server.

````