> ## 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.

# Generare variazioni

> Invia un job di variazioni — un'immagine sorgente, facoltativamente guidata — e ottieni un id del job.

Genera variazioni creative di una `image` sorgente. La chiamata restituisce
**`202 Accepted`** con un `id` del job; interroga
[`GET /images/variations/{id}`](/it/api-reference/image-ops/get-variations) 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à

<CodeGroup>
  ```bash image_id theme={null}
  curl -X POST https://api.samsa.ai/public/v1/images/variations \
    -H "Authorization: Bearer $SAMSA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" } }'
  ```

  ```bash url theme={null}
  curl -X POST https://api.samsa.ai/public/v1/images/variations \
    -H "Authorization: Bearer $SAMSA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "image": { "url": "https://cdn.example.com/photo.png" },
      "target": "object",
      "creativity": "subtle",
      "num_outputs": 4,
      "variation_instructions": "Try different background colors"
    }'
  ```

  ```bash base64 theme={null}
  curl -X POST https://api.samsa.ai/public/v1/images/variations \
    -H "Authorization: Bearer $SAMSA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "image": { "base64": "iVBORw0KGgoAAAANSUhEUg...", "mime_type": "image/png" },
      "preservation_instructions": "Keep the product shape unchanged",
      "webhook_url": "https://example.com/webhooks/samsa"
    }'
  ```
</CodeGroup>

La risposta `202` è l'handle del job asincrono:

```json 202 Accepted theme={null}
{
  "id": "c4d5e6f7-8a9b-4c1d-2e3f-4a5b6c7d8e9f",
  "status": "pending",
  "estimated_credits": 5
}
```

<Note>
  Invia **esattamente una** modalità sorgente in `image`. `target` — cosa possono
  cambiare le variazioni — è `everything` (predefinito), `person`, `object` o
  `scene`. `creativity` è `subtle` o `creative` (predefinito).
  `variation_instructions` (cosa cambiare) e `preservation_instructions` (cosa
  mantenere) sono testo libero facoltativo, ≤ 2000 caratteri ciascuno. `num_outputs`
  (1–4) è **1** per impostazione predefinita e ogni output viene addebitato. Non c'è
  un parametro `resolution` — la risoluzione di output è **ereditata dalla
  sorgente**.
</Note>

## Credits

Ogni output costa `5` credits a `1K`, con scalatura in base al livello di risoluzione
dell'**immagine sorgente** (`1K` ×1, `2K` ×2, `4K` ×4) e moltiplicato per
`num_outputs`. 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`/`creativity` non valido o istruzioni troppo lunghe.                                                                                                                                                                                                                                                                                                           |
| `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/variations
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/variations:
    post:
      tags:
        - Images
      summary: Generate creative variations of an image
      description: >-
        Submits an image-variations job — one source `image` — and returns `202`
        immediately with the job `id` and a credit estimate; poll `GET
        /images/variations/{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`. Optional `target` (`everything` default, `person`,
        `object`, `scene`), `creativity` (`subtle`, `creative` default),
        free-text `variation_instructions` / `preservation_instructions` (<=
        2000 chars each), and `num_outputs` (1-4, default **1**). The output
        **resolution is inherited from the source image** (there is no
        `resolution` parameter): the credit multiplier is the source's
        resolution tier, so each output is billed at `5 x resolution_multiplier`
        credits (1K:1x, 2K:2x, 4K:4x). A source with no recoverable dimensions
        prices at `1K`. Common errors: an invalid `target`/`creativity` or an
        over-long instruction 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_variations_images_variations_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicVariationsRequest'
        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:
    PublicVariationsRequest:
      properties:
        image:
          $ref: '#/components/schemas/PublicImageEditSource'
          description: >-
            The source image: exactly one of `image_id`, `url`, or
            `base64`+`mime_type`.
        target:
          type: string
          enum:
            - everything
            - person
            - object
            - scene
          title: Target
          description: >-
            What the variations may change: `everything` (default), `person`,
            `object`, or `scene`.
          default: everything
          examples:
            - everything
        creativity:
          type: string
          enum:
            - subtle
            - creative
          title: Creativity
          description: >-
            How far the variations may deviate from the source: `subtle` or
            `creative` (default).
          default: creative
          examples:
            - creative
        variation_instructions:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Variation Instructions
          description: Optional free-text guidance for WHAT to change (<= 2000 chars).
          examples:
            - Try different background colors and lighting
        preservation_instructions:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Preservation Instructions
          description: Optional free-text guidance for WHAT to keep (<= 2000 chars).
          examples:
            - Keep the product label and shape unchanged
        num_outputs:
          type: integer
          maximum: 4
          minimum: 1
          title: Num Outputs
          description: >-
            Number of variations to generate (1-4). Defaults to **1** (the app
            default is 4); each output is billed.
          default: 1
          examples:
            - 1
        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
      title: PublicVariationsRequest
      description: >-
        `POST /images/variations` body (SAM-816 / S8.4 — ADR §8, §10).


        Generate creative variations of ONE source `image` (the app's Gemini 3
        Pro

        variations flow). The source is exactly one of `image_id` (an image in
        your

        organization's context), an https `url`, or `base64`+`mime_type`. The
        output

        resolution is **inherited from the source** (there is no `resolution`
        param);

        each output is billed at `5 x resolution_multiplier` credits (1K:1x,
        2K:2x,

        4K:4x) where the multiplier is the source image's resolution tier.
        `target`

        and `creativity` are lowercase public aliases of the internal Gemini

        variation controls; `num_outputs` defaults to **1** (the app default is
        4).
      examples:
        - image:
            image_id: 123e4567-e89b-12d3-a456-426614174000
        - creativity: subtle
          image:
            url: https://cdn.example.com/photo.png
          num_outputs: 4
          target: object
          variation_instructions: Try different background colors
        - image:
            base64: iVBORw0KGgoAAAANSUhEUg...
            mime_type: image/png
          preservation_instructions: Keep the product shape unchanged
          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/<op>` 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).
    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_...`.

````