Image API (gpt-image-2) Sync Generation

📖 Overview

The Image API handles synchronous text-to-image and image-to-image generation. It is separate from the async task model used by Seedance video generation: the Image API returns the final result directly in the response, with no task_id to poll.

Base URL: https://images.beehears.com/v1
Recommended model: gpt-image-2
Sync text-to-image: POST /v1/images/generations
Sync image-to-image: POST /v1/images/edits (multipart form upload)

⚠️ Do not reuse the video polling logic

The Image API lives on a dedicated domain images.beehears.com and works synchronously: one request returns the image result directly. Only video (Seedance) is an async task flow (submit to get a task_id, then poll). Applying the video polling logic to an image client is the most common integration mistake.

① Prerequisites

Terminal - Environment Variables

export BASE_URL="https://images.beehears.com"
export TOKEN="sk-xxxxxxxxxxxxxxxx"

Common request headers:

Authorization: Bearer <TOKEN>
Text-to-image uses Content-Type: application/json; image-to-image uses multipart/form-data (curl's -F sets this automatically — no need to write it by hand)

⏱️ Synchronous requests are slow — set a generous timeout

Generation blocks until the image is ready; measured single-call latency is about 60–100 seconds (text-to-image faster, image-to-image slower). Set the client connect/read timeout to 180 seconds or more, otherwise a default timeout (30s / 60s) will cut the call off before the image returns.

② Recommended Model

Model	Capability	Notes
`gpt-image-2`	Text-to-image / Image-to-image	Recommended model, shared by both text-to-image and image-to-image. Put this name in the `model` field

③ The Two Endpoints

Function	Method	Path	Body
Sync text-to-image	POST	`/v1/images/generations`	JSON
Sync image-to-image	POST	`/v1/images/edits`	multipart form

ℹ️ Synchronous

Both endpoints are synchronous: by the time the HTTP response returns, the image is already generated. No task_id, no query endpoint, no polling.

④ Text to Image

Send JSON to /v1/images/generations:

Terminal

curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean sci-fi product poster, minimal composition, high detail",
    "size": "1024x1024",
    "n": 1
  }'

Field	Type	Required	Description
`model`	string	Yes	Use `gpt-image-2`
`prompt`	string	Yes	Text prompt
`size`	string	No	Output resolution, e.g. `1024x1024`. See the cap in ⑧
`n`	int	No	Number of images, defaults to 1

⑤ Image to Image

Send a multipart form to /v1/images/edits (with curl's -F). Mind the image field: use image for a single image, and repeated image[] for multiple.

5.1 Single-image edit

Terminal

curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "prompt=Repaint based on the reference image with high fidelity" \
  -F "size=1024x1024" \
  -F "n=1" \
  -F "image=@./reference.png"

5.2 Multi-image edit

For multiple reference images, use the repeated image[] field, one per line:

Terminal

curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "prompt=Use all reference images together to create one cohesive poster." \
  -F "size=1024x1024" \
  -F "n=1" \
  -F "image[]=@./ref1.png" \
  -F "image[]=@./ref2.png" \
  -F "image[]=@./ref3.png"

⚠️ Always write the file path as @./filename

curl uploads a local file with -F "image=@./reference.png" (the @ followed by ./). Do not write @reference.png — historically that form is easily mangled by web "email protection" rewriting, leaving the copied command broken.

⑥ Response Handling

The Image API may return b64_json, or it may return an image URL. Clients should handle both forms.

// Form A: base64 (the default in practice, with mime_type for the image format)
{ "data": [ { "mime_type": "image/png", "b64_json": "iVBORw0KGgoAAA..." } ] }

// Form B: URL
{ "data": [ { "url": "https://.../generated.png" } ] }

When reading the result, first check whether data[i].b64_json exists; if so, decode it (using mime_type) and save; otherwise fall back to downloading data[i].url.

⑦ Output Format

Parameter	Meaning	Notes
`output_format`	The actual output image format	Supported: `png` / `jpeg` / `webp`
`response_format`	How the result is returned	`url` or `b64_json`. It only controls the return form and does not by itself determine the underlying image format

ℹ️ The difference

output_format decides what the image itself is (png vs jpeg/webp); response_format decides how it is delivered to you (a direct URL, or base64 embedded in JSON). They are independent — combine as needed.

⑧ Resolution

Use the size field to control the output resolution, e.g. 1024x1024, 1536x1024, etc.

📐 4K cap

The maximum supported resolution is 4K, i.e. 3840×2160. Any size above this cap is not supported.

⑨ Pitfalls FAQ

Problem	Cause	Correct approach
`image is required`	The request carries no valid multipart image field	Use `image` for a single image, repeated `image[]` for multiple
curl command broken after copy	The legacy `@reference.png` form is easily mangled by the page's "email protection" rewriting	Always use the `@./reference.png` form
Image client reuses video polling logic	Video and image APIs are not the same runtime model	Treat images as synchronous, video as a task flow

Image API · gpt-image-2

📖 Overview

① Prerequisites

② Recommended Model

③ The Two Endpoints

④ Text to Image

⑤ Image to Image

5.1 Single-image edit

5.2 Multi-image edit

⑥ Response Handling

⑦ Output Format

⑧ Resolution

⑨ Pitfalls FAQ

🔗 Related Links