Image Compose API

Combine 1–3 reference images with a text prompt to synthesize a new image. Common use cases: place a character into a different scene, compose multiple products in one frame, style-transfer composites, and so on.

Editing a single image? Use the Image Edits API — outfit swaps, scene replacements, variants.

Pure text-to-image? Use the Image Generation API.

When to use which endpoint

Request

POST /v1/images/compose

Headers

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

x-api-key (Anthropic SDK style) is also supported.

Body

Reference image total: image_keys.length + generation_ids.length + image_urls.length must be between 1 and 3. All three arrays can be mixed. Duplicate references (including the same image across arrays) are rejected.

image_urls security constraints:

• https:// URLs must use HTTPS. Tokensmart blocks private / loopback / link-local / CGN addresses, blocks redirects, blocks userinfo (user:pass@host), validates the response Content-Type is image/(jpeg\|png\|gif\|webp), enforces a 30-second timeout, and caps each fetched image at 25MB.
• data: URIs must be a valid data:image/(jpeg\|png\|gif\|webp);base64,... string (≤35MB), decode to ≤25MB of raw bytes, and the file's magic bytes must match the declared MIME.
• Inline images flow through Workers memory only — they are NOT written to R2, do NOT count toward your 200MB file quota, and do NOT appear in /api/images/history.

Full Example

Compose two previously-generated images:

{
  "model": "gpt-image-2",
  "prompt": "Place the person from image 1 into the scene from image 2, keep clothing, unify lighting",
  "generation_ids": [
    "00000000-0000-0000-0000-000000000001",
    "00000000-0000-0000-0000-000000000002"
  ],
  "n": 1
}

Mix uploaded image with generated image:

{
  "model": "gpt-image-2",
  "prompt": "Print this logo on the product, on a white wooden table background",
  "image_keys": ["files/<userId>/<key>.png"],
  "generation_ids": ["<uuid>"],
  "n": 1
}

Pass base64 inline images (no upload step):

{
  "model": "gpt-image-2",
  "prompt": "Place the person from image 1 into the scene from image 2, keep clothing, unify lighting",
  "image_urls": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
  ],
  "n": 1
}

Or pass public HTTPS URLs:

{
  "model": "gpt-image-2",
  "prompt": "Place the person into this scene",
  "image_urls": [
    "https://example.com/portrait.jpg",
    "https://example.com/scene.jpg"
  ],
  "n": 1
}

Response

{
  "created": 1776864985,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ],
  "picklyone_generation_ids": ["00000000-0000-0000-0000-000000000099"]
}

Billing

Per-image billing, identical to the Image Generation API: actualCount × price_per_image. Pre-deduction freezes balance for the requested n; settlement charges for actually returned images; the difference is auto-refunded.

Python Example

import requests, base64

API_KEY = "pk_live_xxxxxxxxxxxxxxxx"
BASE = "https://api.tokensmart.ai"

resp = requests.post(
    f"{BASE}/v1/images/compose",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "Place the person from image 1 into the scene from image 2",
        "generation_ids": [
            "00000000-0000-0000-0000-000000000001",
            "00000000-0000-0000-0000-000000000002",
        ],
        "n": 1,
    },
    timeout=300,
).json()

for i, item in enumerate(resp.get("data", [])):
    if item.get("b64_json"):
        with open(f"out_{i}.png", "wb") as f:
            f.write(base64.b64decode(item["b64_json"]))
        print(f"saved out_{i}.png — generation_id: {resp['picklyone_generation_ids'][i]}")

cURL Example

curl https://api.tokensmart.ai/v1/images/compose \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Place the person from image 1 into the scene from image 2",
    "generation_ids": [
      "00000000-0000-0000-0000-000000000001",
      "00000000-0000-0000-0000-000000000002"
    ]
  }'

Node.js Example

import fs from "fs";

const API_KEY = "pk_live_xxxxxxxxxxxxxxxx";
const BASE = "https://api.tokensmart.ai";

const resp = await fetch(`${BASE}/v1/images/compose`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "...",
    image_keys: ["files/<userId>/<key>.png"],
    generation_ids: ["<uuid>"],
    n: 1,
  }),
}).then(r => r.json());

for (const [i, item] of resp.data.entries()) {
  if (item.b64_json) {
    fs.writeFileSync(`out_${i}.png`, Buffer.from(item.b64_json, "base64"));
  }
}

Limits

Error Codes

Notes

• b64_json is raw base64 (no data:image/png;base64, prefix) — decode directly with Buffer.from(b64, "base64") or Python base64.b64decode(b64)
• Auto-persisted to history — generated images are automatically saved to Tokensmart history and queryable via /api/images/history. The picklyone_generation_ids in the response are the persisted UUIDs.
• Chained composition — pass picklyone_generation_ids[i] from a prior call as a generation_id in the next call to iterate within the same context.

Related Endpoints

• File upload (used with image_keys): File Upload API
• Single-image edit: Image Edits API
• Text-to-image: Image Generation API