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

# Référence API

> L'API REST publique de Samsa — base URL, authentification et conventions.

<Info>
  Cette page couvre les conventions qui s'appliquent à chaque endpoint. La
  référence complète, endpoint par endpoint — générée à partir de la spécification
  OpenAPI de l'API — se trouve dans les groupes de la barre latérale :
  [Génération d'images](/fr/api-reference/images/overview),
  [Édition d'images](/fr/api-reference/edits/overview),
  [Génération de vidéos](/fr/api-reference/videos/overview),
  [Entraînement de modèles](/fr/api-reference/model-training/overview),
  [Modèles](/fr/api-reference/models/overview) et
  [Compte & utilisation](/fr/api-reference/account/overview). Pour un exemple
  complet de bout en bout, consulte le [quickstart](/fr/quickstart).
</Info>

## Base URL

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

## Authentification

Chaque requête doit porter une API key d'organisation en tant que bearer token :

```
Authorization: Bearer samsa_sk_your_key_here
```

Les clés appartiennent à l'organisation, sont limitées par scope et affichées une
seule fois à la création. Voir
[Créer une API key](/fr/quickstart#créer-une-api-key) pour en obtenir une.

## Conventions

* **Jobs asynchrones** — les endpoints de génération renvoient `202 Accepted` avec
  un `id` de job ; interroge l'endpoint `GET` correspondant pour le statut, ou
  fournis un `webhook_url` pour être notifié à la fin.
* **Statuts** — les jobs passent par `pending`, `processing`, puis un état terminal
  `completed`, `failed` ou `cancelled`.
* **Scopes** — la plupart des endpoints exigent un scope sur la clé (par exemple,
  `images.generate`) ; `GET /me` ne nécessite qu'une clé valide. Une clé à laquelle
  il manque un scope requis reçoit `403`.
* **Erreurs** — les réponses non-2xx renvoient un corps d'erreur JSON structuré avec
  un `type`, un `code`, un `message` et un `request_id`.
* **Credits** — les actions puisent dans le pool de credits de l'organisation ; un
  pool épuisé renvoie `402`.
* **Rate limits** — les requêtes sont limitées par clé ; dépasser la limite renvoie
  `429` avec un header `Retry-After`.