GPT-image 2.0 โ
โ Back to the GPT-image overview for a version comparison and selection guide.
GPT-image 2.0 maps to the model ID custom-model-og-v2 and is invoked synchronously through the TokenHub path. It supports both text-to-image and image editing. The result is already contained in the response body when the request returns โ no task polling required.
This page is one of three GPT-image API documents. For version selection, see GPT-image 2.5 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, enable pay-as-you-go, then create a Key for that 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.
- 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 |
| Supported tasks | Text-to-image, image 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 / high / medium / low |
| Return format | url / b64_json |
| Guardrail removal supported | Not supported |
Region-Specific Endpoints
The address above is for Singapore. For region-specific addresses and backup addresses such as Guangzhou and Silicon Valley, see the API usage guide.
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 |
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 | Specifies the quality of the image to be generated. Supports auto, high, medium, low |
n | No | Integer | Number of images to generate, 1~10. Default: 1 |
background | No | String | Sets the transparency of the generated image background. This parameter is supported only by GPT image models. 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",
"quality": "low",
"prompt": "a dancing kitten",
"size": "2048x2048",
"n": 1
}'Response Example
{
"background": "opaque",
"created": 1786095835,
"data": [
{
"url": "https://xxxxxxxxxxxx.png"
},
{
"url": "https://xxxxxxxxxxxx.png"
}
],
"output_format": "png",
"quality": "low",
"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 |
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 |
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 | Specifies the quality of the image to be generated. Supports auto, high, medium, low |
background | No | String | Sets the transparency of the generated image background. This parameter is supported only by GPT image models. Must be one of transparent, opaque, or auto (default). With auto, the model determines the best background automatically. 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. Output Parameters โ
Identical to the text-to-image endpoint; see above.
4. 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",
"quality": "low",
"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' \
--form 'prompt=dancing' \
--form 'image[]=@input.png' \
--form 'n=2' \
--form 'size=2048x2048' \
--form 'quality=low' \
--form 'output_format=png'Response Example
{
"background": "opaque",
"created": 1786096322,
"data": [
{
"url": "https://xxxxxxxxxxxx.png"
},
{
"url": "https://xxxxxxxxxxxx.png"
}
],
"output_format": "png",
"quality": "low",
"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 taskRelated Documents โ
| Document | Description |
|---|---|
| GPT-image 2.5 | Adds the xhigh / max quality tiers and markup-based editing |
| 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 |