Edit image

Image-to-image / image editing: GPT Image (supports mask), Seedream, and Gemini in the "Gemini (all models, incl. image)" group.

POST/v1/images/edits

Generates from reference images or edits locally. multipart/form-data is recommended (local files; reference image field image / image[], repeatable); JSON is also accepted (reference images as HTTP(S) URLs or Data URLs). Field names are the same in both. The example on the right uses JSON; for multipart see the Image generation guide.

JSON edits and async tasks do not keep output_compression, moderation, user or response_format. The "Gemini Official Direct" group has no such endpoint; pass reference images to Create image instead.

Edit image

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Turn the reference image into an oil painting in the style of Van Gogh'\''s The Starry Night",
    "image": "https://example.com/input.png",
    "size": "1536x1024",
    "quality": "medium"
  }'

200application/json

{
  "created": 1790222400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 1310,
    "output_tokens": 1056,
    "total_tokens": 2366
  }
}

Headers

Authorization:requiredstring

Bearer sk-…: an API key created in the console under API keys; its group must include the requested model

Prefer:optionalstring

respond-async: GPT Image / Gemini immediately return 202 Accepted with task_id and status_url; then poll GET /v1/images/tasks?task_id=…. Recommended for large 2K / 4K images. Seedream ignores this header and returns synchronously as usual

Valuesrespond-async

Body parametersJSON

ModelOpen in image request builder Model docs

Group: GPT Image (all models). Read results from data[].b64_json. Up to 16 reference images.

model:required"gpt-image-2"

First confirm that GET /v1/models for the current key includes this ID

prompt:requiredstring

Generation or editing instruction; empty returns 400 prompt must not be empty. The gateway sets no length limit; the official cap applies

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length1–32000 chars

size:optional"auto" or string

E.g. 1024x1024, 2048x2048, 3840x2160. Invalid sizes return 400 before generation and are not billed; 1K / 2K / 4K are not accepted

Limitsauto or WxH: sides multiples of 16, each side ≤ 3840, long-to-short ratio ≤ 3:1, total pixels 655360–8294400

quality:optionalstring

Higher tiers produce more output tokens and cost more: at 1024x1024, measured output is about 200 tokens for low, 1,760 for high, 3,120 for xhigh and 7,020 for max

Valuesautolowmediumhigh

LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens

n:optionalinteger

Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1

Range1–10Default1

background:optionalstring

transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability

Valuesautoopaquetransparent

output_format:optionalstring

Sets the format of the decoded b64_json

Valuespngjpegwebp

output_compression:optionalinteger

jpeg / webp only; kept only in synchronous generations JSON and multipart edits

Range0–100Default100

moderation:optionalstring

Does not turn off content safety checks

Valuesautolow

user:optionalstring

End-user identifier string; not a HopBase account ID, and it does not change billing attribution

response_format:optionalstring

Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it

stream:optionalboolean

true switches to HopBase Images SSE (keepalives are sent meanwhile; only the last data: event is the Images JSON, ending with [DONE]), not OpenAI's native per-image preview events. Keep it false in SDKs

Limitstrue returns HopBase Images SSE; keep false in SDKsDefaultfalse

input_fidelity:optionalstring

Compatibility field; GPT Image 2 processes reference images at high fidelity by default, so omit it

Valueslowhigh

image:requiredstring or array of string

Multipart files (image / image[]), or in JSON an HTTP(S) URL / Data URL string or array of strings. images is not read; raw base64 and file_id are not accepted; images may be compressed before forwarding

Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images

mask:optionalstring

Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical

LimitsPNG with an alpha channel; transparent areas mark what to edit

transparent requires png or webp
output_compression applies only to jpeg / webp

model:required"gpt-image-2.5-flare"

First confirm that GET /v1/models for the current key includes this ID

prompt:requiredstring

Generation or editing instruction; empty returns 400 prompt must not be empty. The gateway sets no length limit; the official cap applies

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length1–32000 chars

size:optional"auto" or string

E.g. 1024x1024, 2048x2048, 3840x2160. Invalid sizes return 400 before generation and are not billed; 1K / 2K / 4K are not accepted

Limitsauto or WxH: sides multiples of 16, each side ≤ 3840, long-to-short ratio ≤ 3:1, total pixels 655360–8294400

quality:optionalstring

Higher tiers produce more output tokens and cost more: at 1024x1024, measured output is about 200 tokens for low, 1,760 for high, 3,120 for xhigh and 7,020 for max

