Skip to main content
POST

Authorizations

x-key
string
header
required

Body

application/json
prompt
string
required

Non-blank text describing the image to generate or the edit to apply.

To place elements, name each one as <id> in the text, then end the prompt with a JSON list of rows, one per element. Each bbox is [top, left, bottom, right] on a 0 to 1000 grid, so [0, 0, 500, 500] is the top-left quarter of the output:

In an edit, rows use from, src_bbox, and tgt_bbox instead of bbox. There is no separate box field, and an entities field returns 422. For full requests, choose Layout with boxes or Edit with boxes in the request examples. Layout and editing lists every row field.

Minimum string length: 1
Pattern: \S
images

One reference image or a list of 1 to 10 images, each as an HTTP(S) URL or a base64 string. A data URI prefix is accepted. Each image must be at least 256 × 256 pixels and at most 16 megapixels; each base64 payload must be at most 20 MB. Inputs over 16 megapixels are rejected with 400, inputs below 256 × 256 pixels with 422.

Minimum string length: 1
aspect_ratio
enum<string>
default:auto

With auto, output follows the first reference image's aspect ratio, or uses 1:1 when there is no reference image.

Available options:
auto,
21:9,
2:1,
16:9,
3:2,
7:5,
4:3,
5:4,
1:1,
4:5,
3:4,
5:7,
2:3,
9:16,
1:2,
9:21
resolution
enum<string>
default:1k

Choose the output size. Check output_mp in the submit response for the exact size in megapixels. Generating at 4k can take several minutes.

Available options:
768sq,
1k,
2k,
4k
safety_tolerance
integer
default:2

Input and output moderation tolerance; 0 is strictest.

Required range: 0 <= x <= 4
grounding
boolean
default:true

When true, the model can research the prompt with web search and image search before it generates. Set false to turn both off.

Response

Poll the returned regional polling_url with x-key. Keep polling while status is Pending, Reasoning, or Generating. When it is Ready, download the image from result.sample; this signed URL expires after 1 hour. Stop on Error, Request Moderated, Content Moderated, or Task not found. Polling errors may use HTTP 503 with a regular JSON body; inspect status.

id
string
required

Task identifier.

polling_url
string<uri>
required

Regional polling URL. Poll this URL with the x-key header rather than constructing a URL.

cost
number | null

Cost in credits for this request

input_mp
number | null

Input megapixels (2 decimal places)

output_mp
number | null

Output megapixels (2 decimal places)