Seedream โ
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generationAuthentication: Tokenhub API Key / Bearer
Seedream is an image generation model that supports text-to-image and reference-image editing. 5.0 Pro supports layer decomposition, and 5.0 Lite supports image-set generation.
Basic Information โ
| Item | Value |
|---|---|
| Call path | Tokenhub API |
| Guardrail bypass support | Not supported |
Supported Specifications by Version โ
| Version | Resolution | Ratio | Reference image |
|---|---|---|---|
seedream-image-v5.0-pro | 1K / 1.5K / 2K | Prompt / specified size | Up to 10 images |
seedream-image-v5.0-lite | 2K / 3K / 4K | Prompt / specified size | Up to 14 images |
Image Generation โ
API Description โ
Seedream image generation (reference-image based image generation) API supports reference-image based image generation, text-to-image generation, and image editing. It generates images using a reference image and a text prompt; if no image is provided, text-to-image generation is performed.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
| model | Required | string | Model ID. Value: seedream-image-v5.0-pro, seedream-image-v5.0-lite |
| prompt | Required | string | A text prompt with a maximum length of 600 characters. If images is not passed, text-to-image generation is performed based on this text. Recommended prompt length: no more than 300 characters for Chinese prompts, and no more than 600 words for English prompts. Excessive length disperses the information, so the model may miss details and focus only on the core content, and some elements may be missing from the generated image. |
| images | Optional | array[string] | Reference images: seedream-image-v5.0-pro supports up to 10 images, and seedream-image-v5.0-lite supports up to 14 images.Input image information supports URLs or Base64 encoding. Image URL: the image URL must be accessible. Base64 encoding: use the data:image/<image_format>;base64,<Base64_encoded_string> format. <image_format> must be lowercase. For example: data:image/png;base64,<base64_image>. |
| layer_decomposition | Optional | boolean | A switch that controls whether to enable the layer decomposition feature. Layer decomposition automatically decomposes the reference target, background, text, and other content in a single image into up to 16 layers that are independent of the base image 1 and can be edited separately. Each layer is a PNG image with an alpha channel. Supported models: seedream-image-v5.0-pro |
| size | Optional | string | Image size.seedream-image-v5.0-pro (image generation scenario) supports the following two approaches, which cannot be used together. Approach 1 (recommended): specify a resolution tier and describe the image's aspect ratio, form, or intended use in natural language in the prompt.The model then determines the size of the generated image. Default: 2K Valid values: 1K, 1.5K, 2K Approach 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 (layer decomposition scenario) only supports specifying a resolution tier.The resolution rules for output images are as follows. Base image: the resolution of the output base image matches the resolution specified by size. The aspect ratio of the output base image matches 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 matches that layer's aspect ratio in the original image. Default and selectable values for size: Default: 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 supports the following two approaches, which cannot be used together.Approach 1: specify a resolution and describe the image's aspect ratio, form, or intended use in natural language in the prompt.The model then determines the size of the generated image. Valid values: 2K, 3K, 4K Approach 2: specify the width and height of the generated image in pixels.Default: 2048x2048 Total pixel value range: [2560x1440 (3686400), 4096x4096 (16777216)] Aspect ratio value range: [1/16, 16] |
| optimize_prompt_options | Optional | object | Prompt optimization configuration. |
| optimize_prompt_options.mode | Optional | string | Optimization mode. standard: standard mode. Generates higher-quality content but takes longer. fast: high-speed mode. Generates content faster, but the quality is slightly lower than in standard mode. seedream-image-v5.0-lite does not currently support this mode. |
| output_format | Optional | string | Image format. Specifies the file format of the generated image. Selectable values: png jpeg |
| background | Optional | string | Image alpha channel. Controls whether to generate an image with an alpha channel. Selectable values: transparent: transparent background mode. Outputs an image with a transparent background. opaque: opaque background mode. Generates a regular solid-color background image. Supported models: seedream-image-v5.0-pro |
| response_format | Optional | string | Response format. Specifies the return form of the generated image. The following two return approaches are supported. url: returns an image download link. The link is valid for 24 hours after the image is generated. Download the image immediately. b64_json: returns the Base64-encoded image data as a JSON string. |
| sequential_image_generation | Optional | string | Group image mode. Controls whether to disable the group image feature (a set of mutually related images generated from the input). auto: automatic mode. The model decides whether to return an image group, and how many images it contains, based on the prompt provided by the user. disabled: disables the group image feature. The model generates only 1 image.Supported models: seedream-image-v5.0-lite |
| sequential_image_generation_options | Optional | object | Group image configuration. Configuration for the group image feature, which takes effect only when sequential_image_generation is set to auto. Supported models: seedream-image-v5.0-lite |
| sequential_image_generation_options.max_images | Optional | integer | Maximum number of generated images. Specifies the maximum number of images that can be generated in this request. Value range: [1, 15]. |
| tools | Optional | object | Tool configuration. Supported models: seedream-image-v5.0-lite |
| tools.type | Optional | string | Tool type. Specifies the type of tool to use. web_search: the web search feature. |
| watermark | Optional | boolean | Watermark switch. Specifies whether to add a watermark to the generated image. false: do not add a watermark. true: add an "AI-generated" watermark to the bottom-right corner of the image. |
Request Examples โ
Reference-image based image generation
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://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
],
"prompt": "a cat sitting on a windowsill at sunset",
"size": "2048x2048"
}'Text-to-image generation (images not used)
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"
}'Response Parameters โ
| Field | Type | Description |
|---|---|---|
| created_at | string | Task creation time. |
| data | object | The 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 | A unique request identifier used for troubleshooting. |
| model | string | The image generation model used. |
| tokenhub_usage | object | Usage. |
| tokenhub_usage.total_tokens | integer | The number of tokens consumed by this task, used for billing/settlement. |
Response Example โ
{
"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 |
|---|---|---|
| BadRequest | Bad request | Invalid request. |
| FieldLacking | Field missing or empty | A required field is missing. |
| FieldUnwanted | Unwanted field | An unnecessary field was passed. |
| FieldInvalid | Invalid field | An input parameter failed validation. |
| FieldItemCountOutOfRange | Field item count out of range | The number of field items exceeded the limit (for example, the number of images exceeded the limit). |
| PageSizeOutOfRange | Page size out of range | The image size/parameter exceeded the limit. |
| ImageFormatInvalid | Invalid image format | The image format does not meet the requirements. |
| ImageSizeInvalid | Invalid image size | The image size is too large or too small. |
| ImageDownloadFailure | Image download failed | The image could not be downloaded from the URL. Check the link. |
| TaskPromptPolicyViolation | Prompt policy violation | The prompt triggered security review and risk control. |
| CreationPolicyViolation | Creation policy violation | The generated content triggered risk control. |
| AuditSubmitIllegal | Submission is invalid | The input did not pass security review. |
| CreditInsufficient | Insufficient credit | Credit is insufficient. |
| ModelUnavailable | Model unavailable | The model is unavailable. |
| Unauthorized | Unauthorized | Not authenticated (check Authorization). |
| Forbidden | Forbidden | The request lacks permission. |
| TaskNotFound | Task not found | The task_id could not be found. |
| QuotaExceeded | Quota exceeded | The concurrency limit was exceeded. |
| TooManyRequests | Too many requests | The request frequency is too high. |
| InternalServiceFailure | Internal service failure | Internal server error. |
General Limits for Image Resources โ
Reference images: seedream-image-v5.0-pro supports up to 10 images, and seedream-image-v5.0-lite supports up to 14 images. Image URLs or Base64 strings are supported (a Base64 string must include the data:image/png;base64, prefix). Supported formats include jpeg/png/webp/bmp/tiff/gif/heic/heif. The minimum pixel dimension is 14 x 14, the total pixel count cannot exceed 36 million, and the aspect ratio must be less than 1:16 or greater than 16:1. Each image cannot exceed 30 MB, and the POST body cannot exceed 20 MB.
FAQ โ
1. How do I distinguish text-to-image from image-to-image? โ
The same API supports both modes. Passing image enables reference-image based image generation driven by the reference target in the image, while omitting images performs text-to-image generation from the prompt alone. seedream-image-v5.0-pro supports both modes.
2. Do generated image links have an expiration time? โ
Generation results are temporary addresses that expire after 12 hours. Download them immediately after the task succeeds.