Image Generation

Generate images from text prompts — or edit existing images — using models from OpenAI, Google Vertex AI, and more. The API is compatible with the OpenAI images endpoint, so existing integrations work without modification.

Generate an image

curl
Python

curl https://api.meshapi.ai/v1/images/generations \
  -H "Authorization: Bearer rsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1-mini",
    "prompt": "A children drawing of a veterinarian and a baby otter",
    "response_format": "url"
  }'

from openai import OpenAI

client = OpenAI(api_key="rsk_...", base_url="https://api.meshapi.ai/v1")

response = client.images.generate(
    model="openai/gpt-image-1-mini",
    prompt="A children drawing of a veterinarian and a baby otter",
    response_format="url",
)
print(response.data[0].url)

Response:

{
  "created": 1717200000,
  "data": [
    {
      "url": "data:image/png;base64,iVBORw0KGgo..."
    }
  ]
}

GPT image and Google Vertex AI models return image bytes, not a hosted link, so with response_format: "url" the url field holds a data: URI. Other providers may return an https:// link.

Request fields

Not all parameters are supported by every model. Support varies by provider — unsupported fields are silently ignored or return an error depending on the model. Check the model’s documentation or test with your target model before relying on a specific parameter.

Field	Type	Description
`model`	string	Image model ID (required)
`prompt`	string	Text description of the image to generate
`n`	integer	Number of images to generate, 1–10 (default: 1)
`size`	string	Image dimensions, e.g. `"1024x1024"`, `"1536x1024"`, or `"auto"` (default)
`quality`	string	`"auto"` (default); `"low"` / `"medium"` / `"high"` for GPT image models (`openai/gpt-image-2.5-*` also take `"xhigh"` / `"max"`); `"1K"` / `"2K"` / `"4K"` for Gemini 3 image models, which also map `low` / `medium` / `high` to those sizes
`aspect_ratio`	string	e.g. `"16:9"` or `"1:1"`. Honoured by xAI Grok Imagine and Gemini 3 image models. Derived from `size` when omitted
`resolution`	string	`"1k"` or `"2k"`, xAI Grok Imagine only. Derived from `size` when omitted
`image`	string or string[]	Reference image(s) for image-conditioned generation, as base64, `data:` URI or URL. Only for models with `supports_image_reference: true` on `GET /v1/models` (BytePlus Seedream, Gemini 3 image, Grok Imagine); other models return `422`. Gemini does not accept `http(s)` URLs
`response_format`	string	`"url"` (default) or `"b64_json"`
`output_format`	string	Output encoding: `"png"`, `"jpeg"`, or `"webp"` on GPT image models; BytePlus Seedream takes `png` / `jpeg`
`output_compression`	integer	Compression level 0–100 for `jpeg`/`webp` output — GPT image models only
`background`	string	Transparency: `"transparent"`, `"opaque"`, or `"auto"` — GPT image models only
`moderation`	string	Content-moderation level: `"low"` or `"auto"` — GPT image models only
`partial_images`	integer	0–3, forwarded to GPT image models. Mesh does not stream partial images from them. See Streaming
`seed`, `guidance_scale`, `watermark`, `optimize_prompt`	—	BytePlus Seedream only: seed (-1 to 2147483647), prompt adherence 1–10, “AI generated” watermark, prompt rewriting on/off
`stream`	boolean	Return a `text/event-stream`. See Streaming
`tags`	object	Your own labels, as an object of up to 16 string pairs. Filter and group spend by them in usage reports
`safety_identifier`	string	A stable, anonymised id for the end user the request was made for (a hash, not an email), so spend can be attributed per user

Edit an image

Transform an existing image with POST /v1/images/edits: edit it with a prompt (optionally guided by a mask), remove its background, upscale, outpaint, inpaint, mix or reframe it. Send either multipart/form-data (file uploads, as below) or application/json with each image as a data:image/<fmt>;base64,... string (or a {"url": "data:..."} object). Remote http(s) image URLs are rejected with 422, because Mesh does not fetch images.

curl
Python

curl https://api.meshapi.ai/v1/images/edits \
  -H "Authorization: Bearer rsk_YOUR_KEY" \
  -F "model=openai/gpt-image-1" \
  -F "operation=edit" \
  -F "prompt=Add a party hat on the cat" \
  -F "image=@cat.png"

from openai import OpenAI

client = OpenAI(api_key="rsk_...", base_url="https://api.meshapi.ai/v1")

response = client.images.edit(
    model="openai/gpt-image-1",
    prompt="Add a party hat on the cat",
    image=open("cat.png", "rb"),
)
print(response.data[0].url)

Response:

{
  "created": 1717200000,
  "data": [
    {
      "url": "data:image/png;base64,..."
    }
  ]
}

GPT image and Vertex AI models return the result as a base64 data: URI in the url field. Pass response_format=b64_json to get the raw base64 in a b64_json field instead.

Operations

The operation field selects what to do. Support is per model: each model lists the operations it serves in image_operations on GET /v1/models.

Operation	Description	Requires
`edit` (default)	Edit guided by `prompt` (+ optional `mask` and reference images)	`prompt`
`remove_background`	Strip the background; returns a transparent image	`image` only
`upscale`	Increase resolution	Optional `upscale_factor` (`x2` / `x4`) or `quality_tier` (`standard` = x2, `hd` = x4)
`outpaint`	Extend the canvas	`prompt`, plus a `mask` (Imagen) or `expand_factor` 1.01–3.0 (Gemini, maskless)
`inpaint`	Repaint the masked region (white = edit)	`mask` with the same dimensions as `image`; optional `mask_feather`
`mix`	Compose 2–4 images into one	`prompt` and 1–3 `reference_images`; returns one image
`reframe`	Recompose to a new aspect ratio	`aspect_ratio`: `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3` or `3:2`; returns one image

