GPT Image 2.5 Image Generation

curl --request POST \
  --url https://api.evolink.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "A beautiful colorful sunset over the ocean"
}
'

{
  "created": 1757156493,
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "gpt-image-2.5-sunburst",
  "object": "image.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 100
  },
  "type": "image",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 2.5,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: gpt-image-2.5-sunburst",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

POST

images

generations

curl --request POST \
  --url https://api.evolink.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "A beautiful colorful sunset over the ocean"
}
'

{
  "created": 1757156493,
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "gpt-image-2.5-sunburst",
  "object": "image.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 100
  },
  "type": "image",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 2.5,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: gpt-image-2.5-sunburst",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

Authorizations

Authorization

string

header

required

##All APIs require Bearer Token authentication##

Get API Key:

Visit API Key Management Page to get your API Key

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

application/json

model

enum<string>

default:gpt-image-2.5-sunburst

required

Image generation model name, official channel, better stability and controllability, suitable for commercial scenarios

Model ID	Positioning
`gpt-image-2.5-sunburst`	Editing precision above all, suited to workflows where edit fidelity matters most
`gpt-image-2.5-flare`	Faster output, suited to high-quality everyday batch generation

Both models take exactly the same parameters; at the same quality tier the actual token consumption may differ slightly, so rely on the returned usage.

Available options:

gpt-image-2.5-sunburst,

gpt-image-2.5-flare

Example:

"gpt-image-2.5-sunburst"

prompt

string

required

Prompt describing the image to generate or how to edit the input image

Length limits (both must be met):

Up to 32,000 characters (counted as Unicode code points)
The prompt text itself must not exceed 60,000 bytes when encoded in UTF-8

Different characters use different numbers of UTF-8 bytes. Use the actual encoded byte count.

If either limit is exceeded, shorten the prompt before resubmitting.

Recommendation: If the prompt exceeds 8000 tokens, the generated image may not match expectations; shortening the prompt is recommended.

Maximum string length: 32000

Example:

"A beautiful colorful sunset over the ocean"

image_urls

string<uri>[]

Reference image URL list for image-to-image and image editing functions

Note:

Number of input images per request: 1~16
Size of a single image: not exceeding 50MB
Pixels of a single image: width × height not exceeding 178,956,970 px
Side length of a single image: width / height each not exceeding 23170 px; exceeding this may cause errors
Supported file formats: .jpeg, .jpg, .png, .webp
Image URLs must be directly accessible by the server, or the image URL should directly download when accessed (typically these URLs end with image file extensions, such as .png, .jpg)
In image-to-image / image editing scenarios, the reference images themselves also incur additional image input token consumption

Example:

[
  "https://example.com/image1.png",
  "https://example.com/image2.png"
]

mask_url

string<uri>

Inpainting mask URL — marks the region of the reference image to regenerate. Only valid in image edit mode (must be combined with image_urls); the mask is silently ignored in pure text-to-image requests.

Format requirements:

Must be a PNG with an alpha channel: transparent pixels (alpha < 255) = regions to regenerate; opaque pixels = preserved
Mask dimensions must exactly match the reference image dimensions (width × height in pixels)
Single mask per request

Note:

At least one reference image is required in image_urls; a mask sent alone has no effect
Common errors:
- Invalid mask image format - mask image missing alpha channel: the uploaded image has no alpha channel (JPEG, opaque PNG, etc.). Re-export the mask as a PNG with transparent regions.
- Invalid mask image format - mask size does not match image size: the mask dimensions don't match the reference image. Resize the mask to the same pixel dimensions as your reference image.

Example:

"https://example.com/mask.png"

size

string

default:auto

Size of the generated image. Supports both ratio format and explicit pixel format, defaults to auto

① Ratio format (recommended, 15 options)

1:1: Square
1:2 / 2:1: Extreme portrait / landscape
1:3 / 3:1: Ultra portrait / landscape (3:1 limit)
2:3 / 3:2: Standard portrait / landscape
3:4 / 4:3: Classic portrait / landscape
4:5 / 5:4: Common social media
9:16 / 16:9: Mobile / desktop widescreen
9:21 / 21:9: Ultra-wide

② Explicit pixel format: WxH (or W×H), e.g. 1024x1024, 1536x1024, 3840×2160

Both width and height must be multiples of 16
Each edge range: [16, 3840]
Pixel budget: 655,360 ≤ width × height ≤ 8,294,400 (about 0.65 MP ~ 8.29 MP)
Aspect ratio: ≤ 3:1

③ auto: The model decides the size automatically (resolution does not apply in this mode)

Out-of-range handling:

If a ratio + resolution combination exceeds the pixel budget, dimensions are automatically scaled down proportionally (e.g. 4K 2:1 → 3840×1920)

Example:

"auto"

resolution