Valuesautolowmediumhighxhighmax

LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens

n:optionalinteger

Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1

Range1–10Default1

background:optionalstring

transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability

Valuesautoopaquetransparent

output_format:optionalstring

Sets the format of the decoded b64_json

Valuespngjpegwebp

output_compression:optionalinteger

jpeg / webp only; kept only in synchronous generations JSON and multipart edits

Range0–100Default100

moderation:optionalstring

Does not turn off content safety checks

Valuesautolow

user:optionalstring

End-user identifier string; not a HopBase account ID, and it does not change billing attribution

response_format:optionalstring

Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it

stream:optionalboolean

Limitstrue returns HopBase Images SSE; keep false in SDKsDefaultfalse

input_fidelity:optionalstring

Compatibility field; GPT Image 2 processes reference images at high fidelity by default, so omit it

Valueslowhigh

image:requiredstring or array of string

Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images

mask:optionalstring

Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical

LimitsPNG with an alpha channel; transparent areas mark what to edit

transparent requires png or webp
output_compression applies only to jpeg / webp

model:required"gpt-image-2.5-sunburst"

First confirm that GET /v1/models for the current key includes this ID

prompt:requiredstring

Generation or editing instruction; empty returns 400 prompt must not be empty. The gateway sets no length limit; the official cap applies

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length1–32000 chars

size:optional"auto" or string

E.g. 1024x1024, 2048x2048, 3840x2160. Invalid sizes return 400 before generation and are not billed; 1K / 2K / 4K are not accepted

Limitsauto or WxH: sides multiples of 16, each side ≤ 3840, long-to-short ratio ≤ 3:1, total pixels 655360–8294400

quality:optionalstring

Higher tiers produce more output tokens and cost more: at 1024x1024, measured output is about 200 tokens for low, 1,760 for high, 3,120 for xhigh and 7,020 for max

Valuesautolowmediumhighxhighmax

LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens

n:optionalinteger

Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1

Range1–10Default1

background:optionalstring

transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability

Valuesautoopaquetransparent

output_format:optionalstring

Sets the format of the decoded b64_json

Valuespngjpegwebp

output_compression:optionalinteger

jpeg / webp only; kept only in synchronous generations JSON and multipart edits

Range0–100Default100

moderation:optionalstring

Does not turn off content safety checks

Valuesautolow

user:optionalstring

End-user identifier string; not a HopBase account ID, and it does not change billing attribution

response_format:optionalstring

Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it

stream:optionalboolean

Limitstrue returns HopBase Images SSE; keep false in SDKsDefaultfalse

input_fidelity:optionalstring

Compatibility field; GPT Image 2 processes reference images at high fidelity by default, so omit it

Valueslowhigh

image:requiredstring or array of string

Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images

mask:optionalstring

Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical

LimitsPNG with an alpha channel; transparent areas mark what to edit

transparent requires png or webp
output_compression applies only to jpeg / webp

model:required"gemini-3.1-flash-image"

GET /v1/models for the current key is authoritative

prompt:requiredstring

If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars

n:optionalinteger

Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed

LimitsCapped by output tier: 1K ≤ 10, 2K ≤ 5Range1–10Default1

image_size:optionalstring

Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size

Values1K2K

Default"1K"

aspect_ratio:optionalstring

Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size

Values1:12:33:23:44:34:55:49:1616:921:9

Default"1:1"

size:optional"auto" or string

WxH is never rejected for its ratio: it maps to the closest official ratio, and the tier is derived from the long edge and silently lowered to the model's highest tier. An explicit 1K / 2K / 4K above the model's tier returns 400; if image_size is also sent, it wins

Values1K2K

Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier

google:optionalobject

In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent

image:optionalstring or array of string

Reference images, placed directly in the generations request body; if both are sent, images wins. On "Gemini Official Direct" each image must be ≤ 20 MiB decoded, and there is no /v1/images/edits

images:optionalstring or array of string

Same as image; if both are sent, images wins

LimitsReference images: a string or array of strings, up to 14

mask:not supported

Not supported: sending mask returns 400; describe the region to change in the prompt instead

background:optionalany

transparent is not supported (returns 400)

Must not be"transparent"

stream:optionalany

Not supported; omit it or pass false

Must not betrue

At most 5 images per request for 2K output (response size limit)

model:required"gemini-3.1-flash-image-preview"

GET /v1/models for the current key is authoritative

prompt:requiredstring