Requesting an operation the model doesn’t support returns 422. A provider with no image-edit support at all returns 501.

Request fields

multipart/form-data:

Field	Type	Description
`model`	string	Image model ID (required)
`image`	file	Source image: PNG, JPEG, or WebP (required). Size caps below
`prompt`	string	Edit instruction. Required for `edit`, `outpaint` and `mix`
`operation`	string	One of the operations above (default `edit`)
`mask`	file	Region to edit (white = edit; Mesh converts to each provider’s convention). Same formats as `image`
`reference_images`	file[]	Extra reference images (multi-image edit, `mix` sources). Models with `supports_image_reference: true` only
`n`	integer	Number of images to return (default: 1). `mix` and `reframe` always return one
`size`	string	Output dimensions — e.g. `"1024x1024"` or `"auto"` (default)
`response_format`	string	`"url"` (default) or `"b64_json"`
`background`	string	`"transparent"`, `"opaque"`, or `"auto"`
`upscale_factor`	string	`upscale` only: `x2` or `x4` (BytePlus maps x2 → 2K, x4 → 4K)
`quality_tier`	string	`upscale` only: `standard` (x2) or `hd` (x4). `upscale_factor` wins when both are set
`aspect_ratio`	string	Target ratio. Required for `reframe`; also used by Gemini `edit` and Grok Imagine `edit`, `mix` and `reframe`
`resolution`	string	xAI Grok Imagine only
`expand_factor`	number	`outpaint` on Gemini: how much to grow the canvas, 1.01–3.0
`mask_feather`	integer	`inpaint` only: feather radius in pixels for blending the result back through the mask (default 0, off)
`seed`, `guidance_scale`, `watermark`, `optimize_prompt`	—	BytePlus Seedream only, same as on generation
`tags`, `safety_identifier`	—	Same as on generation

Size caps. Each image is capped at 20 MB, lower for some providers: BytePlus 4.7 MB, Gemini and Imagen 7 MB, Grok Imagine via OpenRouter 10 MB. Masks are capped at 4 MB on OpenAI, Azure and Imagen. All reference images together are capped at 20 MB. An oversized file returns 422.

The per-file caps sit under a hard 32 MiB ceiling on the whole request body, enforced at the edge. A JSON body carries every image as base64, about 4/3 of the file size, so it reaches that ceiling sooner than multipart. An oversized request returns a plain HTML 413 page with no Mesh error envelope and no request ID. See Rate Limits & Spend Caps.

More examples

Remove a background:

curl https://api.meshapi.ai/v1/images/edits \
  -H "Authorization: Bearer rsk_YOUR_KEY" \
  -F "model=openai/gpt-image-1" \
  -F "operation=remove_background" \
  -F "image=@product.png"

Edit with multiple reference images (BytePlus Seedream):

curl https://api.meshapi.ai/v1/images/edits \
  -H "Authorization: Bearer rsk_YOUR_KEY" \
  -F "model=byteplus/seedream-5-0" \
  -F "operation=edit" \
  -F "prompt=Blend these into one product scene" \
  -F "image=@base.png" \
  -F "reference_images=@ref1.png" \
  -F "reference_images=@ref2.png"

Streaming

Set "stream": true to get a text/event-stream instead of a single JSON response:

{
  "model": "openai/gpt-image-1-mini",
  "prompt": "...",
  "stream": true
}

BytePlus Seedream 4.0, 4.5 and 5.0 (e.g. byteplus/seedream-5-0) stream natively, in BytePlus’s own event shape. Each finished image arrives as an image_generation.partial_succeeded event with url or b64_json at the top level of the event, not under data[]. An image that fails arrives as image_generation.partial_failed. The stream ends with image_generation.completed, which carries usage; there is no data: [DONE]. For every other model the stream keeps the connection open during a long generation: the server emits an initial processing chunk, then SSE comment pings every 15 seconds until the image is ready, then one chunk with the result in data[], then data: [DONE].

Keep-alive chunk sequence

data: {"id":"img_...","object":"image.chunk","created":...,"model":"...","data":[],"status":"processing"}

: ping

: ping

data: {"id":"...","object":"image.chunk","created":...,"data":[{"url":"..."}]}

data: [DONE]

Available models

Model	Notes
`openai/gpt-image-1-mini`	Fast, cost-efficient — ideal for most use cases
`openai/gpt-image-1` / `openai/gpt-image-2`	GPT image models, strong instruction-following
`google/gemini-3-pro-image`	Gemini 3 image: reference images, every edit operation
`google/imagen-4-fast`	Google Imagen 4 Fast. Text-to-image, plus edit, inpaint, outpaint, upscale and remove_background
`byteplus/seedream-5-0`	BytePlus Seedream: reference images, native streaming
`x-ai/grok-imagine`	xAI Grok Imagine: `aspect_ratio` / `resolution`, edit, mix, reframe

Check GET /v1/models for the full live list of enabled image models, their pricing, and each model’s image_operations.

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh Code

Mesh CLI

Platform

Reference

Generate an image

Request fields

Edit an image

Operations

Request fields

More examples

Streaming

Keep-alive chunk sequence

Available models

​Generate an image

​Request fields

​Edit an image

​Operations

​Request fields

​More examples

​Streaming

​Keep-alive chunk sequence

​Available models

Generate an image

Request fields

Edit an image

Operations

Request fields

More examples

Streaming

Keep-alive chunk sequence

Available models