tencent cloud

LLM Service TokenHub

Seedream Image Generation API Guide

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-10-20 15:22:07
AI翻訳

Overview

Seedream is a series of image generation models launched by Volcano Engine. This document describes how to call the Seedream image generation models Seedream-Image-v5.0-pro (seedream-image-v5.0-pro), Seedream-Image-v5.0-lite (seedream-image-v5.0-lite), and Seedream-Image-v5.0-flash (seedream-image-v5.0-flash) through TokenHub. These models support text-to-image and reference-to-image generation, allowing you to generate images by combining a reference image with text prompts, or by text alone.

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, YOUR_API_KEY must be replaced 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
Prompt Limit
Resolution
Seedream-Image-v5.0-pro
seedream-image-v5.0-pro
Reference-based image generation/text-to-image generation
600 characters
1K / 1.5K / 2K
Seedream-Image-v5.0-lite
seedream-image-v5.0-lite
Reference-based image generation/text-to-image generation
600 characters
2K / 3K / 4K
Seedream-Image-v5.0-flash
seedream-image-v5.0-flash
Reference-based image generation/text-to-image generation
600 characters
1K / 1.5K / 2K

Image Generation

1. API Description

The Seedream image generation (reference-to-image) API supports reference-to-image, text-to-image, and image editing: it generates images using a reference image + text prompts, or performs text-to-image generation when no image is provided.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation

2. Input Parameters

Parameter Name
Required
Type
Description
model
Yes
string
Model ID. Valid values: seedream-image-v5.0-pro, seedream-image-v5.0-lite, seedream-image-v5.0-flash
prompt
Yes
string
Text prompt, with a maximum length of 600 characters. If images is not passed, image-to-text generation is performed based on this text.
Prompt length recommendation: Chinese prompts should not exceed 300 characters, and English prompts should not exceed 600 words. Excessive length can scatter information, causing the model to overlook details and focus only on key points, resulting in missing elements in the generated image.
images
No
array[string]
Images: seedream-image-v5.0-pro and seedream-image-v5.0-flash support up to 10 images, seedream-image-v5.0-lite supports up to 14 images, and URL and Base64 formats are supported.
Image format: jpeg/png/webp/bmp/tiff/gif/heic/heif. Aspect ratio (width/height) range: [1/16, 16]. Width and height (px): > 14. Size: <= 30 MB. Total pixels: [196, 6000×6000 (36 million)] (a limit on the product of the width and height of a single image, rather than separate limits on the width or height).
layer_decomposition
No
boolean
Layer decomposition switch, controlling whether to enable the layer decomposition feature.
Layer decomposition automatically breaks down the subject, background, text, and other content of a single image into one base image and up to 16 independently editable layers. Each layer is a PNG image with an alpha channel.
Supported models:
seedream-image-v5.0-pro
seedream-image-v5.0-flash
size
No
string
Image size.
seedream-image-v5.0-pro, seedream-image-v5.0-flash (image generation scenario)
The following two methods are supported and cannot be mixed:
Method 1 (Recommended): Specify a resolution tier and describe the image aspect ratio, shape, or purpose in natural language in the prompt. The model then determines the size of the generated image.
Default value: 2K
Valid values: 1K, 1.5K, 2K
Method 2: Specify the width and height in pixels (width x height).
Total pixel value range: [1280x720 (921600), 2048x2048x1.1025 (4624220)]
Aspect ratio value range: [1/16, 16]

seedream-image-v5.0-pro, seedream-image-v5.0-flash (layer decomposition scenario)
Only setting by specifying a resolution tier is supported. The resolution rules for the output image are as follows:
Base image: The resolution of the output base image is consistent with the resolution specified by size. The aspect ratio of the output base image is consistent with that of the original image to be split.
Layers: The resolution of each output layer is close to the resolution specified by size. The aspect ratio of each output layer is consistent with that of the layer in the original image.
Default and optional values of size:
Default value: auto
Valid values: 1K, 1.5K, 2K, auto (output based on the size and aspect ratio of the input image)