If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars

n:optionalinteger

Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed

LimitsCapped by output tier: 1K ≤ 10, 2K ≤ 5Range1–10Default1

image_size:optionalstring

Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size

Values1K2K

Default"1K"

aspect_ratio:optionalstring

Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size

Values1:12:33:23:44:34:55:49:1616:921:9

Default"1:1"

size:optional"auto" or string

Values1K2K

Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier

google:optionalobject

In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent

image:optionalstring or array of string

images:optionalstring or array of string

Same as image; if both are sent, images wins

LimitsReference images: a string or array of strings, up to 14

mask:not supported

Not supported: sending mask returns 400; describe the region to change in the prompt instead

background:optionalany

transparent is not supported (returns 400)

Must not be"transparent"

stream:optionalany

Not supported; omit it or pass false

Must not betrue

At most 5 images per request for 2K output (response size limit)

model:required"gemini-3-pro-image"

GET /v1/models for the current key is authoritative

prompt:requiredstring

If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars

n:optionalinteger

Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed

LimitsCapped by output tier: 1K ≤ 10, 2K ≤ 5, 4K ≤ 2Range1–10Default1

image_size:optionalstring

Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size

Values1K2K4K

Default"1K"

aspect_ratio:optionalstring

Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size

Values1:12:33:23:44:34:55:49:1616:921:9

Default"1:1"

size:optional"auto" or string

Values1K2K4K

Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier

google:optionalobject

In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent

image:optionalstring or array of string

images:optionalstring or array of string

Same as image; if both are sent, images wins

LimitsReference images: a string or array of strings, up to 14

mask:not supported

Not supported: sending mask returns 400; describe the region to change in the prompt instead

background:optionalany

transparent is not supported (returns 400)

Must not be"transparent"

stream:optionalany

Not supported; omit it or pass false

Must not betrue

At most 5 images per request for 2K output (response size limit)
At most 2 images per request for 4K output (response size limit)

model:required"gemini-3.1-flash-lite-image"

GET /v1/models for the current key is authoritative

prompt:requiredstring

If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars

n:optionalinteger

Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed

LimitsCapped by output tier: 1K ≤ 10Range1–10Default1

image_size:optionalstring

Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size

Values1K

Default"1K"

aspect_ratio:optionalstring

Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size

Values1:12:33:23:44:34:55:49:1616:921:9

Default"1:1"

size:optional"auto" or string

Values1K

Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier

google:optionalobject

In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent

image:optionalstring or array of string

images:optionalstring or array of string

Same as image; if both are sent, images wins

LimitsReference images: a string or array of strings, up to 14

mask:not supported

Not supported: sending mask returns 400; describe the region to change in the prompt instead

background:optionalany

transparent is not supported (returns 400)

Must not be"transparent"

stream:optionalany

Not supported; omit it or pass false

Must not betrue

model:required"gemini-2.5-flash-image"

GET /v1/models for the current key is authoritative

prompt:requiredstring

If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars

n:optionalinteger

Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed

LimitsCapped by output tier: 1K ≤ 10Range1–10Default1

image_size:optionalstring

Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size

Values1K

Default"1K"

aspect_ratio:optionalstring

Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size

Values1:12:33:23:44:34:55:49:1616:921:9

Default"1:1"

size:optional"auto" or string

Values1K

Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier

google:optionalobject

In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent

image:optionalstring or array of string

images:optionalstring or array of string

Same as image; if both are sent, images wins

LimitsReference images: a string or array of strings, up to 3

mask:not supported

Not supported: sending mask returns 400; describe the region to change in the prompt instead

background:optionalany

transparent is not supported (returns 400)

Must not be"transparent"

stream:optionalany

Not supported; omit it or pass false

Must not betrue

Returns

200Synchronous success

202With Prefer: respond-async

created:optionalinteger

Unix seconds

data:requiredarray of object

One entry per image

usage:optionalobject

May be returned

Errors

400Invalid parameters (rejected before generation, not billed)

401Missing, invalid or expired API key (missing_api_key / invalid_api_key / api_key_expired)

402Balance, or key / member / department quota, exhausted (insufficient_quota)

404The model is not in this key's group (model_not_found), or the path does not belong to the group (route_not_found)

413Request body over 60 MB (request_too_large)

429Account or key concurrency cap reached (user_concurrency_limit / apikey_concurrency_limit), with Retry-After

Headers

Body parametersJSON

Returns

Errors

Related