Image Generation API

The image API is compatible with the OpenAI Images protocol. The featured, verified inventory below contains eight models. Every listed model supports text-to-image through generations; only models explicitly marked for edits should be used with the editing endpoint.

Two endpoints are available:

• /v1/images/generations - Generate images; some models also accept reference images on this endpoint
• /v1/images/edits - Edit images for models explicitly marked below, compatible with OpenAI native edits usage

Endpoint and Authentication

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/edits

Use https://api.icodeeasy.cc as the primary Base URL. https://jp.icodeeasy.cc and https://sg.icodeeasy.cc are backup/fallback domains; keep the same path when switching.

Request headers:

• Authorization: Bearer <your API Key> (required, starts with sk_)
• Content-Type: application/json for JSON requests or multipart/form-data for file upload requests

POST /images/generations and POST /images/edits without the /v1 prefix are also accepted and behave the same.

Two Request Body Forms

The API supports two request body forms:

1. JSON (Content-Type: application/json): put reference images in image_urls as URLs or base64 data URLs. This is the most common form.
2. multipart/form-data: upload reference images through image[] files and put other parameters in form fields. This matches OpenAI native edits usage and is suitable for local file uploads.

Request Parameters

• model (required): one of the eight featured model IDs in the table above.
• prompt (required): image description in English or Chinese. The upstream performs content safety review; rejected content is not billed.
• n (default 1): number of images. Billing accumulates by image count.
• size (default 1:1): output aspect ratio. See below. auto is treated as 1:1; pixel strings such as 1536x1024 are also accepted.
• resolution (default 1k): Gemini 2.5 accepts 1k only; the listed Gemini 3.x models accept 1k, 2k, or 4k. Do not use this field to select a tier for gpt-image-2.
• quality (gpt-image-2 billing only): low, medium, high, or auto. It does not affect actual output and only decides gpt-image-2 billing price. Gemini models ignore this field and use fixed per-model pricing.
• image_urls / image_input (optional, JSON): reference images for image-to-image, up to 4 images. Items may be public https://... URLs or data:image/...;base64,...; mixed values are allowed. The two fields are aliases.
• image[] (optional, multipart): reference image files for image-to-image. Multiple files are allowed and are equivalent to file upload form of image_urls.

Reference image note: URLs must use https:// (http is rejected); base64 must be a valid data:image/*;base64, value.

Supported Ratios and Resolution

Supported size ratios: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21 / auto.

gemini-2.5-flash-image is limited to 1k. The listed Gemini 3.x models support 1k, 2k, and 4k. gpt-image-2 uses size for output ratio or pixel dimensions and has no published resolution-tier claim.

Sync / Async Modes

Default sync mode: the request waits until image generation completes and returns OpenAI-compatible data[].url.

Async mode: add ?async=1 to the URL (true and yes are also accepted). The API returns task_id immediately, and you poll for the result. Use this when you do not want to hold a long connection, need progress handling, or submit batches.

Request Examples

Minimal text-to-image, sync

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "an orange cat sitting on a windowsill watching the sunset, watercolor style"
  }'

Specify ratio and 2K with Gemini 3.x

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k"
  }'

Gemini text-to-image

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a futuristic coffee shop at sunrise, realistic photography",
    "size": "16:9",
    "resolution": "1k"
  }'

Image-to-image using image URL (JSON)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "size": "1536x1024",
    "image_urls": ["https://example.com/photo.png"]
  }'

Image-to-image uploading a local file (multipart)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=make this person 70 years old" \
  -F "size=1536x1024" \
  -F "image[]=@/path/to/photo.png"

Image-to-image with multiple references (URL + base64 mixed)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "merge these two photos into a poster",
    "size": "4:3",
    "image_urls": [
      "https://example.com/photo-a.jpg",
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    ]
  }'

Async submit + polling

# 1) Submit and get task_id immediately
curl -X POST "https://api.icodeeasy.cc/v1/images/edits?async=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "image_urls": ["https://example.com/photo.png"]
  }'
