Skip to content

GPT-image 2.5 โ€‹

Updated

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

GPT-image 2.5 ships two variants on TokenHub. They are invoked through the same set of endpoints and differ only in the model value:

Model IDPositioning
custom-model-og-v2.5-fFlare โ€” for fast iteration and everyday batch generation
custom-model-og-v2.5-sSunburst โ€” for scenarios demanding editing precision and fine detail

The two share identical request fields and the same token unit price. Choose purely on "speed versus editing precision".

This page is one of three GPT-image API documents. See also GPT-image 2.0 and GPT-image 2.6.

Prerequisites โ€‹

  1. You have registered a Tencent Cloud account and activated the TokenHub service.
  2. Your account has been allowlisted for this model.
  3. You have obtained an API Key. How to do it: go to Online Inference โ€“ Vision Models, search for custom-model-og-v2.5-f and custom-model-og-v2.5-s, enable pay-as-you-go, then create a Key for the model under API-Key management.

Important

  • This model is a test model and requires an allowlist entry granted by the backend team before it can be used. Contact the product team and submit your UIN and AppId.
  • Allowlisting takes effect per model ID โ€” -f and -s must be requested separately.
  • TokenHub settles on an hourly cycle. Sales should apply for customer discounts in good time.

Replace YOUR_API_KEY in every example below with your own API Key. Authentication uses the request header Authorization: Bearer YOUR_API_KEY.

Basic Information โ€‹

ItemValue
modelcustom-model-og-v2.5-f / custom-model-og-v2.5-s
Supported tasksText-to-image, image editing, markup-based editing
Request domain (international site)tokenhub-intl.tencentcloudmaas.com (Singapore)
AuthenticationAuthorization: Bearer <API_KEY>
Result returnSynchronous; the result is contained in the response body
Quality tiersauto / low / medium / high / xhigh / max
Return formaturl / b64_json
Guardrail removal supportedNot supported

What Changed Versus 2.0 โ€‹

ChangeDescription
Two variantsSplit into Flare (fast) and Sunburst (precise) model IDs
Extended quality tiersAdds xhigh and max on top of low / medium / high
Markup-based editingAccepts a transparent PNG annotation layer that circles the region to change

All other parameters, endpoints, data structures, and billing conversions are identical to 2.0.

Submit a Text-to-Image Task โ€‹

1. Endpoint Description โ€‹

  • Request domain (international site): tokenhub-intl.tencentcloudmaas.com (Singapore)
  • Endpoint: POST /v1/wand/og-image/generation

Generates an image synchronously from the input text and returns the result directly.

2. Input Parameters โ€‹

ParameterRequiredTypeDescription
modelYesStringModel selection: custom-model-og-v2.5-f or custom-model-og-v2.5-s
promptNoStringText description. Up to 32,000 characters
sizeNoStringOutput image size. Custom sizes are supported (each side โ‰ค 3840px, width and height multiples of 16, long-to-short side ratio โ‰ค 3:1, total pixels 655,360~8,294,400)
qualityNoStringQuality tier. Supports auto, high, medium, low, plus xhigh and max newly added in 2.5
nNoIntegerNumber of images to generate, 1~10. Default: 1
backgroundNoStringSets the transparency of the generated image background. Must be one of opaque, transparent, auto. With auto, the model determines the best background automatically
output_formatNoStringReturn format of the generated image. Supports png, jpeg
output_compressionNoIntegerCompression level of the generated image (0-100). Supported only by GPT image models when the output format is jpeg
response_formatNoStringReturn format of the generated image. Options: url or b64_json

3. Output Parameters โ€‹

ParameterTypeDescription
output_formatStringReturn format of the generated image. Example: png
qualityStringQuality applied to the generated image. Example: auto
sizeStringSize of the generated image. Example: 1024x1024
backgroundStringBackground transparency applied to the generated image. Example: auto
createdIntegerUnix timestamp (in seconds) of image creation. Example: 1776946569
dataArray of ResultImageList of generated result images
usageUsageToken statistics
request_idStringUnique request ID generated by the server and returned with every request. Provide this RequestId when troubleshooting

4. Examples โ€‹

Request Example

bash
curl --location 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/og-image/generation' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
  -d '{
    "model": "custom-model-og-v2.5-f",
    "quality": "xhigh",
    "prompt": "a dancing kitten",
    "size": "2048x2048",
    "n": 1
}'

Response Example

json
{
    "background": "opaque",
    "created": 1786095835,
    "data": [
        {
            "url": "https://xxxxxxxxxxxx.png"
        }
    ],
    "output_format": "png",
    "quality": "xhigh",
    "size": "2048x2048",
    "usage": {
        "total_tokens": 93323
    },
    "request_id": "eaa4b07b-ccde-40a4-b184-822e3c5a4e60"
}

Submit an Image Editing Task โ€‹

1. Endpoint Description โ€‹

  • Request domain: tokenhub-intl.tencentcloudmaas.com (Singapore)
  • Endpoint: POST /v1/wand/og-image/edits (json)
  • Or: POST /v1/wand/og-image/multipart-edits (multipart)
  • Or: POST /v1/wand/og-image/images/edits (json / multipart)

Generates an image synchronously from the input image and returns the result directly.

2. Input Parameters โ€‹

