Generate images

Generate images from a prompt (and optional trained models)

curl --request POST \
  --url https://api.samsa.ai/public/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "person_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "setting_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "engine": "nano_banana_pro",
  "num_outputs": 1,
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "output_format": "png",
  "webhook_url": "https://example.com/webhooks/samsa"
}
'

import requests

url = "https://api.samsa.ai/public/v1/images/generations"

payload = {
    "prompt": "<string>",
    "style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "person_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "setting_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "engine": "nano_banana_pro",
    "num_outputs": 1,
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "output_format": "png",
    "webhook_url": "https://example.com/webhooks/samsa"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    style_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    object_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    person_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    setting_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    color_palette_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    engine: 'nano_banana_pro',
    num_outputs: 1,
    aspect_ratio: '1:1',
    resolution: '1K',
    output_format: 'png',
    webhook_url: 'https://example.com/webhooks/samsa'
  })
};

fetch('https://api.samsa.ai/public/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.samsa.ai/public/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'style_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'object_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'person_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'setting_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'color_palette_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'engine' => 'nano_banana_pro',
    'num_outputs' => 1,
    'aspect_ratio' => '1:1',
    'resolution' => '1K',
    'output_format' => 'png',
    'webhook_url' => 'https://example.com/webhooks/samsa'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.samsa.ai/public/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"object_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"person_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"setting_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"engine\": \"nano_banana_pro\",\n  \"num_outputs\": 1,\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"1K\",\n  \"output_format\": \"png\",\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"object_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"person_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"setting_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"engine\": \"nano_banana_pro\",\n  \"num_outputs\": 1,\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"1K\",\n  \"output_format\": \"png\",\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.samsa.ai/public/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"object_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"person_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"setting_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"engine\": \"nano_banana_pro\",\n  \"num_outputs\": 1,\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"1K\",\n  \"output_format\": \"png\",\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "estimated_credits": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

POST

images

generations

Generate images from a prompt (and optional trained models)

curl --request POST \
  --url https://api.samsa.ai/public/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "person_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "setting_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "engine": "nano_banana_pro",
  "num_outputs": 1,
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "output_format": "png",
  "webhook_url": "https://example.com/webhooks/samsa"
}
'

import requests

url = "https://api.samsa.ai/public/v1/images/generations"

payload = {
    "prompt": "<string>",
    "style_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "object_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "person_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "setting_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "color_palette_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "engine": "nano_banana_pro",
    "num_outputs": 1,
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "output_format": "png",
    "webhook_url": "https://example.com/webhooks/samsa"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    style_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    object_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    person_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    setting_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    color_palette_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    engine: 'nano_banana_pro',
    num_outputs: 1,
    aspect_ratio: '1:1',
    resolution: '1K',
    output_format: 'png',
    webhook_url: 'https://example.com/webhooks/samsa'
  })
};