# -> {"status":"pending","task_id":"d142c93a-..."}

# 2) Poll until completed
curl "https://api.icodeeasy.cc/v1/images/tasks/d142c93a-..." \
  -H "Authorization: Bearer sk_xxxxxxxx"
# -> {"status":"completed","result_url":"https://...png","cost":0.2,...}

Response Structure

Sync success (HTTP 200, OpenAI Images compatible):

{
  "id": "3e0c77bb-9cbd-4c44-9549-bff1b4060623",
  "created": 1781599773,
  "data": [
    {
      "url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/3e0c77bb-...-1.png"
    }
  ]
}

Async submit (HTTP 202):

{ "status": "pending", "task_id": "d142c93a-de26-40c9-be62-0de840d10960" }

Async task query (GET /v1/images/tasks/{task_id}):

{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gpt-image-2",
  "cost": 0.2,
  "result_url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/d142c93a-...-1.png"
}

• status: pending / completed / failed
• data[].url / result_url: image URL, usable directly in <img src>
• id / task_id: task ID for support troubleshooting

The API always returns URLs and does not support response_format: b64_json. Download the image yourself if you need bytes.

Image URL Behavior

data[].url looks like https://api.icodeeasy.cc/v1/images/files/gpt-image-2/YYYYMMDD/<id>-<seq>.png:

• Open directly: GET returns 302 and redirects to the actual image URL
• Force download: add ?download=1
• Long-term availability: the link stays available long term
• Access control: this path does not require API Key; the full link itself is the credential. Do not post generated result links publicly, because anyone with the full URL can download the image.

Sync Semantics and Timeout

In default sync mode, the request stays open until the image is ready:

• Recommended client HTTP timeout: at least 200 seconds
• One image usually takes 30 to 60 seconds; image-to-image, 2K, or multiple images may take longer
• If you do not want to wait on a long connection, use async mode (?async=1) to get a task_id and poll later

Error Response

Error bodies use:

{
  "error": {
    "type": "server_error",
    "message": "...",
    "provider": "icodeeasy.cc"
  }
}

Common statuses:

• 400 invalid_request_error: invalid parameters, unsupported ratio, more than 4 reference images, non-https reference URL, invalid base64, and similar issues
• 401 authentication_error: missing or invalid API Key
• 402 payment_required: insufficient balance or exhausted monthly quota
• 429 rate_limit_error: rate limit exceeded
• 5xx: service temporarily unavailable or generation failed; retry later

Failed requests are not billed and do not deduct balance.

Billing

Billing is fixed by image count x model / tier in CNY and is unrelated to tokens.

gpt-image-2 is billed by quality tier:

• low: CNY 0.10 / image
• medium / auto (default): CNY 0.20 / image
• high: CNY 0.40 / image

Gemini image models are billed at a fixed per-model price:

In Usage Details, the request is recorded with the actual model, and cost_breakdown includes image_count, image_cost_rmb, and image_urls, so you can copy links or download images from history.

Differences from OpenAI Images API

• Model: use one of the eight featured model IDs above; there is no gpt-image-1 or dall-e-3
• Endpoints: every featured model supports generations; use edits only for models explicitly marked above
• size: aspect ratios such as 16:9 are recommended; pixel strings are also accepted
• resolution: Gemini 2.5 is 1k only; the listed Gemini 3.x models support 1k, 2k, and 4k; gpt-image-2 has no resolution-tier claim
• quality: low, medium, high, or auto; billing only, different from OpenAI standard / hd
• response_format: b64_json is not supported; URLs are always returned
• Reference images: only models marked above accept them; supported requests use image_urls / image_input (JSON) or image[] (multipart), with model-specific limits
• Async mode: OpenAI has no such mode; this API supports ?async=1, returns task_id, and polls /v1/images/tasks/{id} for result
• Task ID: responses include id / task_id for troubleshooting