Image Generation API

The image API is compatible with the OpenAI Images protocol. The featured, verified inventory below contains sixteen models. Every listed model supports text-to-image through generations; only models explicitly marked for edits should be used with the editing endpoint. See the GPT Image sections below for still images with Image 2, 2.5, and 2.6 and GIFs with Image 2.6.

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 that support editing, compatible with OpenAI native edits usage

GPT Image 2, 2.5, and 2.6 Still Images

All three versions support 1K, 2K, and 4K still images. Use POST /v1/images/generations for text-to-image. For reference-image edits, use POST /v1/images/edits with publicly accessible HTTPS URLs or data:image/...;base64,... values in image_urls. Image 2.6 accepts up to eight references. References for Image 2.6 still images at 2K and 4K must be PNG, JPEG, or WebP.

Select the resolution with image_size. For Image 2, set an aspect ratio such as 16:9 in size. For Image 2.5 and 2.6, use aspect_ratio. For Image 2.6 still images, set output_format: "png" and n: 1.

GPT Image 2 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"
  }'

GPT Image 2.5 text-to-image (2K)

curl -X POST "https://api.icodeeasy.cc/v1/images/generations?sync=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "an orange cat wearing an astronaut helmet, cinematic lighting",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }'

GPT Image 2.5 image-to-image (reference-image edit)

curl -X POST "https://api.icodeeasy.cc/v1/images/edits?sync=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "replace the background with a sunset beach while preserving the pose and clothing",
    "aspect_ratio": "3:2",
    "image_size": "1K",
    "image_urls": ["https://example.com/photo.png"]
  }'

GPT Image 2.6 reference-image edit (4K)

The example uses Sunburst. For Flare, set model to gpt-image-2.6-flare. Replace the example URL with your reference image URL.

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.6-sunburst",
    "prompt": "Replace the background with a pale blue wall. Preserve the cup and the composition of the reference image.",
    "output_format": "png",
    "aspect_ratio": "16:9",
    "image_size": "4K",
    "n": 1,
    "image_urls": [
      "https://example.com/reference.png"
    ]
  }'

GPT Image 2.6 GIF Generation

Use gpt-image-2.6-flare or gpt-image-2.6-sunburst with POST /v1/images/generations. Set output_format: "gif", size: "auto", and n: 1 to generate one GIF with automatic dimensions and frame settings.

Omit image_urls for text-to-GIF. To animate from references, pass up to eight images as publicly accessible HTTPS URLs or data:image/...;base64,... values.

This example uses Flare. Replace the example URL with your own reference image URL. For Sunburst, set model to gpt-image-2.6-sunburst.

curl -X POST 'https://api.icodeeasy.cc/v1/images/generations?async=1' \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "Animate the paper lantern in the reference image swaying gently. Keep the original composition and make it loop seamlessly.",
    "output_format": "gif",
    "size": "auto",
    "n": 1,
    "image_urls": [
      "https://example.com/reference.png"
    ]
  }'

The asynchronous request returns a task_id. Poll GET /v1/images/tasks/{task_id} and download the GIF from result_url once the task completes.

• Text-to-GIF costs ¥0.0833 per result at the standard rate. Flare costs ¥0.30 per result when the fallback service is used.
• GIFs with references are billed by actual usage. The usage record shows the final charge.

FLUX 2 Pro / Max / Flex

Resolution reference prices (CNY / image). Settled by actual generation usage; the final charge is shown on your bill: Charges vary with output dimensions and reference images.

Seedream series

The four new models support basic generation and reference-image editing with up to 8 references. Use an explicit ratio in size / aspect_ratio, choose image_size below, and pass image_input. Each task produces one image; the drawing page batches independent tasks. 5 Flash/Pro ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 2:1, 1:2, 21:9; 4.5/4.0 additionally support 9:21. 4.0 prompts are limited to 1000 characters. Layers, transparent backgrounds, and other advanced features are not enabled. Legacy Lite remains 2K ¥0.30 / 3K ¥0.45.

Reference prices; completed tasks settle at their actual generation charge. Check usage details for the final amount. Seedream 5 Pro only: each reference after the first adds approximately ¥0.01911; actual task charges take priority.

FLUX 3 Image and Klein

flux-3-image and flux-3-image-klein use image_size: 768sq / 1K / 1.5K / 2K / 4K, plus an explicit aspect_ratio: 1:1 / 9:16 / 16:9 / 2:3 / 3:2 / 4:5 / 5:4. Do not send auto or pixel dimensions; the legacy FLUX 2 2048-pixel side limit does not apply. Supply up to 8 references through image_input (URLs or base64 data URLs); bounding-box editing is not supported. Each task generates one image; the drawing page splits multiple images into independent tasks. Image does not support seed; Klein accepts seed from 0 to 4294967295. Neither model supports prompt_upsampling, style, or negative_prompt.

Reference prices; completed tasks settle at their actual generation charge. Check usage details for the final amount.

{
  "model": "flux-3-image",
  "prompt": "A watercolor landscape",
  "aspect_ratio": "16:9",
  "image_size": "4K",
  "image_input": []
}

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

The parameters below apply to still images. For GIF requests, use the parameters in the GPT Image 2.6 GIF section.

• model (required): one of the sixteen featured model IDs in the table above. You can also use the IDs in the GPT Image 2.6 still-image section.
• 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. When GPT Image 2 settles from actual task total cost, image count is not multiplied again.
• size (default 1:1): output aspect ratio. See below. auto is treated as 1:1; pixel strings such as 1536x1024 are also accepted.
• aspect_ratio (optional, default 1:1): output ratio for GPT Image 2.5 and 2.6, such as 16:9.
• image_size (optional, default 1K): GPT Image 2 / 2.5 / 2.6 resolution tier, one of 1K, 2K, or 4K.
• quality: GPT Image 2 accepts low, medium, high, or auto, without quality-based price tiers. GPT Image 2.5 is billed per image and resolution and has no separate quality setting; the field is accepted for legacy requests but does not affect generation parameters or price.
• image_urls / image_input (optional, JSON): reference images for image-to-image, up to 4 images (8 for FLUX 3 and GPT Image 2.6). 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.

GPT Image 2.5 aspect_ratio supports: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 21:9.

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, with 1K, 2K, and 4K resolution reference prices.

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

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",
    "aspect_ratio": "16:9",
    "image_size": "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",
    "aspect_ratio": "16:9",
    "image_size": "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

The GPT Image sections above list still-image prices and GIF billing rules.

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 an ID from the table or the GPT Image 2.6 still-image section
• Endpoints: every featured model supports generations; use edits for models that support editing
• size: aspect ratios such as 16:9 are recommended; pixel strings are also accepted
• aspect_ratio: use this field to set the GPT Image 2.5 or 2.6 output ratio.
• image_size: GPT Image 2 / 2.5 / 2.6 supports 1K, 2K, and 4K; Gemini 2.5 is limited to 1K; the listed Gemini 3.x models support 1K, 2K, and 4K
• quality: GPT Image 2 accepts low, medium, high, or auto, without quality-based price tiers. GPT Image 2.5 is billed per image and resolution and has no separate quality setting; the field is accepted for legacy requests but does not affect generation parameters or price.
• response_format: b64_json is not supported; URLs are always returned
• Reference images: use the format supported by the model, such as 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