seedream-image-v5.0-lite
The following two methods are supported and cannot be mixed:
Method 1: Specify a resolution and describe the image aspect ratio, shape, or purpose in natural language in the prompt. The model then determines the size of the generated image.
Valid values: 2K, 3K, 4K
Method 2: Specify the width and height of the generated image in pixels.
Default value: 2048x2048
Total pixel value range: [2560x1440 (3686400), 4096x4096 (16777216)]
Aspect ratio value range: [1/16, 16]
optimize_prompt_options
No
object
Prompt optimization configuration.
optimize_prompt_options.mode
No
string
Optimization mode.
standard: Standard mode. It generates higher-quality content but takes longer.
fast: Fast mode. It takes less time to generate content, with slightly lower quality than standard mode. seedream-image-v5.0-lite and seedream-image-v5.0-flash do not currently support this mode.
output_format
No
string
Image format.
Specifies the file format of the generated image. Optional values:
png
jpeg
background
No
string
Image alpha channel.
Controls whether to generate an image with an alpha channel. Optional values:
transparent: Transparent background mode. It outputs images with a transparent background.
opaque: Opaque background mode. It generates regular solid background images.
Supported models:
seedream-image-v5.0-pro
seedream-image-v5.0-flash
response_format
No
string
Response format.
Specifies the return format of the generated image. The following two return methods are supported:
url: Returns the image download link. The link is valid for 12 hours after the image is generated. Download the image promptly.
b64_json: Returns the image data as a JSON string encoded in Base64.
sequential_image_generation
No
string
Group image mode.
Controls whether to disable the group image feature (group image: a set of content-related images generated based on your input).
auto: Automatic mode. The model determines whether to return a group of images and the number of images in the group based on the user-provided prompt.
disabled: Disables the group image feature. The model generates only one image.
Supported models:
seedream-image-v5.0-lite
sequential_image_generation_options
No
object
Group image configuration.
Configuration of the group image feature. Takes effect only when sequential_image_generation is set to auto.
Supported models:
seedream-image-v5.0-lite
sequential_image_generation_options.max_images
No
integer
Maximum number of generated images.
Specifies the maximum number of images that can be generated in this request. Value range: [1, 15].
tools
No
object
Tool configuration.
Supported models:
seedream-image-v5.0-lite
tools.type
No
string
Tool type. Specifies the type of tool to use.
web_search: Web search feature.
watermark
No
boolean
Watermark switch.
Whether to add a watermark to the generated image.
false: No watermark is added.
true: Adds a watermark labeled "AI-generated" to the bottom-right corner of the image.

3. Sample Request

Reference-to-image
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"model": "seedream-image-v5.0-pro",
"images": ["https://example.com/reference.jpg"],
"prompt": "a cat sitting on a windowsill at sunset",
"size": "2048x2048"
}'
Text-to-image (without images)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"model": "seedream-image-v5.0-pro",
"prompt": "a cat sitting on a windowsill at sunset",
"size": "2048x2048"
}'

4. Output Parameters

Field
Type
Description
created
integer
Task creation time.
data
object
Returned image content.
data[].output_format
string
Output format.
data[].size
string
Image size.
data[].url
string
Image URL.
data[].b64_json
string
Image Base64 data.
request_id
string
Unique request identifier used for troubleshooting.
model
string
Image generation model used.
tokenhub_usage
object
Usage consumption.
tokenhub_usage.total_tokens
integer
Number of tokens consumed by this task, used for billing/reconciliation.

5. Sample Response

{
"created": 1787309367,
"data": [
{
"output_format": "jpeg",
"size": "2048x2048",
"url": "https://xxxxxxx.jpg"
}
],
"model": "doubao-seedream-5-0-pro-260628",
"tokenhub_usage": {
"total_tokens": 60000
},
"request_id": "f781d9dc-9792-43d8-82f3-90de51a1ff44"
}

Appendix

Unified Error Codes

