tencent cloud

LLM Service TokenHub

HiDream Image Generation API Guide

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-11-09 20:18:51
AI翻訳

Overview

HiDream-O1 is an image generation model series launched by HiDream.ai. This document describes how to call the HiDream image generation models HiDream-O1-Image-1.5 (hidream-image-o1-1.5) and HiDream-O1-Image-Edit-1.5 (hidream-image-o1-1.5-edit) through TokenHub:
HiDream-O1-Image-1.5: generates images synchronously from text prompts with native 2K output, supports 7 common aspect ratios, and excels at rendering Chinese and English text and numbers, complex layouts, and multi-subject control.
HiDream-O1-Image-Edit-1.5: generates images synchronously from text prompts combined with 1 to 6 reference images, supports natural language instruction editing (style changes, color adjustments, adding or removing elements, background replacement, and in-image text rewriting) and multi-image reference for subject consistency, without the need for masks.
Note:
Both models use synchronous calls: a single request directly returns the generated result without the need to submit a task or poll. Image generation typically takes 30 to 120 seconds, so set the client timeout to no less than 300 seconds.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
Enable postpaid billing for the corresponding model in Console - Online Inference - Vision Models.
Note:
In all examples below, replace YOUR_API_KEY with your own API Key. The authentication method is the request header Authorization: Bearer YOUR_API_KEY.

Model List

Model name
model Parameter Value
Supported Capability
Input Limit
Size Constraint
Brief Description
HiDream-O1-Image-1.5
hidream-image-o1-1.5
Text-to-image generation (synchronous)
5000 characters
7 preset sizes, native 2K
A primary text-to-image model that excels in text rendering, complex layouts, long prompt comprehension, and multi-subject control, suitable for scenarios such as e-commerce hero images, marketing posters, brand materials, and film storyboards.
HiDream-O1-Image-Edit-1.5
hidream-image-o1-1.5-edit
Image-to-image generation / image editing (synchronous)
5000 characters; 1 to 6 reference images
7 preset sizes, native 2K
Edit with natural language instructions without masks. Multiple reference images can lock the appearance of characters, products, or IPs, making the model suitable for product retouching, background replacement, poster revision, and character extension.

HiDream-O1-Image-1.5 Text-to-Image

1. API Description

Enter a text prompt to generate an image synchronously. If size is not specified or is set to auto, the model automatically determines the output size. For available sizes, see the appendix "Supported Size List".
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hidream-image/images/generations

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model ID. Value: hidream-image-o1-1.5
prompt
Yes
string
Text prompt used for image generation, with a length no greater than 5000 characters.
size
No
string
Generated size, in the format ${width}x${height}. Supports 7 options: 2048x2048 (1:1), 2304x1728 (4:3), 1728x2304 (3:4), 2560x1440 (16:9), 1440x2560 (9:16), 2496x1664 (3:2), 1664x2496 (2:3). If auto is passed or not passed, the model adaptively determines the output size.

3. Request Example

# Text-to-image
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hidream-image/images/generations' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"model": "hidream-image-o1-1.5",
"prompt": "A golden retriever running on the beach in warm evening light",
"size": "2048x2048"
}'

4. Output Parameters

Parameter Name
Type
Description
created
integer
Unix timestamp (in seconds).
data
array
Array of generated image content returned.
data[n].item_index
integer
Index of the image in this request, starting from 0.
data[n].url
string
The generated image URL is temporary and valid for 12 hours. Download and save it promptly.
request_id
string
Unique request ID for troubleshooting.
tokenhub_usage
object
Usage consumption.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.

5. Response Example

{
"created": 1793780017,
"data": [
{
"item_index": 0,
"url": "https://xxx.png"
}
],
"request_id": "c9a668db-041b-4edc-bf1f-df657c1d332e",
"tokenhub_usage": {
"total_tokens": 60000
}
}
The returned url is a temporary address valid for 12 hours. Because the address requires authentication, accessing it directly through a browser address bar may be denied. We recommend downloading it in one of the following ways:
curl -o generated_image.png 'https://xxx.png'
Or use an HTTP client in your code to download and save it to local storage.

6. Error Codes

HTTP Status Code
Description
Recommended Solution
400
The request format is incorrect.
Check the request body field types/values (such as the size value, prompt length, and model name).
401
Authentication failed.
Check whether the API_KEY is valid and whether the Authorization uses the Bearer format.
422
Input or output failed moderation (blocked by content safety).
Input or output triggers content safety moderation. Adjust the prompt or business policy.
429
The number of concurrent requests exceeds the limit.
The concurrency limit is reached. Retry with backoff and control the call concurrency.
500
Internal error.
A server exception occurs. Retry the request. If the failure persists, contact technical support and provide the request_id.

HiDream-O1-Image-Edit-1.5 Image-to-Image / Image Editing

1. API Description

Enter a text prompt and reference images to generate the edited image synchronously. When a single reference image is provided, the image is edited according to the instructions. When multiple reference images are provided, the appearance of a person, product, or IP in the images can be locked to maintain subject consistency in a new scene.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hidream-image/images/edits
Two request methods are supported: application/json (by passing image URLs) and multipart/form-data (by uploading local image files).

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model ID. Value: hidream-image-o1-1.5-edit
prompt
Yes
string
Text prompt used for image generation, describing the editing intent for the reference image. Length: no more than 5000 characters.
images
Yes
array[string]
List of reference images, supporting 1 to 6 images. Image URLs must be publicly accessible (http/https). For multipart/form-data, upload local files through the image field. For input constraints, see the appendix "Reference Image Input Constraints".
size
No
string
Generated size, in the format ${width}x${height}. Supports 7 options: 2048x2048 (1:1), 2304x1728 (4:3), 1728x2304 (3:4), 2560x1440 (16:9), 1440x2560 (9:16), 2496x1664 (3:2), 1664x2496 (2:3). If auto is passed or not passed, the model adaptively determines the output size.

