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

# Samsa API

> Genera immagini, modificale, produci video e addestra modelli personalizzati — a livello programmatico, dall'account Samsa della tua organizzazione.

La **Samsa API** porta lo studio generativo di immagini e video di Samsa nelle tue
applicazioni. Autenticati con una API key di organizzazione, invia un job e interroga
il risultato — gli stessi modelli, asset addestrati e pool di credits che il tuo team
usa già nell'app, ora disponibili tramite un'interfaccia REST pulita e un
[MCP server](/it/mcp-server) remoto.

<Info>
  **Base URL** — tutti gli endpoint REST vivono sotto

  ```
  https://api.samsa.ai/public/v1
  ```
</Info>

## Inizia qui

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/it/quickstart">
    Crea una chiave e genera la tua prima immagine in cinque passaggi, con esempi
    copia-incolla in curl, Python e TypeScript.
  </Card>

  <Card title="Riferimento API" icon="terminal" href="/it/api-reference/introduction">
    Il base URL, l'autenticazione e le convenzioni condivise da ogni endpoint.
  </Card>

  <Card title="Crea una API key" icon="key" href="/it/quickstart#crea-una-api-key">
    Le chiavi sono di proprietà dell'organizzazione, hanno degli scope e vengono
    mostrate una sola volta. Un admin dell'organizzazione le crea nelle tue
    impostazioni Samsa.
  </Card>

  <Card title="MCP server" icon="plug" href="/it/mcp-server">
    Connetti Samsa a ChatGPT, Claude o qualsiasi client MCP tramite OAuth o una API key.
  </Card>
</CardGroup>

## Cosa puoi costruire

<CardGroup cols={2}>
  <Card title="Generazione di immagini" icon="image">
    Trasforma un prompt in immagini, componendo facoltativamente i modelli
    **style**, **object**, **person** e **setting** addestrati dalla tua
    organizzazione e le palette di colori.
  </Card>

  <Card title="Magic Edit" icon="wand-magic-sparkles">
    Modifica un'immagine esistente con un prompt — con o senza maschera — e riusa gli
    stessi modelli addestrati per risultati fedeli al tuo brand.
  </Card>

  <Card title="Generazione di video" icon="clapperboard">
    Produci video da un frame iniziale (con un frame finale facoltativo), da testo o
    da testo stilizzato con i tuoi modelli addestrati.
  </Card>

  <Card title="Addestramento di modelli" icon="graduation-cap">
    Crea modelli personalizzati in quattro categorie — style, object, person e
    setting — a partire da una manciata di immagini di riferimento.
  </Card>
</CardGroup>

Ogni endpoint di generazione è **asincrono**: un `POST` restituisce `202 Accepted`
con un `id` del job, tu interroghi l'endpoint `GET` corrispondente per lo stato e —
una volta che il job è `completed` — la risposta contiene presigned URL agli asset
finiti. Puoi anche passare un `webhook_url` per essere notificato al completamento
invece di interrogare.

## Autenticazione

Invia la tua chiave come bearer token in ogni richiesta:

```
Authorization: Bearer samsa_sk_your_key_here
```

Le chiavi portano **scope** (`images.generate`, `images.edit`, `videos.generate`,
`models.read`, `models.write`, `usage.read`) e agiscono per l'organizzazione della
chiave — i credits vengono prelevati dal pool di quell'organizzazione e gli asset
generati appaiono nell'app sotto l'account di chi ha creato la chiave. Consulta il
[quickstart](/it/quickstart) per creare la tua prima chiave.

## Model Context Protocol (MCP)

Samsa espone anche un **MCP server** remoto affinché i client agentici possano
generare e modificare media come strumenti:

```
https://api.samsa.ai/mcp
```

L'endpoint MCP supporta l'**autenticazione doppia** — OAuth 2.1 (con una schermata di
consenso nell'app Samsa) per client interattivi come ChatGPT e Claude, e
`Authorization: Bearer <api key>` per client headless come script e n8n.
Consulta la [guida all'MCP server](/it/mcp-server) per il catalogo degli strumenti e
la configurazione per ciascun client.

## Credits e prezzi

Le azioni API prelevano dal pool di credits Samsa esistente della tua organizzazione
alle stesse tariffe dell'app — per esempio, la generazione di immagini costa `5`
credits per output a `1K`, scalando con la risoluzione (`1K` ×1, `2K` ×2, `4K` ×4).
Quando il pool è esaurito, le richieste restituiscono `402`. Controlla il tuo saldo in
qualsiasi momento con `GET /credits` o `GET /me`.