Error Code
Error Message
Description
InvalidParameter
One or more parameters specified in the request are not valid.
The request contains one or more invalid parameters. Check the parameter names, types, value ranges, and dependencies between parameters against the API documentation, and try again.
MissingParameter
The request failed because it is missing %s parameter.
The request is missing the required parameter %s. Add the missing parameter and try again.
InvalidAction
The requested action is not valid for the current resource state.
The current state of the target resource does not allow this operation. Migrate the resource to a state that allows this operation (for example, end the ongoing turn or resume the paused resource), and then retry.
InvalidPayload
Request payload is invalid.
The request payload does not conform to the API contract. This may be caused by JSON parsing failures, invalid event list structures, or invalid event parameters. Check the request payload against the API documentation.
EmptyEvents
Request must include at least one event.
The events array in the POST events request payload is empty. This code is used to distinguish it from InvalidPayload: InvalidPayload indicates that the batch structure is invalid, while EmptyEvents specifically indicates that the structure is valid but the length is 0.
RuntimeRejected
Runtime rejected the request.
Synchronous materialization during the POST create phase is rejected by the runtime. Fatal errors during Tool Service startup are also classified under this code. The message content may differ when public override is used at create time. Check whether the agent snapshot is compatible with the runtime configuration.
MissingSessionModel
Request provider mode requires agent.model.name.
In request provider mode, the managed-agent snapshot for POST create does not contain a valid agent.model.name. Add the model information in the agent definition.
MissingSessionId
session_id is required.
The POST create request payload is missing session_id, or the field is an empty string. Retry with a non-empty session_id.
ManagedAgentsRequired
Managed agents integration is required for request provider mode.
POST create uses request provider mode, but the server does not have the managed-agents loader configured. Complete the managed agents integration on the server before calling the API.
ManagedAgentsRejected
Managed agent definition was rejected.
The managed-agents business layer rejects the request during the POST create phase. Common causes: the target session does not exist, the session has been deleted, or the tenant does not match the session owner.
ManagedAgentsInvalidAgent
Managed agent definition is invalid.
During the POST create phase, the agent payload cannot be translated into a valid AgentSpec. Common causes: agent.name is empty, the permission policy or tool name is not recognized, or skill_id is missing.
InvalidSession.NotFound
The session %s does not exist or you do not have access to it.
The specified session_id does not exist, or the caller does not have access to the session.
InvalidAgent.NotFound
The agent %s does not exist or you do not have access to it.
The specified agent_id does not exist, or the caller does not have access to the agent.
InvalidEnvironment.NotFound
The environment %s does not exist or you do not have access to it.
The specified environment_id does not exist, or the caller does not have access to the environment.
InvalidVault.NotFound
The vault %s does not exist or you do not have access to it.
The specified vault_id does not exist, or the caller does not have access to the vault.
InvalidCredential.NotFound
The credential %s does not exist or you do not have access to it.
The specified credential_id does not exist, or the caller does not have access to the credential.
InvalidMemoryStore.NotFound
The memory_store %s does not exist or you do not have access to it.
The specified memory_store_id does not exist, or the caller does not have access to the memory store.
InvalidFile.NotFound
The file %s does not exist or you do not have access to it.
The specified file_id does not exist, or the caller does not have access to the file.
ResourceNotFound
The requested resource does not exist or you do not have access to it.
The requested resource does not exist or the caller does not have access to it. Use this general code when the resource type does not fall into the specific .NotFound branches above.
RequestTooLarge
The request entity is larger than the limit allowed.
A single content / payload at the business layer exceeds the limit, including business granularities such as a single file, zip package, or single message. Split or compress it and try again.
RequestBodyTooLarge
The request body is larger than the limit allowed.
The byte size of the HTTP request body exceeds the transport layer limit. Compress the request body or transfer it in batches. The difference between this code and RequestTooLarge is that the former indicates a business granularity limit, while this code indicates a transport granularity limit.
UpstreamUnavailable
An upstream dependency is temporarily unavailable. Please retry later or check that the upstream is healthy.
A client-side upstream dependency, such as an MCP server or IdP, is temporarily unreachable, which may manifest as timeouts, jitter, or 5xx responses. Retry later and check the health of the upstream service.
InternalServiceError
The service encountered an unexpected internal error. Please retry later.
The service encountered an unexpected internal error. Retry the request. If the issue persists, submit a ticket with the Request ID for troubleshooting.
SideEffectFailed
Request side effect failed.
The server failed to perform the associated operation before dispatching the event to the runtime. Retry the request. If the failure persists, submit a ticket with the Request ID.
ManagedAgentsUnavailable
Managed agent definition is temporarily unavailable.
During the POST create phase, the InnerGetSession call to managed-agents encountered a network error, a non-2xx response, or a response decoding failure, indicating that the upstream managed-agents service is temporarily unavailable. Retry later.

General Constraints on Image Assets

Up to 10 reference images are supported for seedream-image-v5.0-pro and seedream-image-v5.0-flash, and up to 14 for seedream-image-v5.0-lite. Image URLs or Base64 are supported. Supported formats include jpeg/png/webp/bmp/tiff/gif/heic/heif, with a minimum resolution of 14 x 14 pixels, a total number of pixels not exceeding 36 million, an aspect ratio less than 1:16 or greater than 16:1, a single image size of 30 MB or less, and a POST body size of 20 MB or less.

FAQs

1. How to Distinguish Text-to-Image from Image-to-Image?

The same API is used: passing images enables reference-to-image generation (using the subject in the image as a reference), while omitting images enables text-to-image generation (generated solely from the prompt). Both modes are supported by seedream-image-v5.0-pro.

2. Do Generated Image Links Expire?

The generated result is a temporary address that expires in 12 hours. Download it promptly after the task succeeds.


ヘルプとサポート

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

フィードバック