Skip to main content
This page covers the conventions that apply to every endpoint. The full, endpoint-by-endpoint reference — generated from the API’s OpenAPI specification — is in the groups in the sidebar: Image Generation, Image Editing, Video Generation, Model Training, Models, and Account & Usage. For a working end-to-end example, see the quickstart.

​
Base URL

https://api.samsa.ai/public/v1
Preview environments mirror the same surface on https://preview.api.samsa.ai/public/v1.

​
Authentication

Every request must carry an organization API key as a bearer token: 
Authorization: Bearer samsa_sk_your_key_here
Keys are organization-owned, scoped, and shown once at creation. See Create an API key to get one.

​
Conventions

  • Asynchronous jobs — generation endpoints return 202 Accepted with a job id; poll the matching GET endpoint for status, or supply a webhook_url to be notified on completion.
  • Statuses — jobs move through pending, processing, and then a terminal completed, failed, or cancelled.
  • Scopes — most endpoints require a scope on the key (for example, images.generate); GET /me needs only a valid key. A key missing a required scope receives 403.
  • Errors — non-2xx responses return a structured JSON error body with a type, code, message, and request_id.
  • Credits — actions draw from the organization’s credit pool; an exhausted pool returns 402.
  • Rate limits — requests are limited per key; exceeding the limit returns 429 with a Retry-After header.