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	`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))

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.

HopBase's standard Azure Gemini Image group multiplier is 3.1. At CNY 6.8 per USD, this is approximately 45.6% of the official benchmark token price. Images are billed by actual token usage; the signed-in model catalog is authoritative.

Seedream 5.0 Pro text-to-image

BytePlus Seedream 5.0 Pro uses /v1/images/generations for text-to-image. It is priced per output image and returns a signed URL valid for 24 hours.

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[]=@./subject.png" \
  -F "image[]=@./style.png" \
  -F "size=2K" \
  -F "output_format=png"

Seedream 5.0 Pro parameters and pricing

Field	Description
`model`	`seedream-5-0-pro`
`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 of up to 10. Providing it enables single- or multi-image transformation and editing.
`size`	`1K`, `2K`, or `WIDTHxHEIGHT` with 921,600-4,624,220 total pixels and a 1:16-16:1 aspect ratio. `4K` is not supported.
`output_format`	`png` or `jpeg`
`optimize_prompt_options.mode`	Optional: `standard` or `fast`
`response_format`	HopBase currently uses `url` and returns a direct image link.
Official benchmark	Output images only: $0.045 each at or below 2.36 MP (approximately 1K), or $0.09 above 2.36 MP (2K / high-pixel custom size). Reference images are not billed again.
HopBase standard display price	Currently 68%: $0.0306 each at or below 2.36 MP, or $0.0612 above 2.36 MP (USD equivalent).

The current standard group multiplier is 4.624, converted at CNY 6.8 per USD for the displayed 68% price. 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, streaming, or base64 responses. 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 Seedream / Seedance plan-group key for which GET /v1/models returns seedream-5-0-pro. Do not assume an OpenAI, Gemini, or Claude key can call across plan groups.

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 "image=@./input.png" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

Common request fields

Field	Required	Description
`model`	Yes	`gpt-image-2`, a Gemini Banana model returned by the current key's `GET /v1/models`, or `seedream-5-0-pro`
`prompt`	Yes	Image content, composition, style, and text requirements
`size`	No	`auto` or `WIDTHxHEIGHT`; common values include 1024x1024, 1536x1024, 1024x1536, and 2048x2048
`quality`	No	`low`, `medium`, `high`, or `auto`
`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 images at 30 MB each and also does not accept a traditional `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 Images gateway)

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. Some Gemini models still return synchronously; use the actual HTTP status.

# 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