Skip to content

GPT-Image 2.5 โ€‹

Updated

โ† Back to the GPT-Image overview for a version comparison and selection guide.

Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcImageTask

GPT-Image 2.5 splits the 2.0 series into two variants and extends the quality tiers from three to five:

VariantPositioningBest for
sunburstEditing precisionComplex compositions, fine-grained revisions, small text rendering
flareSpeedBatch output, prompt iteration, interactive previews

This page is one of three GPT-Image API documents. See also GPT-Image 2.0 and GPT-Image 2.6. 2.6 uses the same basic call as this page and adds GIF / SVG output, so new integrations should go straight to 2.6.

Basic information โ€‹

ItemValue
ModelNameOG
ModelVersionimage2.5_sunburst_* / image2.5_flare_* โ€” * is a placeholder, not a value you can pass; see ModelVersion enumeration for all 10 actual values
Result pollingDescribeTaskDetail
Guardrail bypassNot supported

ModelVersion enumeration โ€‹

Five tiers per variant, 10 values in total.

Tiersunburstflare
lowimage2.5_sunburst_lowimage2.5_flare_low
mediumimage2.5_sunburst_mediumimage2.5_flare_medium
highimage2.5_sunburst_highimage2.5_flare_high
xhighimage2.5_sunburst_xhighimage2.5_flare_xhigh
maximage2.5_sunburst_maximage2.5_flare_max

Choosing a quality tier โ€‹

Higher tiers mean higher fidelity, but also longer generation times and higher cost.

TierCharacteristicsRecommended for
lowFastest generation, lowest costQuick drafts, batch testing, prompt iteration
mediumThe sweet spot between speed, cost, and qualityMost day-to-day production and general design work
highRicher detail, texture, lighting and shadowReview-ready output, images that need careful rendering
xhighHigher fidelity than highFinal review, upscaled use
maxHighest fidelity; strong on complex text and small typeFinal deliverables, print material, high-precision product shots

Generation time per tier โ€‹

Measured with the same prompt at 1024x1024. Actual times vary with network conditions and server load, so treat these as order-of-magnitude references.

Variantlowmediumhighxhighmax
sunburst30 s30 s53 s92 s169 s
flare22 s22 s35 s41 s61 s

flare is clearly faster at every tier, and the gap widens as the tier rises โ€” nearly 3ร— at max.

Request parameters โ€‹

ParameterRequiredTypeDescription
SubAppIdYesIntegerSubapplication ID
ModelNameYesStringFixed value OG
ModelVersionNoStringModel version, e.g. image2.5_sunburst_medium. Defaults to the engine default image2_medium (the 2.0 series) when omitted
PromptYesStringGeneration prompt, up to 32,000 characters
FileInfos.NNoArrayReference images (image-to-image), up to 16. Acts as a mask when ReferenceType=mask. See Passing reference images
OutputConfig.StorageModeNoStringTemporary (7-day retention) / Permanent (returns a FileId)
OutputConfig.ResolutionNoString1K / 2K / 4K
OutputConfig.AspectRatioNoString1:1 / 3:2 / 2:3 / 3:4 / 4:3 / 16:9 / 9:16 / 21:9 / 9:21
OutputConfig.OutputImageCountNoIntegerNumber of images; 1โ€“8 for OG
OutputConfig.OutputFormatNoStringjpeg / png. Follows the model default when omitted. GIF / SVG output is 2.6 only
OutputConfig.PersonGenerationNoStringAllowAdult / Disallowed (no people or faces in the image)
OutputConfig.InputComplianceCheckNoStringInput compliance check: Enabled / Disabled
OutputConfig.OutputComplianceCheckNoStringOutput compliance check: Enabled / Disabled
OutputConfig.LogoAddNoStringAdd a logo watermark: Enabled / Disabled
InputRegionNoStringInput region: Mainland (Chinese mainland) / Oversea (outside the Chinese mainland) / OverseaUSWest (US West)
ExtInfoNoStringJSON string carrying model-specific options; see Special settings
SessionContextNoStringSession identifier echoed back in the callback

Request example โ€‹

json
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_sunburst_medium",
  "Prompt": "a serene japanese garden, soft morning light",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "1:1",
    "OutputImageCount": 1
  },
  "SessionContext": "job-001"
}

Response example โ€‹

json
{
  "AigcImageTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Progress": 100,
    "Output": {
      "FileInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcImageGenFile.png",
          "ExpireTime": "2026-08-01T10:29:48Z",
          "MetaData": {
            "Width": 1024,
            "Height": 1024,
            "Container": "png"
          }
        }
      ]
    }
  }
}

