> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Ingrandire un'immagine
> Invia un job di upscale — un'immagine sorgente verso una risoluzione target superiore — e ottieni un id del job.
Ingrandisci una `image` sorgente verso una `target_resolution` superiore con uno dei
quattro modelli. La chiamata restituisce **`202 Accepted`** con un `id` del job;
interroga [`GET /images/upscales/{id}`](/it/api-reference/image-ops/get-upscale) per
il risultato. L'`image` prende **esattamente uno** tra `image_id`, `url` o
`base64` + `mime_type`. Richiede lo scope `images.transform`.
## Esempio: una sorgente per modalità
```bash image_id theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/upscales \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"model": "crystal",
"target_resolution": "4K"
}'
```
```bash url theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/upscales \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "url": "https://cdn.example.com/photo.png" },
"model": "seedvr",
"target_resolution": "2K"
}'
```
```bash base64 theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/upscales \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "base64": "iVBORw0KGgoAAAANSUhEUg...", "mime_type": "image/png" },
"model": "magnific-precision",
"target_resolution": "6K",
"options": { "magnific_precision": { "flavor": "photo", "sharpen": 20, "ultra_detail": 40 } }
}'
```
## Esempio: magnific-creative con opzioni
```json Body theme={null}
{
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"model": "magnific-creative",
"target_resolution": "8K",
"options": {
"magnific_creative": {
"prompt": "sharp studio product photo",
"optimized_for": "films_n_photography",
"creativity": 2,
"hdr": 1,
"engine": "magnific_sharpy"
}
},
"webhook_url": "https://example.com/webhooks/samsa"
}
```
La risposta `202` è l'handle del job asincrono:
```json 202 Accepted theme={null}
{
"id": "d5e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
"status": "pending",
"estimated_credits": 75
}
```
`model` è `crystal` (predefinito), `seedvr`, `magnific-creative` o
`magnific-precision`. `target_resolution` è **obbligatorio** e tratto da un insieme
chiuso: `2K`, `4K`, `6K`, `8K`, `10K`, `12K`, `14K`, `16K`, `20K`, `24K`, `28K`,
`32K`, `38K`. Le classi oltre `16K` sono valide solo per `crystal`. I limiti di
fattore e area per modello sono validati **prima** di qualsiasi addebito — una
richiesta oltre il limite è un `422`, mai un job addebitato.
Le `options` sono **per modello, tipizzate e validate rigorosamente**: fornisci
`magnific_creative` per il modello `magnific-creative` o `magnific_precision` per
`magnific-precision`. `seedvr` e `crystal` non prendono opzioni — fornire `options`
per loro è un `422`. Chiavi sconosciute o valori fuori intervallo sono un `422`.
* `magnific_creative`: `prompt` (≤ 500 caratteri), `optimized_for`
(`standard` · `soft_portraits` · `hard_portraits` · `art_n_illustration` ·
`videogame_assets` · `nature_n_landscapes` · `films_n_photography` ·
`3d_renders` · `science_fiction_n_horror`), `creativity`/`hdr`/`resemblance`/
`fractality` (interi −10…10), `engine` (`automatic` · `magnific_illusio` ·
`magnific_sharpy` · `magnific_sparkle`).
* `magnific_precision`: `sharpen`/`smart_grain`/`ultra_detail` (interi 0…100),
`flavor` (`sublime` (predefinito) · `photo` · `photo_denoiser`).
## Credits
Il costo è il livello di risoluzione (`2K`:5, `4K`:10, `6K`:20, `8K`:25, `10K`:35,
`12K`:45, `14K`:60, `16K`:80) moltiplicato per il moltiplicatore di credits del
modello (Magnific ×3); Crystal oltre `12K` addebita per megapixel di output. Gli
`estimated_credits` nella risposta `202` corrispondono esattamente all'addebito. Vedi
[Prezzi](/it/guides/pricing).
## Errori
| Stato | Codice | Quando |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402` | [`insufficient_credits`](/it/guides/errors#insufficient_credits) / [`insufficient_team_credits`](/it/guides/errors#insufficient_team_credits) / [`insufficient_unallocated_credits`](/it/guides/errors#insufficient_unallocated_credits) | Il saldo che questa credenziale può spendere è al di sotto del costo del job. Le organizzazioni con almeno un team attivo ricevono i codici legati ai team invece di `insufficient_credits` (eccetto le organizzazioni di sistema esenti dal budgeting per team). Un guasto operativo nella detrazione stessa può comunque restituire il generico `insufficient_credits`, qualunque sia il regime. |
| `402` | [`subscription_inactive`](/it/guides/errors#subscription_inactive) | L'organizzazione non ha un abbonamento utilizzabile. |
| `403` | [`missing_scope`](/it/guides/errors#missing_scope) | La chiave non ha lo scope `images.transform`. |
| `404` | [`not_found`](/it/guides/errors#not_found) | L'`image_id` sorgente è sconosciuto o non appartiene al creatore della chiave — anche un'immagine creata da un altro membro della tua organizzazione è un `404`. |
| `422` | [`validation_error`](/it/guides/errors#validation_error) | Zero/più modalità sorgente, `target_resolution` mancante/non valido, una classe oltre il limite o `options` non valide/mal posizionate. |
| `429` | [`rate_limited`](/it/guides/errors#rate_limited) / [`too_many_active_jobs`](/it/guides/errors#too_many_active_jobs) | Finestra di frequenza per chiave o limite di concorrenza per organizzazione superato. |
## OpenAPI
````yaml api-reference/openapi.json POST /images/upscales
openapi: 3.1.0
info:
title: Samsa API
description: >-
The Samsa public REST API. Authenticate with an organization API key as a
bearer token (`Authorization: Bearer samsa_sk_...`). Errors follow a single
envelope shape; every response carries an `X-Request-ID`.
version: 1.0.0
servers:
- url: https://api.samsa.ai/public/v1
security:
- BearerAuth: []
paths:
/images/upscales:
post:
tags:
- Images
summary: Upscale an image to a higher resolution (all 4 models)
description: >-
Submits an upscale job — one source `image`, a `model`, and a
`target_resolution` — and returns `202` immediately with the job `id`
and a credit estimate; poll `GET /images/upscales/{id}` for the result.
The source is exactly one of `image_id` (an image in your organization's
context), an https `url`, or `base64`+`mime_type`. `model` is one of
`seedvr`, `crystal` (default), `magnific-creative`,
`magnific-precision`. `target_resolution` is a CLOSED set (`2K`, `4K`,
`6K`, `8K`, `10K`, `12K`, `14K`, `16K`, `20K`, `24K`, `28K`, `32K`,
`38K`); classes above `16K` are only valid for `crystal`, and the
per-model factor/area caps are validated BEFORE charging (an over-cap
request is a `422`, never a charged job). `options` are per-model,
typed, and STRICTLY validated (out-of-range / unknown values are `422` —
supply `options.magnific_creative` for `magnific-creative` or
`options.magnific_precision` for `magnific-precision`;
`seedvr`/`crystal` take no options). **Cost** = the resolution tier
(2K:5, 4K:10, 6K:20, 8K:25, 10K:35, 12K:45, 14K:60, 16K:80) x the model
credit multiplier (Magnific x3); `crystal` above 12K prices by output
megapixels. `estimated_credits` in the 202 equals the deduction exactly.
Common errors: an unknown `model`, an over-cap/unsupported
`target_resolution`, or invalid `options` return `422`; a foreign or
unknown `image_id` returns `404`; missing credits or no usable org
subscription returns `402`; the per-key rate limit or per-org
concurrency cap returns `429`. Requires the `images.transform` scope.
operationId: create_image_upscale_images_upscales_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUpscaleRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicTransformAccepted'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'402':
description: Insufficient credits, or no usable org subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: The API key lacks the required scope for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Generation, or a referenced model/palette, not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: A referenced model is not ready for generation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Request validation failed (prompt, engine, resolution, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Per-key rate limit or per-org concurrency cap exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
PublicUpscaleRequest:
properties:
image:
$ref: '#/components/schemas/PublicImageEditSource'
description: >-
The source image: exactly one of `image_id`, an https `url`, or
`base64`+`mime_type`.
model:
type: string
enum:
- seedvr
- crystal
- magnific-creative
- magnific-precision
title: Model
description: >-
Upscale model: `seedvr`, `crystal` (default), `magnific-creative`,
or `magnific-precision`.
default: crystal
examples:
- crystal
target_resolution:
type: string
enum:
- 2K
- 4K
- 6K
- 8K
- 10K
- 12K
- 14K
- 16K
- 20K
- 24K
- 28K
- 32K
- 38K
title: Target Resolution
description: >-
Target resolution class (REQUIRED) — one of `2K`, `4K`, `6K`, `8K`,
`10K`, `12K`, `14K`, `16K`, `20K`, `24K`, `28K`, `32K`, `38K`.
Classes above 16K are only valid for `crystal`. The per-model
factor/area caps are validated before charging.
examples:
- 4K
options:
anyOf:
- $ref: '#/components/schemas/PublicUpscaleOptions'
- type: 'null'
description: >-
Per-model tuning options (typed). Only `magnific-creative` and
`magnific-precision` accept options — supplying `options` for
`seedvr`/`crystal` is a `422`.
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
Optional https webhook notified once on terminal status (signed per
the webhook signature scheme; see the webhooks docs).
examples:
- https://example.com/webhooks/samsa
type: object
required:
- image
- target_resolution
title: PublicUpscaleRequest
description: >-
`POST /images/upscales` body (SAM-819 / S8.7 — ADR §7, §8, §10).
Upscale ONE source `image` to a higher `target_resolution` with one of
the
four public models. The source is exactly one of `image_id` (an image in
your organization's context), an https `url`, or `base64`+`mime_type`.
`target_resolution` is a CLOSED set — the per-model factor/area caps are
validated BEFORE charging (an over-cap request is a `422`, never a
charged
job). `options` are per-model, typed, and STRICTLY validated
(out-of-range /
unknown values are `422` — a documented deviation from the app's
clamping).
Cost is the existing upscale estimator: the resolution tier
(2K:5, 4K:10, 6K:20, 8K:25, 10K:35, 12K:45, 14K:60, 16K:80) x the model
credit multiplier (Magnific x3); Crystal above 12K prices by output
megapixels. `estimated_credits` in the 202 equals the deduction exactly.
examples:
- image:
image_id: 123e4567-e89b-12d3-a456-426614174000
model: crystal
target_resolution: 4K
- image:
url: https://cdn.example.com/photo.png
model: seedvr
target_resolution: 2K
- image:
image_id: 123e4567-e89b-12d3-a456-426614174000
model: magnific-creative
options:
magnific_creative:
creativity: 2
engine: magnific_sharpy
hdr: 1
optimized_for: films_n_photography
prompt: sharp studio product photo
target_resolution: 8K
webhook_url: https://example.com/webhooks/samsa
- image:
base64: iVBORw0KGgoAAAANSUhEUg...
mime_type: image/png
model: magnific-precision
options:
magnific_precision:
flavor: photo
sharpen: 20
ultra_detail: 40
target_resolution: 6K
PublicTransformAccepted:
properties:
id:
type: string
format: uuid
title: Id
description: The job id — poll the op's `GET .../{id}` endpoint.
status:
$ref: '#/components/schemas/PublicImageStatus'
description: >-
Initial status: `pending` (job queued — enter the polling flow), or
`completed` with `estimated_credits: 0` when `background-removals` /
`vectorizations` serve an owned-image cache hit (the result is
immediately available).
examples:
- pending
estimated_credits:
type: integer
title: Estimated Credits
description: >-
Credits this job is expected to cost — `0` on a cache-hit
`completed` response.
examples:
- 5
type: object
required:
- id
- status
- estimated_credits
title: PublicTransformAccepted
description: >-
Shared `202` body for the transform-op submits (SAM-813 / S8 wave).
Every `POST /images/` returns the async job handle
`{id, status, estimated_credits}`. The initial `status` is `pending`
(the
job is queued), with ONE exception: `background-removals` and
`vectorizations` answer an owned-`image_id` cache hit (a ready result
already exists for that image) with `status: "completed"` and
`estimated_credits: 0` — no new job is queued, the `completed` webhook
event is emitted immediately for a supplied `webhook_url`, and the
result
is already available from the op's `GET .../{id}` endpoint. The other
transform ops (`img2img`, `variations`, `resizes`, `upscales`) always
start `pending`.
ErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorEnvelope
description: The complete public error body — an ``error`` object wrapper (ADR §5).
PublicImageEditSource:
properties:
image_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Image Id
description: Id of an image in your organization's context to edit.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: https URL of the source image (downloaded under SSRF guards).
examples:
- https://cdn.example.com/photo.png
base64:
anyOf:
- type: string
- type: 'null'
title: Base64
description: Base64-encoded source image bytes (send with `mime_type`).
mime_type:
anyOf:
- type: string
- type: 'null'
title: Mime Type
description: >-
MIME type for a base64 source — one of: image/jpeg, image/png,
image/webp.
examples:
- image/png
type: object
title: PublicImageEditSource
description: >-
The source image for an edit — exactly one of three modes (ticket §1).
* `image_id` — an image already in the key creator's context (owned by
the key
creator; ownership is enforced in the route -> `404` on a miss).
* `url` — an `https` URL the server downloads under the SSRF guard
(§7.4).
* `base64` + `mime_type` — inline bytes (`mime_type` in the allow-list).
Exactly one mode must be supplied; zero or more than one is a `422`.
`url` / `base64` rasters must decode to at most **33,554,432 pixels**
(32 MP, width x height) — a larger source returns `422` naming the
source
param, before any charge (same ceiling the resize op documents).
PublicUpscaleOptions:
properties:
magnific_creative:
anyOf:
- $ref: '#/components/schemas/PublicUpscaleMagnificCreativeOptions'
- type: 'null'
description: Options for the `magnific-creative` model.
magnific_precision:
anyOf:
- $ref: '#/components/schemas/PublicUpscaleMagnificPrecisionOptions'
- type: 'null'
description: Options for the `magnific-precision` model.
additionalProperties: false
type: object
title: PublicUpscaleOptions
description: >-
Per-model upscale options — supply the subobject matching `model`.
`magnific_creative` for the `magnific-creative` model,
`magnific_precision`
for `magnific-precision`. `seedvr` and `crystal` take NO options
(supplying
`options` for them is a 422). `extra="forbid"` rejects unknown keys.
PublicImageStatus:
type: string
enum:
- pending
- processing
- completed
- failed
- cancelled
title: PublicImageStatus
description: >-
Public image-job status — the lower-cased internal ``TaskStatus``.
Deliberately the plain lower-cased internal value (NOT the ADR §7.2
``PENDING -> queued`` remap): the ticket's 202 uses ``status:
"pending"`` and
its fixtures say ``pending/processing/completed/failed``, and this keeps
the
public surface consistent with the already-shipped models API
(``PublicModelStatus``).
ErrorDetail:
properties:
type:
type: string
title: Type
examples:
- authentication_error
code:
type: string
title: Code
examples:
- invalid_api_key
message:
type: string
title: Message
examples:
- The provided API key is invalid, expired, or revoked.
request_id:
type: string
title: Request Id
examples:
- 8f14e45fceea167a5a36dedd4bea2543
param:
anyOf:
- type: string
- type: 'null'
title: Param
description: Present on validation errors — names the offending field.
examples:
- aspect_ratio
type: object
required:
- type
- code
- message
- request_id
title: ErrorDetail
description: The ``error`` object of the public envelope (ADR §5).
PublicUpscaleMagnificCreativeOptions:
properties:
prompt:
type: string
maxLength: 500
title: Prompt
description: Guidance for the upscaler (<= 500 chars).
default: ''
optimized_for:
type: string
enum:
- standard
- soft_portraits
- hard_portraits
- art_n_illustration
- videogame_assets
- nature_n_landscapes
- films_n_photography
- 3d_renders
- science_fiction_n_horror
title: Optimized For
description: Content preset the model optimizes for.
default: standard
creativity:
type: integer
maximum: 10
minimum: -10
title: Creativity
description: Creativity (-10..10).
default: 0
hdr:
type: integer
maximum: 10
minimum: -10
title: Hdr
description: HDR (-10..10).
default: 0
resemblance:
type: integer
maximum: 10
minimum: -10
title: Resemblance
description: Resemblance to source (-10..10).
default: 0
fractality:
type: integer
maximum: 10
minimum: -10
title: Fractality
description: Fractality / detail spread (-10..10).
default: 0
engine:
type: string
enum:
- automatic
- magnific_illusio
- magnific_sharpy
- magnific_sparkle
title: Engine
description: Magnific rendering engine.
default: automatic
additionalProperties: false
type: object
title: PublicUpscaleMagnificCreativeOptions
description: >-
`magnific-creative` tuning knobs (strict — out-of-range/unknown -> 422).
Every field has a documented default, so a PARTIAL object fills the rest
(`_validate_model_params` mirror). `extra="forbid"` rejects unknown
keys.
PublicUpscaleMagnificPrecisionOptions:
properties:
sharpen:
type: integer
maximum: 100
minimum: 0
title: Sharpen
description: Sharpen (0..100).
default: 7
smart_grain:
type: integer
maximum: 100
minimum: 0
title: Smart Grain
description: Smart grain (0..100).
default: 7
ultra_detail:
type: integer
maximum: 100
minimum: 0
title: Ultra Detail
description: Ultra detail (0..100).
default: 30
flavor:
type: string
enum:
- sublime
- photo
- photo_denoiser
title: Flavor
description: Precision flavor (drives the per-flavor output-size caps).
default: sublime
additionalProperties: false
type: object
title: PublicUpscaleMagnificPrecisionOptions
description: >-
`magnific-precision` tuning knobs (strict — out-of-range/unknown ->
422).
`flavor` drives the per-flavor output caps; an omitted flavor defaults
to
`sublime` (the tightest, safest cap — mirrors
`PRECISION_DEFAULT_FLAVOR`).
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Organization API key as a bearer token: `Authorization: Bearer
samsa_sk_...`.
````