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

# Riferimento API

> L'API REST pubblica di Samsa — base URL, autenticazione e convenzioni.

<Info>
  Questa pagina copre le convenzioni valide per ogni endpoint. Il riferimento
  completo, endpoint per endpoint — generato dalla specifica OpenAPI dell'API —
  si trova nei gruppi nella barra laterale:
  [Generazione di immagini](/it/api-reference/images/overview),
  [Modifica di immagini](/it/api-reference/edits/overview),
  [Generazione di video](/it/api-reference/videos/overview),
  [Addestramento di modelli](/it/api-reference/model-training/overview),
  [Modelli](/it/api-reference/models/overview) e
  [Account & utilizzo](/it/api-reference/account/overview). Per un esempio
  completo end-to-end, vedi il [quickstart](/it/quickstart).
</Info>

## Base URL

```
https://api.samsa.ai/public/v1
```

## Autenticazione

Ogni richiesta deve includere una API key dell'organizzazione come bearer token:

```
Authorization: Bearer samsa_sk_your_key_here
```

Le key appartengono all'organizzazione, sono dotate di scope e vengono mostrate
una sola volta alla creazione. Vedi
[Crea una API key](/it/quickstart) per ottenerne una.

## Convenzioni

* **Job asincroni** — gli endpoint di generazione restituiscono `202 Accepted`
  con un `id` del job; interroga l'endpoint `GET` corrispondente per lo stato,
  oppure fornisci un `webhook_url` per essere notificato al completamento.
* **Stati** — i job attraversano `pending`, `processing` e poi uno stato
  terminale `completed`, `failed` o `cancelled`.
* **Scope** — la maggior parte degli endpoint richiede uno scope sulla key (per
  esempio, `images.generate`); `GET /me` richiede solo una key valida. Una key a
  cui manca uno scope richiesto riceve `403`.
* **Errori** — le risposte non-2xx restituiscono un corpo di errore JSON
  strutturato con `type`, `code`, `message` e `request_id`.
* **Credits** — le azioni attingono dal pool di credits dell'organizzazione; un
  pool esaurito restituisce `402`.
* **Rate limit** — le richieste sono limitate per key; il superamento del limite
  restituisce `429` con un header `Retry-After`.