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

# API Samsa

> Génère des images, édite-les, produis de la vidéo et entraîne des modèles personnalisés — le tout par programmation, depuis le compte Samsa de ton organisation.

L'**API Samsa** amène le studio génératif d'images et de vidéos de Samsa dans tes
propres applications. Authentifie-toi avec une API key d'organisation, envoie un
job et interroge le résultat — les mêmes modèles, assets entraînés et pool de
credits que ton équipe utilise déjà dans l'app, désormais accessibles via une
interface REST propre et un
[MCP server](/fr/mcp-server) distant.

<Info>
  **Base URL** — tous les endpoints REST vivent sous

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

## Commence ici

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/fr/quickstart">
    Crée une clé et génère ta première image en cinq étapes, avec du curl, du
    Python et du TypeScript prêts à copier-coller.
  </Card>

  <Card title="Référence API" icon="terminal" href="/fr/api-reference/introduction">
    La base URL, l'authentification et les conventions communes à chaque endpoint.
  </Card>

  <Card title="Créer une API key" icon="key" href="/fr/quickstart#créer-une-api-key">
    Les clés appartiennent à l'organisation, sont scopées et affichées une seule
    fois. Un admin de l'org les crée dans tes paramètres Samsa.
  </Card>

  <Card title="MCP server" icon="plug" href="/fr/mcp-server">
    Connecte Samsa à ChatGPT, Claude ou n'importe quel client MCP via OAuth ou une
    API key.
  </Card>
</CardGroup>

## Ce que tu peux construire

<CardGroup cols={2}>
  <Card title="Génération d'images" icon="image">
    Transforme un prompt en images, en composant éventuellement les modèles
    **style**, **objet**, **personne** et **décor** entraînés de ton organisation
    ainsi que des palettes de couleurs.
  </Card>

  <Card title="Magic Edit" icon="wand-magic-sparkles">
    Édite une image existante à partir d'un prompt — avec ou sans masque — et
    réutilise les mêmes modèles entraînés pour des résultats fidèles à ta marque.
  </Card>

  <Card title="Génération de vidéos" icon="clapperboard">
    Produis de la vidéo à partir d'une image de départ (avec une image de fin
    optionnelle), à partir de texte, ou à partir de texte stylisé avec tes modèles
    entraînés.
  </Card>

  <Card title="Entraînement de modèles" icon="graduation-cap">
    Crée des modèles personnalisés dans quatre catégories — style, objet, personne
    et décor — à partir d'une poignée d'images de référence.
  </Card>
</CardGroup>

Chaque endpoint de génération est **asynchrone** : un `POST` renvoie
`202 Accepted` avec un `id` de job, tu interroges le endpoint `GET` correspondant
pour connaître le statut, et — une fois le job `completed` — la réponse contient
les presigned URLs vers les assets terminés. Tu peux aussi passer un `webhook_url`
pour être notifié à la fin plutôt que d'interroger en boucle.

## Authentification

Envoie ta clé comme bearer token sur chaque requête :

```
Authorization: Bearer samsa_sk_your_key_here
```

Les clés portent des **scopes** (`images.generate`, `images.edit`,
`videos.generate`, `models.read`, `models.write`, `usage.read`) et agissent pour
l'organisation de la clé — les credits sont prélevés sur le pool de cette
organisation et les assets générés apparaissent dans l'app sous le compte du
créateur de la clé. Consulte le [quickstart](/fr/quickstart) pour créer ta
première clé.

## Model Context Protocol (MCP)

Samsa expose aussi un **MCP server** distant afin que les clients agentiques
puissent générer et éditer des médias sous forme d'outils :

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

Le endpoint MCP prend en charge une **double authentification** — OAuth 2.1 (avec
un écran de consentement dans l'app Samsa) pour les clients interactifs comme
ChatGPT et Claude, et `Authorization: Bearer <api key>` pour les clients headless
comme les scripts et n8n. Consulte le [guide MCP server](/fr/mcp-server) pour le
catalogue d'outils et la configuration par client.

## Credits et tarification

Les actions de l'API puisent dans le pool de credits Samsa existant de ton
organisation aux mêmes tarifs que l'app — par exemple, la génération d'images
coûte `5` credits par output en `1K`, mis à l'échelle selon la résolution (`1K`
×1, `2K` ×2, `4K` ×4). Quand le pool est épuisé, les requêtes renvoient `402`.
Consulte ton solde à tout moment avec `GET /credits` ou `GET /me`.