Skip to main content

Images

POST https://gateway.primexos.com/v1/images/generations

OpenAI-compatible image generation. The route is model-agnostic, so send the model you want and Primex routes it.

OpenAI-compatible

Uses the OpenAI Images request shape with the Primex-supported controls below. Supported values depend on the selected model. Primex differences: authenticate with your prx- key, set model to a Primex model ID, and see Errors & Limits for status codes.

Generate an image​

curl https://gateway.primexos.com/v1/images/generations \
  -H "Authorization: Bearer prx-YOUR_KEY" \
  -H "X-Primex-Operation-ID: unique-id-for-this-image-request" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A neon violet fox, studio lighting",
    "size": "1024x1024"
  }'

Use a fresh operation ID for each generation or edit and retain it with the request ID. Reuse it if the outcome is uncertain; see Retries & idempotency. The Gateway currently accepts direct image requests without this header, but the planned shared-output mode will require it and return 409 for an already submitted operation instead of starting another paid job.

Models and billing​

Image services can be billed by reported token usage, output image, or output megapixel. Size, quality, and output count can affect the measured cost. Use the live catalogue for the selected model's unit and current price.

FLUX Flex controls​

FLUX.2-flex is currently Coming soon; check the live catalogue before using it. Its generation contract accepts one image per request (n: 1), an explicit size, and PNG or JPEG output. Each side must be 64–2048 pixels in multiples of 16, with at most four 1024×1024 pixel units in total.

It does not accept reference images, editing, a quality selector, a style, background controls, or output compression. Create's initial curated size is 1024×1024. Billing uses the dimensions of the actual returned image, rounding up to a whole 1024×1024 unit per image. Generated files use Primex's temporary private storage and expire; save any output you want to keep.

Editing​

Models that advertise image editing support use POST /v1/images/edits (multipart with input images + prompt), following the OpenAI images API shape.

Send references as image or repeated image[] fields. The route accepts up to 16 references plus one optional mask, subject to the configured per-file and combined upload byte limits. The selected model may accept fewer references.

A GPT Image mask guides the edit; it does not guarantee that pixels outside the transparent area stay unchanged. Describe both the requested change and what to retain in the prompt, then inspect the returned image. See the provider's mask guidance.

For a reusable reference, use the Primex temporary Files API with purpose IMAGE_REFERENCE, then send the finalized file_id, prompt, model, and supported edit options as JSON to /v1/images/edits. Playground production examples use this account-scoped flow instead of replaying the Playground file ID.

Supported controls​

Generation accepts model, prompt, n, size, quality, style, response_format, background, output_format, output_compression, and input_fidelity. n is 1–10; the model may impose a tighter limit. GPT Image output controls include PNG/JPEG/WebP and transparent/opaque/auto backgrounds where supported. Use the selected model's published controls and supported values.

Multipart editing accepts the applicable output controls plus the input images and optional mask. JSON editing accepts one finalized file_id; it does not accept style, response_format, or a mask. See the live catalogue for model-specific options.