> ## 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.
# Ein Bild resizen
> Reiche einen Resize-Job ein — ein Quellbild auf ein neues Seitenverhältnis (serverseitiges Outpainting).
Ändere die Größe eines Quell-`image` auf ein neues `aspect_ratio`. Resize ist ein
**serverseitiges Outpainting**: Das Backend rendert die Komposition und Maske aus
deiner Quelle im Zielverhältnis und füllt die neu freigelegte Leinwand mit einer
stilangepassten Erweiterung. Der Aufruf gibt **`202 Accepted`** mit einer Job-`id`
zurück; frage [`GET /images/resizes/{id}`](/de/api-reference/image-ops/get-resize)
nach dem Ergebnis ab. Das `image` nimmt **genau eines** von `image_id`, `url` oder
`base64` + `mime_type`. Erfordert den `images.transform`-Scope.
## Beispiel: eine Quelle pro Modus
```bash image_id theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/resizes \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"aspect_ratio": "16:9"
}'
```
```bash url theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/resizes \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "url": "https://cdn.example.com/portrait.png" },
"aspect_ratio": "1:1",
"resolution": "2K",
"placement": { "gravity": "top", "scale": 0.8 }
}'
```
```bash base64 theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/resizes \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "base64": "iVBORw0KGgoAAAANSUhEUg...", "mime_type": "image/png" },
"aspect_ratio": "21:9",
"num_outputs": 2,
"prompt": "extend the mountain range on both sides",
"webhook_url": "https://example.com/webhooks/samsa"
}'
```
Die `202`-Antwort ist das asynchrone Job-Handle:
```json 202 Accepted theme={null}
{
"id": "e6f7a8b9-0c1d-4e2f-3a4b-5c6d7e8f9a0b",
"status": "pending",
"estimated_credits": 5
}
```
`aspect_ratio` ist **erforderlich** und eines von `21:9`, `16:9`, `3:2`, `4:3`,
`5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`. `resolution` (`1K` Standard, `2K`, `4K`)
ist Provider-Metadata, die die Credits skaliert — die Leinwand wird immer mit einer
maximalen Kante von 1024px gerendert. `num_outputs` (1–4) ist standardmäßig **1**
und jedes Ergebnis (output) wird abgerechnet. `prompt` ist optionale Anleitung für
den neu generierten Bereich (validiert, wenn nicht leer). `placement` positioniert
die Quelle auf der Zielleinwand: `gravity` ist eines von `center` (Standard),
`top`, `bottom`, `left`, `right`, `top_left`, `top_right`, `bottom_left`,
`bottom_right`; `scale` liegt in `(0, 1]` (Standard `1.0` = maximaler
Contain-Fit).
**Leere-Maske-No-op.** Wenn das angeforderte `aspect_ratio` + `placement` (nahezu)
keinen neuen zu generierenden Bereich lassen — z. B. wenn die Quelle bei
`scale = 1` bereits dem Zielverhältnis entspricht — und kein `prompt` angegeben
ist, überspringt der Job das Modell, gibt die abgeflachte Komposition zurück und
**erstattet die ungenutzten Outputs**. Er `completes` dennoch.
## Credits
Jedes Ergebnis (output) kostet `5` Credits bei `1K` und skaliert mit der Auflösung
(`1K` ×1, `2K` ×2, `4K` ×4), multipliziert mit `num_outputs`. Siehe
[Preise](/de/guides/pricing).
## Fehler
| Status | Code | Wann |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402` | [`insufficient_credits`](/de/guides/errors#insufficient_credits) / [`insufficient_team_credits`](/de/guides/errors#insufficient_team_credits) / [`insufficient_unallocated_credits`](/de/guides/errors#insufficient_unallocated_credits) | Der Stand, den dieses Credential ausgeben kann, liegt unter den Job-Kosten. Organisationen mit mindestens einem aktiven Team erhalten statt `insufficient_credits` die team-bezogenen Codes (ausgenommen vom Team-Budgeting befreite System-Organisationen). Ein operativer Fehler in der Abbuchung selbst kann dennoch das generische `insufficient_credits` liefern, unabhängig vom Regime. |
| `402` | [`subscription_inactive`](/de/guides/errors#subscription_inactive) | Die Organisation hat kein nutzbares Abonnement. |
| `403` | [`missing_scope`](/de/guides/errors#missing_scope) | Dem Schlüssel fehlt der `images.transform`-Scope. |
| `404` | [`not_found`](/de/guides/errors#not_found) | Die Quell-`image_id` ist unbekannt oder gehört nicht dem Key-Ersteller — auch ein Bild, das ein anderes Mitglied deiner Organisation erstellt hat, ist ein `404`. |
| `422` | [`validation_error`](/de/guides/errors#validation_error) | Null/mehrere Quellmodi, fehlendes/ungültiges `aspect_ratio`, ungültiges `placement`, ein richtlinienverletzender `prompt` oder ein Quellraster über **33.554.432 Pixel** (32 MP, Breite × Höhe), das mit `param: image` vor jedem Rendering abgelehnt wird. |
| `429` | [`rate_limited`](/de/guides/errors#rate_limited) / [`too_many_active_jobs`](/de/guides/errors#too_many_active_jobs) | Pro-Schlüssel-Ratenfenster oder pro-Organisation-Concurrency-Limit überschritten. |
## OpenAPI
````yaml api-reference/openapi.json POST /images/resizes
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/resizes:
post:
tags:
- Images
summary: Resize an image to a new aspect ratio (server-side outpaint)
description: >-
Submits a resize job — one source `image` plus a target `aspect_ratio` —
and returns `202` immediately with the job `id` and a credit estimate;
poll `GET /images/resizes/{id}` for the result. The server renders the
composition and fills the newly exposed canvas with a style-matched
extension (this is the app's outpaint feature). The source is exactly
one of `image_id` (an image in your organization's context), an https
`url`, or `base64`+`mime_type`. `aspect_ratio` is REQUIRED (one of
`21:9`, `16:9`, `3:2`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`,
`9:16`). Optional `resolution` (`1K` default, `2K`, `4K` — the canvas is
always a 1024px max edge; the tier is provider metadata scaling credits
1K:1x, 2K:2x, 4K:4x), `num_outputs` (1-4, default **1**), free-text
`prompt` for the new area, and `placement` (`gravity` + `scale`)
positioning the source on the canvas. Each output is billed at `5 x
resolution_multiplier` credits. **Empty-mask no-op:** when the target
ratio + placement leave (almost) no new area to generate (e.g. the
source already matches the target ratio at `scale=1`) and no `prompt` is
given, the job skips the model, returns the flattened composition, and
refunds the unused outputs — it still `completes`. Common errors: an
unsupported `aspect_ratio`/`resolution` or a rejected `prompt` returns
`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_resize_images_resizes_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicResizeRequest'
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:
PublicResizeRequest:
properties:
image:
$ref: '#/components/schemas/PublicImageEditSource'
description: >-
The source image: exactly one of `image_id`, an https `url`, or
`base64`+`mime_type`. The source raster must be at most **33,554,432
pixels** (32 MP, width x height) — a larger source returns `422`
with `param: image` before any rendering. The composition canvas is
at most 1024px per edge, so higher-resolution sources gain no output
detail.
aspect_ratio:
type: string
title: Aspect Ratio
description: >-
Target aspect ratio (REQUIRED) — one of: `21:9`, `16:9`, `3:2`,
`4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `2:3`, `9:16`.
examples:
- '16:9'
resolution:
type: string
title: Resolution
description: >-
Provider resolution tier — `1K` (default), `2K`, or `4K`. The canvas
is always rendered at a 1024px max edge (per S8.5); the tier is
provider metadata that scales credits 1K:1x, 2K:2x, 4K:4x per
output.
default: 1K
examples:
- 1K
num_outputs:
type: integer
maximum: 4
minimum: 1
title: Num Outputs
description: >-
Number of images to generate (1-4). Defaults to **1**; each output
is billed.
default: 1
examples:
- 1
prompt:
type: string
title: Prompt
description: >-
Optional instruction for the newly generated area. When non-empty it
runs the app's prompt validation (rejects empty / malformed /
policy-violating prompts with a `422`).
default: ''
examples:
- extend the beach and the ocean horizon naturally
placement:
anyOf:
- $ref: '#/components/schemas/PublicResizePlacement'
- type: 'null'
description: >-
Optional placement of the source on the target canvas (`gravity` +
`scale`). Defaults to centered, maximum contain-fit.
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
- aspect_ratio
title: PublicResizeRequest
description: >-
`POST /images/resizes` body (SAM-818 / S8.6 — ADR §8, §10).
Resize = server-side outpaint: the backend renders the composition +
mask from
your source at the target `aspect_ratio` and fills the newly exposed
canvas
with a style-matched extension. The source is exactly one of `image_id`
(an
image in your organization's context), an https `url`, or
`base64`+`mime_type`.
`aspect_ratio` is REQUIRED (validated against the resize engine's
supported
list). `num_outputs` defaults to **1**; each output is billed at
`5 x resolution_multiplier` credits (1K:1x, 2K:2x, 4K:4x).
Empty-mask no-op: when the requested `aspect_ratio` + `placement` leave
(almost)
no new area to generate (e.g. the source already matches the target
ratio at
`scale=1`) and no `prompt` is given, the job SKIPS the model, returns
the
flattened composition, and REFUNDS the unused outputs — it still
`completes`.
examples:
- aspect_ratio: '16:9'
image:
image_id: 123e4567-e89b-12d3-a456-426614174000
- aspect_ratio: '1:1'
image:
url: https://cdn.example.com/portrait.png
placement:
gravity: top
scale: 0.8
resolution: 2K
- aspect_ratio: '21:9'
image:
base64: iVBORw0KGgoAAAANSUhEUg...
mime_type: image/png
num_outputs: 2
prompt: extend the mountain range on both sides
webhook_url: https://example.com/webhooks/samsa
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).
PublicResizePlacement:
properties:
gravity:
type: string
title: Gravity
description: >-
Placement of the source on the target canvas — one of: center, top,
bottom, left, right, top_left, top_right, bottom_left, bottom_right.
default: center
examples:
- center
scale:
type: number
maximum: 1
exclusiveMinimum: 0
title: Scale
description: Contain-fit scale in (0, 1]; 1.0 = fill the canvas edge-to-edge.
default: 1
examples:
- 1
type: object
title: PublicResizePlacement
description: >-
Where the source sits on the resized canvas (S8.5 geometry).
``gravity`` is one of the nine positions; ``scale`` in ``(0, 1]``
shrinks the
contain-fit placement (1.0 = maximum contain-fit).
``build_resize_composition``
re-validates both (the geometry authority) — these validators give a
clean,
param-scoped ``422`` at request parse.
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).
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Organization API key as a bearer token: `Authorization: Bearer
samsa_sk_...`.
````