> ## 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 and transform 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-server).

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

  ```
  https://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-server">
    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" href="/api-reference/images/overview">
    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" href="/api-reference/edits/overview">
    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="Image operations" icon="wand-sparkles" href="/api-reference/image-ops/overview">
    Transform an image you already have — img2img, variations, resize by
    outpainting, upscale, background removal, and vectorization to SVG.
  </Card>

  <Card title="Video generation" icon="clapperboard" href="/api-reference/videos/overview">
    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" href="/api-reference/model-training/overview">
    Create custom models in four categories — style, object, person, and setting —
    from a handful of reference images.
  </Card>

  <Card title="Account & usage" icon="chart-line" href="/api-reference/account/overview">
    Introspect a key, read the credit balance it can spend, and review your
    organization's API usage.
  </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`, `images.transform`,
`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,
edit, and transform 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-server) 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 what a key can spend any time with
[`GET /credits`](/api-reference/account/credits) — organizations that reserve credits
as per-team budgets get a per-key balance there, not just the organization total.