Generate images
Turn a prompt into images, optionally composing your organization’s trained
style, object, person, and setting models and color palettes.
Magic Edit
Edit an existing image from a prompt — with or without a mask — and reuse the
same trained models for on-brand results.
Transform images
Run img2img, generate variations, resize by outpainting, upscale to high
resolution, remove a background, or vectorize to SVG — one tool per operation.
Create video
Produce video from a start frame, from text, or from text styled with your
trained models — all as a single tool call.
Track jobs & credits
Poll any job to completion and read your organization’s remaining credit
balance — reads are always free.
Server URL — add this one endpoint to any MCP client:
/mcp, no trailing slash) serves
both authentication modes. The transport is stateless: every tool call returns a
single JSON response, and generation tools return a job id immediately so nothing
holds a long-lived stream open.
Get connected in three steps
1
Get your credentials
Interactive apps — Claude, ChatGPT, and Microsoft Copilot
(through Copilot Studio) — sign in with OAuth; you approve a consent screen
in the Samsa app and never paste a key. Headless clients — Claude Code,
Cursor, n8n, SDKs — use an API key created in
Settings → API Keys.
2
Add the server
Point your client at
https://api.samsa.ai/mcp. There’s nothing to install
and no local process — see Connect your client for
the exact one-time setup.3
Start creating
Your client lists the fifteen Samsa tools. Ask it to generate an image,
run a Magic Edit, transform or upscale an image, make a video, or create and
update your trained models — it submits each job and polls the async ones to
completion for you.
Authentication
The MCP endpoint accepts two credential types on the same URL. Pick the one that matches your client:
Both act for an organization: credits are drawn from that organization’s pool
and generated assets appear in the app under the connected account. See
Authentication for how keys, scopes, and organizations
work.
OAuth sign-in follows the standard MCP flow: the client discovers Samsa’s
authorization server from the
401 challenge, registers itself dynamically
(PKCE, no client secret), and sends you through a consent screen before
exchanging a short-lived access token. If a sign-in doesn’t complete, tell us
at support@samsa.ai.The async pattern
The nine credit-costing media tools are asynchronous — they enqueue a job and return right away, so your client never blocks waiting for a render.create_model
is a tenth async submit tool (poll get_job_status(kind="model", …)) but it is free.
1
Submit
Call any submit tool —
generate_image, edit_image, img2img,
create_variations, resize_image, upscale_image, remove_background,
vectorize_image, or generate_video. It returns
{ id, status: "pending", estimated_credits, next_step } in milliseconds, and
the estimated credits are deducted from your organization’s pool at submit.2
Poll
Call
get_job_status(kind=…, id=…) with the id you received and the kind the
submit tool named. The status moves pending → processing → completed
(or failed). Image jobs typically finish in 30 seconds to two minutes; video
in one to five.3
Collect
Once
completed, the response carries presigned result URLs valid for 24
hours. If a job ends failed on Samsa’s side, the credits are automatically
refunded to the same pool.remove_background and vectorize_image are cached per source image: when the
source is an image_id you own that already has a result, the call skips the queue
and returns { status: "completed", estimated_credits: 0 } immediately — no credits
and no concurrency slot consumed.Read next
Tools
The fifteen tools, their parameters, scopes, and what each costs.
Connect your client
One-time setup for Claude, ChatGPT, Cursor, VS Code, n8n, and more.
Troubleshooting
Security and credits, and how to read a rejected call.
See also
Authentication
Organization keys, scopes, and the Bearer header.
Pricing
How image, edit, and video credits are calculated.
Rate limits
Per-key rate, per-org concurrency, and back-off.
API reference
The REST surface behind the same tools.