Image API

HopBase presents a single OpenAI Images compatible protocol to clients. Send text-to-image requests to POST https://api.hop-base.com/v1/images/generations. Even for Gemini Banana, do not send a Gemini-native generateContent payload; HopBase adapts the request for the selected model.

Endpoints

Method	Path	Purpose	Request format
POST	`/v1/images/generations`	Text-to-image; Seedream also accepts `image` for transformation and editing	`application/json`
POST	`/v1/images/edits`	Image-to-image and editing	`multipart/form-data` (recommended), or JSON with URLs / Data URLs
GET	`/v1/images/tasks?task_id=...`	Query an asynchronous task	Used after a request with `Prefer: respond-async`

Every endpoint uses Authorization: Bearer sk-your-key. The Base URL is https://api.hop-base.com/v1.

Minimal text-to-image curl request

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A Shiba Inu sitting under cherry blossoms, Japanese watercolor style",
    "size": "2048x2048",
    "quality": "medium",
    "background": "opaque",
    "output_format": "png",
    "n": 1
  }'

Text-to-image with the OpenAI Python SDK

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hop-base.com/v1",
    api_key="sk-your-key",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="A Shiba Inu sitting under cherry blossoms, Japanese watercolor style",
    size="2048x2048",
    quality="medium",
    background="opaque",
    output_format="png",
    n=1,
)

image = resp.data[0]
with open("result.png", "wb") as f:
    f.write(base64.b64decode(image.b64_json))

GPT Image model IDs

Model	Model ID	Positioning
GPT Image 2	`gpt-image-2`	Previous generation; `auto`, 1K, 2K, and 4K sizes
GPT Image 2.5 Flare	`gpt-image-2.5-flare`	Everyday default for most image work
GPT Image 2.5 Sunburst	`gpt-image-2.5-sunburst`	Higher fidelity; slower than Flare at the same settings

Both GPT Image 2.5 models use the same OpenAI Images protocol on /v1/images/generations and /v1/images/edits; existing clients only change model. Prices are on the pricing page and in the signed-in model catalog.

GPT Image 2.5 parameters

Field	GPT Image 2.5 behavior
`size`	`1024x1024`, `1536x1024`, `1024x1536`, `auto`, or any `WIDTHxHEIGHT` whose sides are multiples of 16, whose longer side is at most 3840, and whose aspect ratio is between 1:3 and 3:1 (for example `1536x864` or `2048x1152`). Other values return an explicit 400.
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, or `auto`. Higher tiers emit more output tokens and cost more: measured at 1024x1024, about 200 at low, 1,760 at high, 3,120 at xhigh, and 7,020 at max.
`n`	Multiple images per request
`background`	`transparent` with `png` or `webp` output
`output_format` / `output_compression`	`png`, `jpeg`, or `webp`, with optional compression
`moderation`	`low` is accepted
`response_format`	`url` is accepted, but the image is still returned as `b64_json`
Editing	One reference, several references through repeated `image[]`, or inpainting with an alpha-channel `mask`: transparent mask areas are regenerated and opaque areas are preserved pixel for pixel

Reference timings for one 1024x1024 image: about 14 seconds at low on either model; at high, Flare takes about 19 seconds and Sunburst about 37 seconds.

GPT Image 2.5 text-to-image with a custom size

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A product shot of a ceramic teapot on slate, soft window light",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "webp",
    "output_compression": 85
  }'

Gemini Banana compatibility

Capability	Gemini behavior through HopBase
Request endpoint	Clients always call `/v1/images/generations`; HopBase adapts the request for the selected model.
Response	Results use OpenAI Images JSON, usually `data[].b64_json` and sometimes `data[].url`.
Image-to-image	Gemini models that support editing accept one or more references and a natural-language instruction through `/v1/images/edits`. Gemini does not provide hard region constraints through `mask`.
Size	HopBase validates `size` for the model and adapts it where required.
Other parameters	Support for `quality`, `background`, `output_format`, `input_fidelity`, and `n` depends on the model. Do not assume exact GPT Image parity.
Streaming	Use synchronous mode for Gemini images. Do not send `"stream": true`; unsupported models return an explicit error.
Asynchronous	Some models support `Prefer: respond-async`. Use the actual HTTP status to determine whether the result is a `202 task_id`.