3. Request Example

Pass image URLs (application/json)
# Image editing
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hidream-image/images/edits' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"model": "hidream-image-o1-1.5-edit",
"prompt": "Change the outfit to a red dress",
"images": ["https://example.com/reference.png"],
"size": "2048x2048"
}'
Upload local images (multipart/form-data)
# Image editing
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hidream-image/images/edits' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-F 'model=hidream-image-o1-1.5-edit' \\
-F 'prompt=Change the outfit to a red dress' \\
-F 'image=@reference.png' \\
-F 'size=2048x2048'

4. Output Parameters

Parameter Name
Type
Description
created
integer
Unix timestamp (in seconds).
data
array
Array of generated image content returned.
data[n].item_index
integer
Index of the image in this request, starting from 0.
data[n].url
string
The generated image URL is temporary and valid for 12 hours. Download and save it promptly.
request_id
string
Unique request ID for troubleshooting.
tokenhub_usage
object
Usage consumption.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.

5. Response Example

{
"created": 1793780017,
"data": [
{
"item_index": 0,
"url": "https://xxx.png"
}
],
"request_id": "fcbdfc09-21c5-4e15-bb88-de8be73bc927",
"tokenhub_usage": {
"total_tokens": 65000
}
}
The returned url is a temporary address valid for 12 hours. Because the address requires authentication, accessing it directly through a browser address bar may be denied. We recommend downloading it in one of the following ways:
curl -o generated_image.png 'https://xxx.png'
Or use an HTTP client in your code to download and save it to local storage.

6. Error Codes

HTTP Status Code
Description
Recommended Solution
400
The request format is incorrect.
Check the request body field types/values (such as the number and format of images, the size value, and the model name).
401
Authentication failed.
Check whether the API_KEY is valid and whether the Authorization uses the Bearer format.
429
The number of concurrent requests exceeds the limit.
The concurrency limit is reached. Retry with backoff and control the call concurrency.

Appendix

Supported Size List

The size values of both models are the same, with the format "width x height". Both models output native 2K resolution, so no upscaling is required:
Aspect Ratio
size Value
Applicable Scenario Reference
1:1
2048x2048
Product main images, avatars, and social media square images
4:3
2304x1728
Horizontal images and PPT illustrations
3:4
1728x2304
Vertical posters and vertical social media images
16:9
2560x1440
Horizontal banners, video covers, and storyboards
9:16
1440x2560
Mobile wallpapers, splash screens, and short video covers
3:2
2496x1664
Horizontal photography images and brand materials
2:3
1664x2496
Vertical posters and book covers
Adaptive
auto (or not passed)
Determined adaptively by the model

Reference Image Input Constraints

Only HiDream-O1-Image-Edit-1.5 supports reference image input:
Constraint Item
Requirement
Quantity
1 to 6 images
Supported formats
png / jpeg / jpg / bmp / tiff / webp / gif
Size per image
≤ 20MB
Total pixels
Greater than 16384 (128×128) and less than 16777216 (4096×4096)
Aspect ratio
Greater than 0.25 and less than 4
We recommend using a direct CDN link without authentication. If the domain is on a private network/requires authentication, contact TokenHub to add it to the allowlist.

FAQs

1. How to Choose Between the Two Models?

hidream-image-o1-1.5 is suitable for text-to-image scenarios where no reference image is required and images are generated from scratch. hidream-image-o1-1.5-edit is suitable for editing existing images, where a reference image is required and the editing intent is described in text (such as outfit changes, background replacement, style transfer, or in-image text rewriting), or where multiple reference images are used to maintain consistency of characters or product appearances. The two models can be used together: first generate a draft with the text-to-image model, and then refine it with the editing model.

2. How to Pass the size Parameter?

Select from the 7 options in the appendix "Supported Size List" based on your target aspect ratio. For example, pass 1728x2304 for a vertical poster. If you are unsure about the aspect ratio, pass auto or omit the parameter, and the model will determine it adaptively.

3. What Is the Purpose of Passing Multiple Reference Images During Editing?

When a single reference image is provided, the model edits the image according to the instructions and preserves the original composition and subject as much as possible. When multiple reference images are provided, the model extracts the appearance of a person, product, or IP from the images and maintains the same subject in a new scene or pose. We recommend clearly specifying the purpose of each image in the prompt, for example, "Use the person from the first image and dress them in the clothes from the second image."

4. How to Handle Long Request Latency?

HiDream image generation uses a synchronous API. A single request typically takes 30 to 120 seconds, so set the client timeout to no less than 300 seconds. If timeouts persist, contact technical support and provide the request_id.

5. Do Generated Image Links Expire?

They will expire. The generated results of both models are returned through data[n].url as temporary signed URLs valid for 12 hours. Download and save the results promptly after generation, and do not rely on them for long-term use.




ヘルプとサポート

この記事はお役に立ちましたか?

フィードバック