tencent cloud

LLM Service TokenHub

DokumentasiLLM Service TokenHubAPI Integration GuideImage Generation ModelsSeedream Image Generation API Guide

Seedream Image Generation API Guide

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-10 22:08:17
Diterjemahkan oleh 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) and Seedream-Image-v5.0-lite (seedream-image-v5.0-lite) through TokenHub. These models support text-to-image and reference-to-image generation, allowing you to generate images by combining reference images with text prompts or by using text alone for text-to-image generation.

Prerequisites

You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
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

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. Value: seedream-image-v5.0-pro, seedream-image-v5.0-lite
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]
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, supporting URL or Base64 encoding.
Image URL: Ensure that the image URL is accessible.
Base64 encoding: Use the following format: data:image/<image_format>;base64,<Base64_encoded_string>. Note that <image_format> must be lowercase, for example, data:image/png;base64,<base64_image>.
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
size
No
string
Image size.
seedream-image-v5.0-pro (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 (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 generates content faster but with slightly lower quality than standard mode. seedream-image-v5.0-lite does 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
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 24 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_at
string
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
BadRequest
bad request
Invalid request
FieldLacking
field is missing or empty
Missing required field
FieldUnwanted
unwanted field
Unwanted field was passed.
FieldInvalid
invalid field
Input parameter failed validation.
FieldItemCountOutOfRange
field item count out of range
The number of field items exceeds the limit (for example, the number of images exceeds the limit).
PageSizeOutOfRange
page size out of range
Image size/parameter exceeds the limit
ImageFormatInvalid
invalid image format
Image format does not meet the requirements.
ImageSizeInvalid
image size invalid
Image size is too large or too small.
ImageDownloadFailure
image download failure
Failed to download the image from the URL. Check the link.
TaskPromptPolicyViolation
prompt policy violation
Prompt triggers security review and risk control.
CreationPolicyViolation
creation policy violation
Generated content triggers risk control.
AuditSubmitIllegal
submit is illegal
Input failed security review.
CreditInsufficient
insufficient credits
Insufficient credits
ModelUnavailable
model unavailable
Model unavailable
Unauthorized
unauthorized
Unauthenticated (check Authorization)
Forbidden
forbidden
Request has no permission.
TaskNotFound
task not found
task_id not found.
QuotaExceeded
quota exceeded
Exceeding the concurrency limit
TooManyRequests
too many requests
Requests are too frequent.
InternalServiceFailure
internal service failure
Internal server error

General Constraints on Image Assets

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 (Base64 strings 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 number of pixels must not exceed 36 million, the aspect ratio must be less than 1:16 or greater than 16:1, each image must not exceed 30 MB, and the POST body must not exceed 20 MB.

FAQs

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

The same API supports both modes: passing image enables reference-to-image (using the subjects in the image as references), while omitting images enables text-to-image (generated solely from the prompt). seedream-image-v5.0-pro supports both modes.

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.

Topik sebelumnya: Vidu Image Generation API GuideTopik selanjutnya: Video Generation Model Invocation Overview

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation