Images

Generate images, edit existing images, replace backgrounds, and compose product visuals through Quotaflow's OpenAI-compatible image endpoints.

When to use this page

Use this page when your application already expects OpenAI-style image generation or image editing request shapes. For model-specific guidance, use the dedicated references for GPT Image 2, Gemini 3.1 Flash Image, and Gemini 3 Pro Image.

Endpoints

POST https://api.quotaflow.ai/openai/v1/images/generations
POST https://api.quotaflow.ai/openai/v1/images/edits
GET  https://api.quotaflow.ai/openai/v1/images/jobs/{id}

Supported models

• gpt-image-2
• openai/gpt-image-2 (GPT Image 2 alias)
• gemini-3.1-flash-image-preview
• gemini-2.5-flash-image

Call /models to confirm which image models are enabled for your key.

gemini-3-pro-image-preview is not generally enabled while its independent supply validation is incomplete. Do not assume availability unless the authenticated /models response for your key includes it.

Key features

• Text-to-image generation: create new assets from a prompt.
• Queued multi-image generation: set n above 1 for multiple outputs; Quotaflow may split, queue, and combine generation work to return the requested number of images when capacity is available.
• Image edits: upload a source image and describe the change.
• Masks: guide localized edits when only one region should change.
• High-fidelity edits: gpt-image-2 automatically processes image inputs at high fidelity; use focused prompts and masks when source image, identity, object layout, or product geometry must remain stable.
• Multi-image composition: combine product, scene, style, and logo references.
• OpenAI-compatible output: use response formats that existing OpenAI-style clients expect. For gpt-image-2, customer-visible and billable image usage is normalized to the official-compatible token truth across generation, edits, masks, multiple references, and n > 1; a mask does not count as an additional reference image. If exact truth cannot be determined, Quotaflow omits usage instead of forwarding an unverified upstream value, so clients should treat usage as optional for image responses.
• Explicit size and quality: successful non-streaming gpt-image-2 responses include explicitly requested size and quality. Undecodable output bytes or output that does not match an explicit size are rejected rather than returned as success.
• Optional hosted URL output: for non-streaming /images/generations and /images/edits, set response_format: "url" to receive a temporary Quotaflow-hosted image URL instead of inline base64 when hosted output is enabled for the deployment.
• Async image jobs for long renders: for JSON gpt-image-2 generation or edit requests, set async: true in the request body to receive a 202 job envelope and poll /images/jobs/{id} instead of holding a long HTTP connection. Successful async jobs return hosted URL output in response.data[].url.

Do not send text-model reasoning controls such as top-level thinking to /images/generations or /images/edits. Image endpoints return a clear 400 invalid_request_error for unsupported parameter families and do not retry those requests on another image execution path.

Common use cases

Generate an image

For generation requests, n controls the number of output images. Large n values can take longer because Quotaflow may process the request in batches and aggregate successful image results before returning one OpenAI-compatible response. Configure client timeouts for the full generation job.

curl https://api.quotaflow.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $QUOTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product screenshot style illustration of a teal API dashboard.",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

Edit an image

Use multipart when your application has local files:

curl https://api.quotaflow.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $QUOTAFLOW_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@./input.png" \
  -F "mask=@./mask.png" \
  -F "prompt=Change only the masked area to a clean teal gradient" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "response_format=b64_json"

For server-side image URLs, send JSON:

curl https://api.quotaflow.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $QUOTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Change only the masked area to a clean teal gradient",
    "images": [{ "image_url": "https://example.com/input.png" }],
    "mask": { "image_url": "https://example.com/mask.png" },
    "size": "1024x1024",
    "quality": "high",
    "response_format": "b64_json"
  }'

Async image jobs

High-resolution or high-fidelity gpt-image-2 renders can take several minutes. If your application does not want to keep a single HTTP connection open, opt in to Quotaflow async image jobs on JSON requests:

curl https://api.quotaflow.ai/openai/v1/images/generations \
  -H "Authorization: Bearer $QUOTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A detailed high-resolution ecommerce hero image of a teal API dashboard.",
    "size": "2880x2880",
    "response_format": "url",
    "async": true
  }'

The create call returns 202 Accepted:

{
  "id": "imgjob_...",
  "object": "image.generation.job",
  "status": "queued",
  "model": "gpt-image-2",
  "created": 1781600000,
  "expires_at": 1781601800,
  "status_url": "/openai/v1/images/jobs/imgjob_..."
}

Poll the status URL with the same API key:

curl https://api.quotaflow.ai/openai/v1/images/jobs/imgjob_... \
  -H "Authorization: Bearer $QUOTAFLOW_API_KEY"

While the job is running, status is queued or running. When it succeeds, the response contains status: "succeeded" and a response object with an OpenAI-compatible image payload. Async jobs return hosted URL output in response.data[].url, plus expires_at, and include usage when exact accounting is available. If a policy or validation error occurs, the job response contains a sanitized error object. Job IDs are scoped to the API key that created them.

Async image jobs currently require JSON request bodies. For edits, use images[].image_url and optional mask.image_url; multipart file uploads remain synchronous.

Reference images from Responses

If your client uses the Responses API, you can pass reference images as input_image content items and attach the image_generation tool. Quotaflow accepts input_image.image_url values, including HTTPS URLs and data URLs, and bridges those requests to the same edit-capable image pool. Use /images/edits directly when you need multipart file uploads, masks, or explicit multi-image edit request control.

Edit request rules

• Use the API host https://api.quotaflow.ai; https://app.quotaflow.ai is the dashboard host and does not accept API POSTs.
• For gpt-image-2, size accepts auto or WIDTHxHEIGHT with 16-pixel multiples, max side 3840, max 8,294,400 total pixels, and max 3:1 aspect ratio. 2880x2880 is valid; 4096x4096 is not.
• Use image file fields for multipart uploads, or images[].image_url for JSON requests.
• JSON file_id inputs are not supported yet. Use image URLs or multipart file uploads instead.
• Multi-image edits are supported; keep total request size reasonable.
• Masks are optional. If you provide a mask, use a focused prompt for the masked region.
• For gpt-image-2, image inputs are high fidelity automatically; use focused prompts and masks for edits where the source subject, product shape, pose, layout, or identity-like features should remain stable.
• Image generation and editing can take longer than chat completions. Configure HTTP client timeouts accordingly.

Prompting tips

• Identify each input image by role: source product, target scene, style reference, logo reference, or mask target.
• State what must stay unchanged, such as product shape, label text, brand color, or camera angle.
• Specify background, lighting, shadow, aspect ratio, and whether text must remain readable.
• Ask for one clear deliverable per request. If you need several variants, send separate requests.

Response shape

Quotaflow returns an OpenAI-compatible image response. Use response_format: "b64_json" when you want image bytes directly in the response. For non-streaming image generation and edits, response_format: "url" is a Quotaflow extension that can return data[].url plus data[].expires_at as a temporary hosted URL; download or copy the image to your own storage before it expires. Successful image responses usually include an OpenAI-style usage object. gpt-image-2 usage is normalized to official-compatible image truth rather than copying unverified provider usage. When exact accounting is unavailable, usage may be omitted, so clients should not require the field to be present.