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

> Generate images, edit them, produce video, and train custom models — programmatically, from your organization's Samsa account.

The **Samsa API** brings Samsa's generative image and video studio to your own
applications. Authenticate with an organization API key, submit a job, and poll
for the result — the same models, trained assets, and credit pool your team
already uses in the app, now available over a clean REST interface and a remote
[MCP server](/mcp).

<Info>
  **Base URL** — all REST endpoints live under

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

  Preview environments mirror the surface on `https://preview.api.samsa.ai/public/v1`.
</Info>

## Start here

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create a key and generate your first image in five steps, with copy-paste
    curl, Python, and TypeScript.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference/introduction">
    The base URL, authentication, and the conventions every endpoint shares.
  </Card>

  <Card title="Create an API key" icon="key" href="/quickstart#create-an-api-key">
    Keys are organization-owned, scoped, and shown once. An org admin creates
    them in your Samsa settings.
  </Card>

  <Card title="MCP server" icon="plug" href="/mcp">
    Connect Samsa to ChatGPT, Claude, or any MCP client over OAuth or an API key.
  </Card>
</CardGroup>

## What you can build

<CardGroup cols={2}>
  <Card title="Image generation" icon="image">
    Turn a prompt into images, optionally composing your organization's trained
    **style**, **object**, **person**, and **setting** models and color palettes.
  </Card>

  <Card title="Magic Edit" icon="wand-magic-sparkles">
    Edit an existing image with a prompt — with or without a mask — and reuse the
    same trained models for on-brand results.
  </Card>

  <Card title="Video generation" icon="clapperboard">
    Produce video from a start frame (with an optional end frame), from text, or
    from text styled with your trained models.
  </Card>

  <Card title="Model training" icon="graduation-cap">
    Create custom models in four categories — style, object, person, and setting —
    from a handful of reference images.
  </Card>
</CardGroup>

Every generation endpoint is **asynchronous**: a `POST` returns `202 Accepted`
with a job `id`, you poll the matching `GET` endpoint for status, and — once the
job is `completed` — the response carries presigned URLs to the finished assets.
You can also pass a `webhook_url` to be notified on completion instead of polling.

## Authentication

Send your key as a bearer token on every request:

```
Authorization: Bearer samsa_sk_your_key_here
```

Keys carry **scopes** (`images.generate`, `images.edit`, `videos.generate`,
`models.read`, `models.write`, `usage.read`) and act for the key's organization —
credits are drawn from that organization's pool and generated assets appear in the
app under the key creator's account. See the [quickstart](/quickstart) to create
your first key.

## Model Context Protocol (MCP)

Samsa also exposes a remote **MCP server** so agentic clients can generate and
edit media as tools:

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

The MCP endpoint supports **dual authentication** — OAuth 2.1 (with a consent
screen in the Samsa app) for interactive clients such as ChatGPT and Claude, and
`Authorization: Bearer <api key>` for headless clients such as scripts and n8n.
See the [MCP server guide](/mcp) for the tool catalog and per-client setup.

## Credits and pricing

API actions draw from your organization's existing Samsa credit pool at the same
rates as the app — for example, image generation costs `5` credits per output at
`1K`, scaling with resolution (`1K` ×1, `2K` ×2, `4K` ×4). When the pool is
exhausted, requests return `402`. Check your balance any time with
`GET /credits` or `GET /me`.