Gemini adaptation happens on the HopBase server. The client Base URL, Bearer key, and OpenAI Images request structure stay unchanged.

Gemini Banana image model IDs

Family	Model ID	Size
Banana	`gemini-2.5-flash-image`	1K
Banana Pro	`gemini-3-pro-image` / `gemini-3-pro-image-c` `gemini-3-pro-image-preview` / `gemini-3-pro-image-preview-c`	1K / 2K / 4K
Banana 2	`gemini-3.1-flash-image` / `gemini-3.1-flash-image-c` `gemini-3.1-flash-image-preview` / `gemini-3.1-flash-image-preview-c`	1K / 2K
Banana 2 Lite	`gemini-3.1-flash-lite-image`	1K

The -c variants are separate production model IDs with the same client protocol as the rest of their family. Do not add or remove the suffix yourself. Call GET /v1/models with the current key and use a complete returned ID.

Gemini image models are billed by actual token usage. Conversion multipliers can vary by plan group; the signed-in model catalog is authoritative.

Available Seedream models

Model	Model ID	Sizes	Output / optimization
Seedream 5.0 Pro	`seedream-5-0-pro`	1K / 1.5K / 2K	PNG / JPEG; standard / fast
Seedream 5.0 Lite	`seedream-5-0-lite`	2K / 3K / 4K	PNG / JPEG; standard
Seedream 4.5	`seedream-4-5`	2K / 4K	JPEG; standard

Lite is the lightweight Seedream 5.0 model. Do not treat seedream-5-0-lite as Pro. The table above shows official benchmark prices; your effective price follows your group multiplier and is shown in the signed-in model catalog. Pro's 1.5K costs the same as 1K with better quality - prefer 1.5K for small-to-medium output. Lite and 4.5 have a 2K-class minimum (at least 3,686,400 total pixels); use Pro when you need 1K output.

Seedream 5.0 Pro text-to-image

Seedream text-to-image uses /v1/images/generations, is priced per output image, and returns a signed URL valid for 24 hours. The example uses Pro; you can select a Lite or 4.5 ID returned for the current key and follow that model's parameter limits.

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "A futuristic city street at night in neon light, cinematic composition",
    "size": "2048x2048",
    "response_format": "url"
  }'

Seedream 5.0 Pro image-to-image and editing (JSON recommended)

Continue to call /v1/images/generations and add image. It accepts 1-10 HTTP(S) URLs or image Data URLs. Single-image transformation, multi-image composition, reference redraws, and local edits marked with coordinates, bounding boxes, arrows, or paint strokes all use this endpoint.

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "Move the cup in the first image to the right side of the table and keep everything else unchanged",
    "image": ["https://example.com/source.png"],
    "size": "2K",
    "output_format": "png",
    "response_format": "url"
  }'

Seedream 5.0 Pro through OpenAI edits (local files)

Existing OpenAI Images editing code can use multipart requests to /v1/images/edits. HopBase adapts the files and request format.

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=seedream-5-0-pro" \
  -F "prompt=Redesign the poster from both references while preserving the subject and brand colors" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "size=2K" \
  -F "output_format=png"

Common Seedream parameters

Field	Description
`model`	A complete Seedream ID returned by the current key's `GET /v1/models`
`prompt`	Content, composition, style, or editing instruction. Local edits can describe coordinates, a bounding box, arrows, or painted regions in a reference.
`image`	Optional single URL / Data URL or an array. Limits: 10 for Pro, 14 for Lite and 4.5. Providing it enables single- or multi-image transformation and editing.
`size`	Use a shorthand size from the table. Custom `WIDTHxHEIGHT` values need a 1:16-16:1 aspect ratio. Total pixel range: 921,600-4,624,220 for Pro; 3,686,400-16,777,216 for Lite and 4.5 (values below the minimum are rejected at the gateway with the valid range).
`output_format`	Pro / Lite: `png` or `jpeg`; 4.5: `jpeg` only
`optimize_prompt_options.mode`	Pro: `standard` or `fast`; Lite / 4.5: `standard` only
`response_format`	HopBase currently uses `url` and returns a direct image link.