ParameterRequiredTypeDescription
modelNoStringModel selection: custom-model-og-v2.5-f or custom-model-og-v2.5-s
promptYesStringText description. Up to 32,000 characters
imagesYesArray of ImageRefInput images. Supported count: 1~16
maskNoImageRefUsed for partial regeneration (inpainting); must match the input image size
markupNoImageRefAnnotation layer. A transparent PNG that circles the region to change. See "Markup-Based Editing" below
sizeNoStringOutput image size. Custom sizes are supported (each side โ‰ค 3840px, width and height multiples of 16, long-to-short side ratio โ‰ค 3:1, total pixels 655,360~8,294,400)
nNoIntegerNumber of images to generate, 1~10. Default: 1
qualityNoStringQuality tier. Supports auto, high, medium, low, plus xhigh and max newly added in 2.5
backgroundNoStringSets the transparency of the generated image background. Must be one of transparent, opaque, or auto (default). Example: auto
output_formatNoStringReturn format of the generated image. One of png, jpeg
output_compressionNoIntegerCompression level of the generated image (0-100). Supported only by GPT image models when the output format is jpeg
response_formatNoStringReturn format of the generated image. Options: url or b64_json

transparent Is Available Only in PNG

For a transparent background, use background=transparent together with output_format=png.

3. Markup-Based Editing โ€‹

Use an annotation layer to tell the model where to edit โ€” far more precise than describing the location in words ("move the logo a little to the left").

Constraints

ConstraintDescription
TargetThe markup applies to the first input image only; the remaining inputs act as reference images
File formatMust be a standalone transparent PNG containing transparent pixels; do not flatten the annotation into the source image
Size requirementThe markup layer must match the first input image in width and height exactly
Pixel capThe first input image and the markup layer must each stay under 16,777,216 pixels
File sizeThe markup file must not exceed 50 MB
Mutually exclusiveCannot be used together with mask
Supported endpointsImage editing endpoints only; not supported on the text-to-image endpoint

Request Example (multipart)

bash
curl --location 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/og-image/multipart-edits' \
--header 'Authorization: Bearer YOUR_API_KEY'  \
--form 'model=custom-model-og-v2.5-s' \
--form 'quality=medium' \
--form 'image[]=@kitchen.png' \
--form 'markup=@markup-overlay.png' \
--form 'prompt=change the striped vase inside the red circle to solid cobalt blue ceramic'

4. Output Parameters โ€‹

Identical to the text-to-image endpoint; see above.

5. Examples โ€‹

Request Example (json)

bash
curl --location 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/og-image/edits' \
--header 'Authorization: Bearer YOUR_API_KEY'  \
--header 'Content-Type: application/json' \
  -d '{
    "model": "custom-model-og-v2.5-s",
    "quality": "max",
    "prompt": "dancing",
    "images": [{ "image_url": "https://xxxxxxxxxxxx.png"}],
    "size": "2048x2048",
    "n": 2
}'

Request Example (multipart)

bash
curl --location 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/og-image/multipart-edits' \
--header 'Authorization: Bearer YOUR_API_KEY'  \
--form 'model=custom-model-og-v2.5-f' \
--form 'prompt=dancing' \
--form 'image[]=@input.png' \
--form 'n=2' \
--form 'size=2048x2048' \
--form 'quality=high' \
--form 'output_format=png'

Response Example

json
{
    "background": "opaque",
    "created": 1786096322,
    "data": [
        {
            "url": "https://xxxxxxxxxxxx.png"
        },
        {
            "url": "https://xxxxxxxxxxxx.png"
        }
    ],
    "output_format": "png",
    "quality": "max",
    "size": "2048x2048",
    "usage": {
        "total_tokens": 183284
    },
    "request_id": "705d12d2-9f68-4cfa-859a-733e449ea675"
}

Data Structures โ€‹

ResultImage โ€‹

ParameterTypeDescription
urlStringURL of the returned image

Usage โ€‹

ParameterTypeDescription
total_tokensIntegerToken statistics

ImageRef โ€‹

NameTypeRequiredDescription
image_urlStringNoImages support png and jpg. Pass either the image URL or base64-encoded data. Example: https://xxxxxxxxxxx.png

Billing and Pricing โ€‹

  • Billing mode: Pay-as-you-go (by token), postpaid.
  • Settlement cycle: The system aggregates and settles your resource consumption hourly.
  • Pricing logic: Cost is determined by token usage and the corresponding unit price: total cost = token usage ร— token unit price.
  • Usage notes: A unified unit price of 1.6 USD per million tokens applies. The conversion against upstream vendor tokens is shown below.
Token typeVendor USD unit priceTokenHub priceConversion factor
text input$5.00 / million$1.60 / million3.125
text cached$1.25 / million$1.60 / million0.78125
image input$8.00 / million$1.60 / million5.0
image cached$2.00 / million$1.60 / million1.25
image output$30.00 / million$1.60 / million18.75

USD Settlement Logic (International Site)

text input tokens ร— 3.125
+ text cached input tokens ร— 0.78125
+ image input tokens ร— 5
+ image cached input tokens ร— 1.25
+ output image tokens ร— 18.75
= token consumption of a single task

Quality Tiers and Token Consumption

The higher the quality tier, the more output image tokens are produced and the higher the cost. Use low tiers for batch drafts and reserve xhigh / max for final renders.

DocumentDescription
GPT-image 2.0The base version, with quality tiers up to high
GPT-image 2.6Adds the complexity planning tier, animated GIF, and SVG vector output
Get an API KeyApplying for and managing TokenHub API Keys

Built with VitePress ยท Deployed on Tencent EdgeOne Pages