enum<string>

default:1K

Resolution tier shortcut, only effective when size is a ratio; ignored in explicit pixel mode

Pixel budget rules (dimensions are derived from the target pixel count and the size ratio, aligned to multiples of 16):

1K: ~1 MP (1024² = 1,048,576 pixels)
2K: ~4 MP (2048² = 4,194,304 pixels)
4K: ~8.29 MP (3840×2160 = 8,294,400 pixels, the maximum)

Landscape / square output dimensions (portrait dimensions are the landscape width/height swapped, e.g. 2:3 = 3:2 reversed):

Ratio	1K	2K	4K
`1:1`	1024×1024	2048×2048	2880×2880
`2:1`	1456×720	2896×1456	3840×1920 *
`3:1`	1776×592	3552×1184	3840×1280 *
`3:2`	1248×832	2512×1680	3520×2352
`4:3`	1184×880	2368×1776	3312×2480 *
`5:4`	1152×912	2288×1824	3216×2576
`16:9`	1360×768	2736×1536	3840×2160 (UHD)
`21:9`	1568×672	3136×1344	3840×1648 *

* Marks combinations that are auto-downscaled to fit the pixel budget. Values are case-insensitive.

Available options:

1K,

2K,

4K

Example:

"1K"

quality

enum<string>

default:medium

Rendering quality that controls the model's "reasoning depth", directly affecting output token count and cost. Defaults to medium

Value	Tile base	Output tokens (1024²)	Relative cost (1024²)
`low`	16	196	~0.45×
`medium`	24	439	1.0×
`high`	48	1,756	~4.0×
`xhigh`	64	3,122	~7.1×
`max`	96	7,024	~16.0×

Note:

The tiers are more fine-grained than on GPT Image 2: low costs the same on both, while medium and high use only 1/4 of the output tokens of the same-named tier on GPT Image 2; high on 2.5 matches medium on GPT Image 2, and only max on 2.5 matches high on GPT Image 2
The table is calculated for 1024×1024; output token count varies with the total pixel count and the aspect ratio, so rely on the returned usage
Use low for quick drafts; for final assets, compare a few tiers to balance detail, latency and cost

Available options:

low,

medium,

high,

xhigh,

max

Example:

"medium"

background

enum<string>

default:opaque

Alpha channel of the output image. Defaults to opaque

opaque: Flat background, no alpha channel
transparent: Keeps the alpha channel

Note:

transparent is a Preview feature and results may be unstable
When using transparent, output_format must be png or webp

Available options:

opaque,

transparent

Example:

"opaque"

output_format

enum<string>

default:png

Output image file format. Defaults to png

png: Lossless, supports transparent backgrounds
jpeg: Lossy compression, smaller files
webp: Balances file size and quality, also supports transparent backgrounds

Note:

When background is transparent, only png or webp can be used; jpeg cannot carry an alpha channel

Available options:

png,

jpeg,

webp

Example:

"png"

integer

default:1

Number of images to generate, each billed independently

Note:

Text input tokens scale linearly with n
The official model's support for n > 1 is currently unreliable: even with a value greater than 1, only one image is often returned. The actual count is whatever results holds in the response, and billing follows the returned usage. If you need several images, send multiple single-image requests instead

Required range: 1 <= x <= 10

Example:

1

callback_url

string<uri>

HTTPS callback address after task completion

Callback Timing:

Triggered when task is completed, failed, or cancelled
Sent after billing confirmation is completed

Security Restrictions:

Only HTTPS protocol is supported
Callback to internal IP addresses is prohibited (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, etc.)
URL length must not exceed 2048 characters

Callback Mechanism:

Timeout: 10 seconds
Maximum 3 retries on failure (retries after 1 second/2 seconds/4 seconds)
Callback response body format is consistent with the task query API response format
Callback address returning 2xx status code is considered successful, other status codes will trigger retry

Example:

"https://your-domain.com/webhooks/image-task-completed"

Response

Image generation task created successfully

created

integer

Task creation timestamp

Example:

1757156493

string

Task ID

Example:

"task-unified-1757156493-imcg5zqt"

model

string

Actual model name used

Example:

"gpt-image-2.5-sunburst"

object

enum<string>

Specific task type

Available options:

image.generation.task

progress

integer

Task progress percentage (0-100)

Required range: 0 <= x <= 100

Example:

0

status

enum<string>

Task status

Available options:

pending,

processing,

completed,

failed

Example:

"pending"

task_info

object

Asynchronous task information

Show child attributes

type

enum<string>

Task output type

Available options:

text,

image,

audio,

video

Example:

"image"

usage

object

Usage and billing information

Show child attributes

Image Series

Video Series

Audio Series

Text Series

Account Management

Task Management

File Management

GPT Image 2.5 Image Generation

Authorizations

Body

Response