Skip to content

GPT-image 2.0 โ€‹

Updated

โ† 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 โ€‹

  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, 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 โ€‹

ItemValue
modelcustom-model-og-v2
Supported tasksText-to-image, image 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 / high / medium / low
Return formaturl / b64_json
Guardrail removal supportedNot 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 โ€‹

ParameterRequiredTypeDescription
modelYesStringModel selection: custom-model-og-v2
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)
qualityNoStringSpecifies the quality of the image to be generated. Supports auto, high, medium, low
nNoIntegerNumber of images to generate, 1~10. Default: 1
backgroundNoStringSets 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_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",
    "quality": "low",
    "prompt": "a dancing kitten",
    "size": "2048x2048",
    "n": 1
}'

Response Example

json
{
    "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 โ€‹

ParameterRequiredTypeDescription
modelNoStringModel selection: custom-model-og-v2
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
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
qualityNoStringSpecifies the quality of the image to be generated. Supports auto, high, medium, low
backgroundNoStringSets 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_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. Output Parameters โ€‹

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

4. 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",
    "quality": "low",
    "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' \
--form 'prompt=dancing' \
--form 'image[]=@input.png' \
--form 'n=2' \
--form 'size=2048x2048' \
--form 'quality=low' \
--form 'output_format=png'

Response Example

json
{
    "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 โ€‹

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
DocumentDescription
GPT-image 2.5Adds the xhigh / max quality tiers and markup-based editing
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