Special settings โ€‹

Everything below works identically across the 2.0 / 2.5 / 2.6 series (the 2.6-only GIF / SVG output is covered in the 2.6 document).

Passing reference images โ€‹

Each FileInfos entry declares its source with Type:

TypeCompanion fieldDescription
FileFileIdVOD media file ID
UrlUrlPublicly accessible image URL
Base64Base64Base64-encoded image

Base64 limits

  • The total size of all files must not exceed 7 MB, so the Base64-encoded request stays under the 10 MB Cloud API body limit;
  • Images must be jpeg / jpg / png / webp;
  • Do not include a prefix such as data:image/jpeg;base64,.

Multiple reference images โ€‹

A single request accepts multiple reference images, up to 16. Use it for image editing, style transfer, and multi-image fusion (background swaps, element composition, and so on).

json
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_sunburst_medium",
  "FileInfos": [
    { "Type": "Url", "Url": "https://<cos>/room.png" },
    { "Type": "Url", "Url": "https://<cos>/fabric.jpg" }
  ],
  "Prompt": "redesign this room with the material palette of the second image, keep the layout unchanged",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "9:16"
  },
  "SessionContext": "job-001"
}

Multi-image output (OutputImageCount) โ€‹

OutputConfig.OutputImageCount sets how many images one request generates. OG accepts 1โ€“8 (limits differ per engine; Kling accepts 1โ€“9).

json
{
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "9:16",
    "OutputImageCount": 3
  }
}

Custom resolution (size) โ€‹

Set the output resolution directly through size inside ExtInfo.

ConstraintValue
Width and heightBoth multiples of 16
Longest edgeAt most 3840px (that is, no larger than 4K)
Total pixels655,360 โ€“ 8,294,400
json
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_flare_high",
  "Prompt": "a serene japanese garden, soft morning light",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "9:16"
  },
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\": \\\"2000x1104\\\"}\"}",
  "SessionContext": "job-001"
}

Common presets are 1024x1024 (square), 1536x1024 (landscape), and 1024x1536 (portrait). 2K (2560x1440) and 4K (3840x2160) output is also available, though anything above 2560px is experimental.

auto mode โ€‹

Set size to auto and the model decides the resolution from the input.

json
{
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"size\\\": \\\"auto\\\"}\"}"
}

Do not pass auto for AspectRatio

When size is auto, AspectRatio still needs a concrete ratio โ€” it must not be auto as well.

Mask-based image editing โ€‹

Include an image with ReferenceType=mask in FileInfos to mask the region you want edited. The mask and the source image each take one entry.

json
{
  "SubAppId": 123456789,
  "ModelName": "OG",
  "ModelVersion": "image2.5_sunburst_medium",
  "FileInfos": [
    {
      "Type": "Url",
      "Url": "https://<cos>/room-mask.png",
      "ReferenceType": "mask"
    },
    {
      "Type": "Url",
      "Url": "https://<cos>/room.png"
    }
  ],
  "Prompt": "the same sunny indoor lounge with a pool, but with a flamingo standing in the pool",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "AspectRatio": "9:16"
  },
  "SessionContext": "job-001"
}

Transparent background โ€‹

Set background to transparent inside ExtInfo to generate an image with a transparent background.

json
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"background\\\":\\\"transparent\\\"}\"}"

VOD and MPS place this option differently

The same OG engine takes the transparent-background option in different places: VOD nests it in AdditionalParameters inside ExtInfo (the JSON string is double-encoded), whereas MPS takes AdditionalParameters at the top level.

Output format (OutputFormat) โ€‹

OutputConfig.OutputFormat sets the output format. The model default applies when omitted.

json
{
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Resolution": "1K",
    "OutputFormat": "png"
  }
}
ValueDescription
jpegJPEG output
pngPNG output

Choose png when you need lossless output, or when post-processing touches the alpha channel or fine gradients; jpeg is better when file size matters more than fidelity. Transparent backgrounds require png.

Text rendering โ€‹

Multilingual text rendering covers Chinese, English, Japanese, Korean, Arabic, and more. The max tier handles complex text and small type best.

DocumentDescription
GPT-Image overviewVersion comparison and shared specifications
GPT-Image 2.6Latest series, same call as this page, plus GIF / SVG output
GPT-Image 2.0Base series, quality tiers up to high
VOD quick startAuthentication, task submission, and result polling for the VOD API

Built with VitePress ยท Deployed on Tencent EdgeOne Pages