Image

Two routes over the same model: one starts from a prompt alone, the other starts from images you supply. Both return the image as base64 in the response body.

Generation#

application/json. A prompt in, a PNG out.

curl -X POST "https://api.trystac.com/v1/images/generations" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a white dress shirt folded on a wooden table",
    "size": "1024x1024",
    "seed": 42
  }'

This route takes no input image. Sending one returns 400 wrong_route_for_reference_image — use /v1/images/edits instead.

Editing#

multipart/form-data. One to four reference images, plus a prompt describing the change.

curl -X POST "https://api.trystac.com/v1/images/edits" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F "prompt=make it black and white" \
  -F "size=1024x1024" \
  -F "image[]=@photo.png"

The file field accepts both image and image[] — the second is what OpenAI's own examples use for multiple files. Up to 4 images, 5 MiB each, in PNG, JPEG or WEBP. The format is read from the file's contents, not from its extension or the part's Content-Type. The whole multipart body is capped at 21 MiB.

Reference images are converted to RGB on arrival, which drops the alpha channel, colour profiles, and EXIF metadata — including any location data the original file carried.

mask is not supported and returns 400. The pod loads a single pipeline, and applying the edit to the whole image while pretending to honour a mask would be worse than refusing.

Parameters#

The same fields on both routes — as JSON on /generations, as form fields on /edits.

Response#

Identical on both routes.

{
  "created": 1767225600,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "meta": {
    "prompt": "a white dress shirt folded on a wooden table",
    "width": 1024,
    "height": 1024,
    "steps": 4,
    "guidance_scale": 1.0,
    "seed": 8151234567890123456,
    "n": 1,
    "model": "flux2-klein-4b",
    "timings": {
      "queue_wait_s": 0.0100,
      "decode_s": null,
      "gpu_s": 4.1000,
      "encode_s": 0.1800,
      "worker_s": 4.2800
    }
  }
}

meta reports the effective parameters — what the server actually used, after defaults and after drawing a seed if you didn't send one.

Prompt length#

This is the most common cause of "the image ignored half of what I asked for". A long, detailed prompt is not just wasted past the cutoff; it also dilutes the part that does fit. Lead with the subject and the details that matter most.

Prompt on the key#

The prompt can live on your API key, the way the system prompt does on the text endpoints — and the same precedence applies.

That is what lets you send only the URL, the key and the image:

curl -X POST "https://api.trystac.com/v1/images/edits" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F "image[]=@photo.png"

Throughput#

Image generation has no daily quota — diffusion produces no tokens, so the token budget that applies to the chat endpoints doesn't apply here. What limits you is the GPU, which renders one image at a time.

Both limits belong to the stack, not to the key. Issuing more keys doesn't raise them, because the same GPU does the work either way.

Observed end to end: roughly 6–9s for text to image, and 7–21s for an edit, varying with the number, dimensions and weight of the reference images. "10 per minute" is a submission ceiling, not a promise of ten finished images per minute.

Storage and retention#

Every generated image is stored, linked to the account, stack and key that created it. This happens server-side and changes nothing in your code — the response is still b64_json.

Two consequences worth knowing:

• A 200 means the image was stored. The write happens before the response is sent, and adds a few hundred milliseconds to a call that already takes seconds.
• A 502 can happen with the image already generated. If storage fails we return the error rather than hand you an image while claiming it was saved. Retrying is safe — but it generates again, with a new seed unless you pinned one.

Files are kept for 30 days. If you need an image for longer, save the b64_json on your side: this storage exists for traceability and for viewing the image in the platform, not as permanent hosting.

Errors#

Two error shapes reach you on these routes. The gateway's own rejections use the API-wide { "detail": "..." } shape; anything the image server rejects comes back in OpenAI's shape, with a stable code you can branch on:

{
  "error": {
    "message": "size must be one of: 1024x1024, 1536x1024, 1024x1536",
    "type": "invalid_request_error",
    "code": "invalid_size"
  }
}

Retry 429, 503 and 504 after the delay in Retry-After. A 502 is also worth one retry, keeping in mind it renders again from scratch.