Image Generation API

This OpenAI Images-compatible API supports image generation, editing, and asynchronous task queries.

Endpoint and Authentication

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/edits
GET  https://api.icodeeasy.cc/v1/images/tasks/{task_id}

Some models accept reference images on generations. Use edits with models that support editing.

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

Set the ICODEEASY_API_KEY environment variable in your terminal before running the examples.

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

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

GPT Image 2 text-to-image (sync)

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -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 $ICODEEASY_API_KEY" \
  -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"
  }'

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.

Image-to-image using image URL (JSON)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -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 $ICODEEASY_API_KEY" \
  -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 $ICODEEASY_API_KEY" \
  -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..."
    ]
  }'

Submit an asynchronous edit

curl -X POST "https://api.icodeeasy.cc/v1/images/edits?async=1" \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -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-..."}

Save the task_id from the HTTP 202 response and query the task to get the result.

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" }

Get image task status

curl -sS 'https://api.icodeeasy.cc/v1/images/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

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.

A task query can return HTTP 200 with status: failed. Display the error message. When present, error_detail contains type, message, retryable, charged, and optional code, moderation_stage, and categories. Use retryable to decide whether to create a new task. If it is absent, inspect the error before resubmitting. For HTTP 404, check the task ID and the account that submitted it.

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: save the I Code Easy URL returned by the API. The 302 redirect target can change.
• 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, such as an unsupported ratio, too many references for the selected model or mode, a non-HTTPS reference URL, or invalid base64
• 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.

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): use an ID from featured models or 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. Limits depend on the model and mode. The four Seedream models in featured models, FLUX 3, and GPT Image 2.6 accept up to 8 references. The Gemini models in the table accept up to 4. 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.

Differences from OpenAI Images API

• See featured models for accepted model IDs and editing support.
• Check the request parameters for aspect ratios, resolution, and reference image formats.
• Results contain image URLs. In async mode, save the task ID and query the result.

Featured models

All 16 verified models in the table support text-to-image through generations. The table shows which also support the editing endpoint.

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.

See the request examples for a synchronous GPT Image 2 text-to-image request.

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": []
}

Billing

See GPT Image 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.