Account-specific multipliers and charges are shown in the signed-in model catalog. Seedream supports synchronous text-to-image, one or multiple references, and editing with n=1 and response_format=url. It does not support asynchronous image tasks or streaming. Each input can be up to 30 MB / 36 MP in JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, or HEIF format. Returned signed URLs are valid for 24 hours; download them promptly.

Seedream local editing does not use a traditional hard mask. Draw the annotation directly on a reference image and describe its coordinates, bounding box, arrow, or painted region in the prompt. Passing mask to /v1/images/edits returns 400 to avoid ambiguous behavior.

Use a plan-group key for which GET /v1/models returns the complete target Seedream ID. Do not assume that another plan group can call these models.

Generic image-to-image or editing with multipart curl

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=gpt-image-2" \
  -F "prompt=Turn the reference into a Van Gogh-style oil painting of a starry night" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

GPT Image 2.5 inpainting with references and a mask

mask is a PNG with an alpha channel. Transparent pixels are regenerated from the prompt; opaque pixels are copied through unchanged. Repeat image[] to pass several references.

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Fill the masked area with a vase in the style of the second reference" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "[email protected]" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "output_format=png"

Common request fields

Field	Required	Description
`model`	Yes	`gpt-image-2`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, or a complete Gemini Banana / Seedream image ID returned by the current key's `GET /v1/models`
`prompt`	Yes	Image content, composition, style, and text requirements
`size`	No	`auto` or `WIDTHxHEIGHT`; common values include 1024x1024, 1536x1024, 1024x1536, and 2048x2048. GPT Image 2.5 also accepts custom sizes within the rules above
`quality`	No	`low`, `medium`, `high`, or `auto`; GPT Image 2.5 also accepts `xhigh` and `max`
`n`	No	Number of images; some models only support 1
`background`	No	`opaque` or `transparent`
`output_format`	No	`png`, `jpeg`, or `webp`
`image` / `mask`	Image is required for editing; mask depends on model	`/images/edits` accepts one or more references for supported models. Gemini does not accept `mask`. Seedream accepts up to 10 reference images for Pro (14 for Lite and 4.5) at 30 MB each and also does not accept a traditional `mask`. GPT Image 2.5 accepts repeated `image[]` references and an alpha-channel `mask`.

Image sizes are validated against the selected model. Unsupported 2K or 4K sizes return 400 before generation and do not incur an image charge.

Synchronous response (default)

Without a Prefer header, the request waits for completion and returns standard OpenAI Images JSON. The image is usually in data[].b64_json; some models return data[].url. usage contains token usage.

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

Non-Gemini image models that support streaming switch to SSE when "stream": true is present. The stream sends keepalive pings; the last data: event contains the Images JSON and is followed by [DONE]. Gemini image models do not support this Images SSE behavior. Keep the default synchronous mode with official SDKs.

Asynchronous task mode (OpenAI / Gemini Images gateways)

With the Prefer: respond-async header, supported models immediately return 202 Accepted, a task_id, and a status_url. Poll until the task is pending, processing, completed, or failed. On completion, result_content contains a Markdown URL for the stored image. Gemini image models also support asynchronous tasks; prefer this mode for 2K / 4K images to avoid long-running requests being cut off by CDN timeouts.

# 1. Submit and receive 202 + task_id
curl -i https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic futuristic city at night",
    "size": "2048x2048"
  }'

# 2. Poll with the task_id from the first response
curl "https://api.hop-base.com/v1/images/tasks?task_id=your-task-id" \
  -H "Authorization: Bearer sk-your-key"

On this page