Skip to main content
POST
Image generation
Generate images from a text prompt through the attested TEE gateway. This endpoint returns a buffered JSON response with inline base64 image data and an x-receipt-id header for verification.

Request body

string
required
Image model id from GET /v1/models, for example black-forest-labs/flux.2-klein-4b.
string
required
Text describing the image. Maximum 32,000 Unicode characters.
integer
Request up to n images, from 1 through 10 (default 1). Providers may return fewer images; image charges use the returned count. Non-integers, null, and integers outside this range return 400 with type: invalid_request_error, code: invalid_parameter, and param: n.
string
Image dimensions, for example 512x512, or auto if the model supports it.
string
Model-specific quality setting.
string
Model-specific background setting.
string
Image encoding option, for example png. For black-forest-labs/flux.2-klein-4b, the NEAR provider does not honor this option; returned bytes may be JPEG. Inspect the decoded bytes before choosing a file extension.
integer
Compression setting from 0 through 100, if supported by the model and output format.
string
Model-specific moderation setting.
string
Omit this field or set it to b64_json. The gateway always requests inline base64 output. url is not supported.
string
Accepted for SDK compatibility but removed before forwarding upstream.
object
The same routing constraints as Chat completions, including zdr, aci_verified, and aci_session_ids.
The gateway checks the types of the string options; supported values and defaults depend on the model and are validated upstream. user and style are accepted as strings but removed before forwarding. Other fields, including seed, return 400 unknown_parameter. Omit stream and partial_images entirely, including stream: false: streaming is not supported. ACI E2EE is not supported on this endpoint.

Example

Both examples save the first image as image.bin without assuming an encoding. The cURL example also saves response headers to image-headers.txt, including the receipt id.

Response

The image data below is shortened and the cost is illustrative, not a model price.
created is a Unix timestamp in seconds, supplied by the upstream or filled in by the gateway. data is a non-empty array of images. Each item contains b64_json and may contain revised_prompt as a string or null. Image URLs are never returned. Optional top-level fields are size, quality, output_format, and background; current black-forest-labs/flux.2-klein-4b responses omit size and output_format. When present, usage always includes integer input_tokens, output_tokens, total_tokens, and input_tokens_details.text_tokens and .image_tokens. Missing token counts are filled with 0, including when the provider reports no token usage. output_tokens_details may also be present. When pricing is available, the gateway adds usage.cost in USD: the returned image count times the applicable per-image price, plus token charges when token usage and rates are available. Zero token counts do not imply free image generation. Read x-receipt-id from the response headers and fetch GET /v1/aci/receipts/{id} using the same bearer token as the generation request. Image receipts have chat_id: null, so use the receipt id rather than a chat id. See Get receipt for the response format and Verify a response for verification.

Errors

Errors use a JSON error object. Parameter validation errors have error.type: invalid_request_error and include error.code and error.param where applicable. Authentication, budget, and routing constraint errors follow the shared error handling reference.

Models

Find available model ids and capabilities.

Get receipt

Retrieve the signed receipt using x-receipt-id.