Skip to main content
This guide takes you from zero to a finished image in five steps: create a key, verify it, submit a generation, poll for the result, and download it. Every call targets the base URL: 
https://api.samsa.ai/public/v1
The examples use a fake key (samsa_sk_example…) and placeholder ids. Replace them with your own. Store your key in an environment variable so it never lands in source control:
export SAMSA_API_KEY="samsa_sk_exampleXf9Lp2QyaBcDeFgHiJkLmNoPqRsTuVwx"

​
Create an API key

API keys are organization-owned and can only be created by an organization admin (OWNER or ADMIN).
1

Open your organization settings

In the Samsa app, go to your organization settings and open the API Keys tab.
2

Create a key

Give the key a name. By default it is granted all scopes (images.generate, images.edit, videos.generate, models.read, models.write, usage.read); narrow them if the integration needs less. You can also set an optional expiry.
3

Copy the key now

The full key (samsa_sk_…) is shown exactly once, at creation. Samsa stores only a hash and can never display it again. Copy it immediately and keep it somewhere safe — if you lose it, revoke the key and create a new one.
Keys act for their organization: credits are drawn from the organization’s pool, and any images or videos you generate appear in the app under the account of the admin who created the key.

​
Verify the key with GET /me

GET /me is the fastest way to confirm a key works. It returns the key’s organization, its safe metadata (prefix, scopes, expiry — never the secret), and the organization’s available credit balance. 
curl https://api.samsa.ai/public/v1/me \
  -H "Authorization: Bearer $SAMSA_API_KEY"
Response
{
  "organization": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Inc"
  },
  "api_key": {
    "id": "9c8d7e6f-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
    "name": "Production key",
    "prefix": "samsa_sk_exam",
    "scopes": [
      "images.edit",
      "images.generate",
      "models.read",
      "models.write",
      "usage.read",
      "videos.generate"
    ],
    "expires_at": null
  },
  "credits": {
    "available": 1450
  }
}

​
Generate an image

Submit a prompt to POST /images/generations. Here we also compose one of the organization’s trained style models by passing its id as style_id — you can combine object_ids, person_ids, setting_ids, and a color_palette_id the same way. The request returns 202 immediately with a job id; the image is produced asynchronously. 
curl -X POST https://api.samsa.ai/public/v1/images/generations \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist product shot of a ceramic mug on linen, soft daylight",
    "style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "num_outputs": 1
  }'
Response — 202 Accepted
{
  "id": "7f9c0e2a-1b3d-4c5e-8f6a-9b0c1d2e3f40",
  "status": "pending",
  "estimated_credits": 5
}
The default engine is nano_banana_pro (pass engine to choose nano_banana_2). num_outputs defaults to 1; each output costs 5 credits at 1K, scaling with resolution (1K ×1, 2K ×2, 4K ×4). The style_id must reference a completed model in your organization.

​
Poll for the result

Poll GET /images/generations/{id} until status is completed (or failed). Statuses are pending, processing, completed, failed, and cancelled. 
curl https://api.samsa.ai/public/v1/images/generations/7f9c0e2a-1b3d-4c5e-8f6a-9b0c1d2e3f40 \
  -H "Authorization: Bearer $SAMSA_API_KEY"
Response — completed
{
  "id": "7f9c0e2a-1b3d-4c5e-8f6a-9b0c1d2e3f40",
  "status": "completed",
  "created_at": "2026-07-02T12:00:00Z",
  "credits_used": 5,
  "images": [
    {
      "id": "d4c3b2a1-6f5e-4b3a-9d8c-1e0f2a3b4c5d",
      "url": "https://cdn.samsa.ai/user-.../7f9c0e2a.png?X-Amz-Signature=...",
      "thumbnail_url": "https://cdn.samsa.ai/user-.../7f9c0e2a-thumb.png?X-Amz-Signature=...",
      "width": 1024,
      "height": 1024,
      "seed": 128390
    }
  ],
  "error": null
}

​
Download the result

Each entry in images carries a presigned HTTPS url that is valid for 24 hours — download and store the asset before it expires. 
curl -o mug.png \
  "https://cdn.samsa.ai/user-.../7f9c0e2a.png?X-Amz-Signature=..."

​
Next steps

API reference

The base URL, authentication, and the conventions every endpoint shares.

Run it locally

Preview and contribute to these docs with the Mintlify CLI.
Prefer push over polling? Pass a webhook_url on any generation request to receive a signed callback the moment the job reaches a terminal status.