GPT-image 2.5 โ
โ 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 ID | Positioning |
|---|---|
custom-model-og-v2.5-f | Flare โ for fast iteration and everyday batch generation |
custom-model-og-v2.5-s | Sunburst โ 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 โ
- You have registered a Tencent Cloud account and activated the TokenHub service.
- Your account has been allowlisted for this model.
- You have obtained an API Key. How to do it: go to Online Inference โ Vision Models, search for
custom-model-og-v2.5-fandcustom-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 โ
-fand-smust 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 โ
| Item | Value |
|---|---|
| model | custom-model-og-v2.5-f / custom-model-og-v2.5-s |
| Supported tasks | Text-to-image, image editing, markup-based editing |
| Request domain (international site) | tokenhub-intl.tencentcloudmaas.com (Singapore) |
| Authentication | Authorization: Bearer <API_KEY> |
| Result return | Synchronous; the result is contained in the response body |
| Quality tiers | auto / low / medium / high / xhigh / max |
| Return format | url / b64_json |
| Guardrail removal supported | Not supported |
What Changed Versus 2.0 โ
| Change | Description |
|---|---|
| Two variants | Split into Flare (fast) and Sunburst (precise) model IDs |
| Extended quality tiers | Adds xhigh and max on top of low / medium / high |
| Markup-based editing | Accepts 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 โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | Yes | String | Model selection: custom-model-og-v2.5-f or custom-model-og-v2.5-s |
prompt | No | String | Text description. Up to 32,000 characters |
size | No | String | Output 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) |
quality | No | String | Quality tier. Supports auto, high, medium, low, plus xhigh and max newly added in 2.5 |
n | No | Integer | Number of images to generate, 1~10. Default: 1 |
background | No | String | Sets the transparency of the generated image background. Must be one of opaque, transparent, auto. With auto, the model determines the best background automatically |
output_format | No | String | Return format of the generated image. Supports png, jpeg |
output_compression | No | Integer | Compression level of the generated image (0-100). Supported only by GPT image models when the output format is jpeg |
response_format | No | String | Return format of the generated image. Options: url or b64_json |
3. Output Parameters โ
| Parameter | Type | Description |
|---|---|---|
output_format | String | Return format of the generated image. Example: png |
quality | String | Quality applied to the generated image. Example: auto |
size | String | Size of the generated image. Example: 1024x1024 |
background | String | Background transparency applied to the generated image. Example: auto |
created | Integer | Unix timestamp (in seconds) of image creation. Example: 1776946569 |
data | Array of ResultImage | List of generated result images |
usage | Usage | Token statistics |
request_id | String | Unique request ID generated by the server and returned with every request. Provide this RequestId when troubleshooting |
4. Examples โ
Request Example
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
{
"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 โ
| Parameter | Required | Type | Description |
|---|---|---|---|
model | No | String | Model selection: custom-model-og-v2.5-f or custom-model-og-v2.5-s |
prompt | Yes | String | Text description. Up to 32,000 characters |
images | Yes | Array of ImageRef | Input images. Supported count: 1~16 |
mask | No | ImageRef | Used for partial regeneration (inpainting); must match the input image size |
markup | No | ImageRef | Annotation layer. A transparent PNG that circles the region to change. See "Markup-Based Editing" below |
size | No | String | Output 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) |
n | No | Integer | Number of images to generate, 1~10. Default: 1 |
quality | No | String | Quality tier. Supports auto, high, medium, low, plus xhigh and max newly added in 2.5 |
background | No | String | Sets the transparency of the generated image background. Must be one of transparent, opaque, or auto (default). Example: auto |
output_format | No | String | Return format of the generated image. One of png, jpeg |
output_compression | No | Integer | Compression level of the generated image (0-100). Supported only by GPT image models when the output format is jpeg |
response_format | No | String | Return 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
| Constraint | Description |
|---|---|
| Target | The markup applies to the first input image only; the remaining inputs act as reference images |
| File format | Must be a standalone transparent PNG containing transparent pixels; do not flatten the annotation into the source image |
| Size requirement | The markup layer must match the first input image in width and height exactly |
| Pixel cap | The first input image and the markup layer must each stay under 16,777,216 pixels |
| File size | The markup file must not exceed 50 MB |
| Mutually exclusive | Cannot be used together with mask |
| Supported endpoints | Image editing endpoints only; not supported on the text-to-image endpoint |
Request Example (multipart)
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)
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)
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
{
"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 โ
| Parameter | Type | Description |
|---|---|---|
url | String | URL of the returned image |
Usage โ
| Parameter | Type | Description |
|---|---|---|
total_tokens | Integer | Token statistics |
ImageRef โ
| Name | Type | Required | Description |
|---|---|---|---|
image_url | String | No | Images 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 tokensapplies. The conversion against upstream vendor tokens is shown below.
| Token type | Vendor USD unit price | TokenHub price | Conversion factor |
|---|---|---|---|
| text input | $5.00 / million | $1.60 / million | 3.125 |
| text cached | $1.25 / million | $1.60 / million | 0.78125 |
| image input | $8.00 / million | $1.60 / million | 5.0 |
| image cached | $2.00 / million | $1.60 / million | 1.25 |
| image output | $30.00 / million | $1.60 / million | 18.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 taskQuality 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.
Related Documents โ
| Document | Description |
|---|---|
| GPT-image 2.0 | The base version, with quality tiers up to high |
| GPT-image 2.6 | Adds the complexity planning tier, animated GIF, and SVG vector output |
| Get an API Key | Applying for and managing TokenHub API Keys |