fetch('https://api.samsa.ai/public/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.samsa.ai/public/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'style_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'object_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'person_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'setting_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'color_palette_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'engine' => 'nano_banana_pro',
    'num_outputs' => 1,
    'aspect_ratio' => '1:1',
    'resolution' => '1K',
    'output_format' => 'png',
    'webhook_url' => 'https://example.com/webhooks/samsa'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.samsa.ai/public/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"object_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"person_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"setting_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"engine\": \"nano_banana_pro\",\n  \"num_outputs\": 1,\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"1K\",\n  \"output_format\": \"png\",\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"object_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"person_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"setting_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"engine\": \"nano_banana_pro\",\n  \"num_outputs\": 1,\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"1K\",\n  \"output_format\": \"png\",\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.samsa.ai/public/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"style_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"object_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"person_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"setting_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"color_palette_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"engine\": \"nano_banana_pro\",\n  \"num_outputs\": 1,\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"1K\",\n  \"output_format\": \"png\",\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "estimated_credits": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

Submit a prompt to generate one to four images. The call returns 202 Accepted with a job id; poll GET /images/generations/{id} for the result. Combine your organization’s trained models by passing their ids or names — style_id, object_ids, person_ids, setting_ids — plus a color_palette_id. Each ref accepts a name or id that resolves to a model or palette visible to you.

Example: compose multiple trained models

Pass a style model, one or more person and setting models, and a color palette together in one request. Every model reference — by id or name — must resolve to a completed model visible to you.

curl -X POST https://api.samsa.ai/public/v1/images/generations \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Our founder presenting on stage at the product launch, cinematic lighting",
    "style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
    "person_ids": ["c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
    "setting_ids": ["a9b8c7d6-e5f4-4a3b-2c1d-0e1f2a3b4c5d"],
    "color_palette_id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
    "engine": "nano_banana_pro",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "num_outputs": 2
  }'

{
  "prompt": "Our founder presenting on stage at the product launch, cinematic lighting",
  "style_id": "2b9d1f7a-3c4e-4a5b-9c8d-0e1f2a3b4c5d",
  "person_ids": ["c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
  "setting_ids": ["a9b8c7d6-e5f4-4a3b-2c1d-0e1f2a3b4c5d"],
  "color_palette_id": "7f6e5d4c-3b2a-4c1d-9e8f-0a1b2c3d4e5f",
  "engine": "nano_banana_pro",
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "num_outputs": 2
}

object_ids, person_ids, and setting_ids are arrays; style_id and color_palette_id take a single value (a name or id). num_outputs (1–4) defaults to 1 and each output is billed. Omit engine to use the default nano_banana_pro. aspect_ratio accepts 1:1 (default), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, and 8:1; an unsupported ratio returns 422 before any credits are charged.

Authorizations

Authorization

string

header

required

Organization API key as a bearer token: Authorization: Bearer samsa_sk_....

Body

application/json

POST /images/generations body (ADR §8, §10).

Trained-model refs (style_id, object_ids, person_ids, setting_ids) and the color_palette_id color-palette ref combine on the Gemini path — each accepts a NAME or its UUID id, resolved within your visible set (a model/palette you own, including private ones, or a non-private one shared within your organization); setting_ids maps to the internal scene_ids (ADR §8.2). engine is a public-safe subset of the image engines (ADR §8.3). Note num_outputs defaults to 1 for API ergonomics — the internal app default is 4.

prompt

string

required

Text prompt. Runs the same validation as the app (rejects empty / malformed / policy-violating prompts with a 422).

Minimum string length: 1

Example:

"A minimalist product shot of a ceramic mug on linen, soft daylight"

style_id

A style model NAME or its UUID id (from list_models), resolved within your visible set — a model you own (including your own private models) or a non-private one shared with your organization. A name matching more than one visible model is rejected — pass the id. Must be completed.

object_ids

(string<uuid> | string)[]

object models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.

person_ids

(string<uuid> | string)[]

person models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id.

setting_ids

(string<uuid> | string)[]

setting models to compose in — each a model NAME or its UUID id (from list_models), resolved within your visible set (a model you own, including private, or a non-private one your organization shares). A name matching more than one visible model is rejected — pass the id. Maps to internal scenes.

color_palette_id

A color palette NAME or its UUID id, resolved within your visible set — a palette you created (including private ones) or a non-private palette shared with your organization. A name matching more than one visible palette is rejected — pass the id.

engine

string | null

Generation engine — one of nano_banana_pro (default) or nano_banana_2. Omit to use the default. Unknown engines return 422.

Example:

"nano_banana_pro"

num_outputs

integer

default:1

Number of images to generate (1-4). Defaults to 1 (the app default is 4); each output is billed.

Required range: 1 <= x <= 4

Example:

1

aspect_ratio

string

default:1:1

Aspect ratio for the generated image(s). One of 1:1 (default), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1. Unsupported ratios return 422 before any credits are charged.

Example:

"1:1"

resolution

string

default:1K

Output resolution — 1K, 2K, or 4K. Credits scale 1K:1x, 2K:2x, 4K:4x per output.

Example:

"1K"

output_format

enum<string>

default:png

Encoding of the returned images. v1 supports png only.

Available options:

png

Example:

"png"

webhook_url

string | null

Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).

Example:

"https://example.com/webhooks/samsa"

Response

Successful Response

202 body for POST /images/generations (ADR §7.1).

string<uuid>

required

The image job id — poll GET /images/generations/{id}.

status

enum<string>

required

Initial status: always pending at submit.

Available options:

pending,

processing,

completed,

failed,

cancelled

Example:

"pending"

estimated_credits

integer

required

Credits this job is expected to cost (base 5 x num_outputs x resolution multiplier).

Example:

5

Overview

Endpoints

Generate images

Example: compose multiple trained models

Authorizations

Body

Response

​Example: compose multiple trained models

Authorizations

Body

Response

Example: compose multiple trained models