Skip to content

Seedream โ€‹

Updated

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

ItemValue
Call pathTokenhub API
Guardrail bypass supportNot supported

Supported Specifications by Version โ€‹

VersionResolutionRatioReference image
seedream-image-v5.0-pro1K / 1.5K / 2KPrompt / specified sizeUp to 10 images
seedream-image-v5.0-lite2K / 3K / 4KPrompt / specified sizeUp 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 โ€‹

ParameterRequiredTypeDescription
modelRequiredstringModel ID. Value: seedream-image-v5.0-pro, seedream-image-v5.0-lite
promptRequiredstringA 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.
imagesOptionalarray[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_decompositionOptionalbooleanA 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
sizeOptionalstringImage 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_optionsOptionalobjectPrompt optimization configuration.
optimize_prompt_options.modeOptionalstringOptimization 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_formatOptionalstringImage format. Specifies the file format of the generated image. Selectable values: png jpeg
backgroundOptionalstringImage 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_formatOptionalstringResponse 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_generationOptionalstringGroup 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_optionsOptionalobjectGroup 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_imagesOptionalintegerMaximum number of generated images. Specifies the maximum number of images that can be generated in this request. Value range: [1, 15].
toolsOptionalobjectTool configuration. Supported models: seedream-image-v5.0-lite
tools.typeOptionalstringTool type. Specifies the type of tool to use. web_search: the web search feature.
watermarkOptionalbooleanWatermark 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

bash
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)

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

FieldTypeDescription
created_atstringTask creation time.
dataobjectThe returned image content.
data[].output_formatstringOutput format.
data[].sizestringImage size.
data[].urlstringImage URL.
data[].b64_jsonstringImage Base64 data.
request_idstringA unique request identifier used for troubleshooting.
modelstringThe image generation model used.
tokenhub_usageobjectUsage.
tokenhub_usage.total_tokensintegerThe number of tokens consumed by this task, used for billing/settlement.

Response Example โ€‹

json
{
  "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 codeError messageDescription
BadRequestBad requestInvalid request.
FieldLackingField missing or emptyA required field is missing.
FieldUnwantedUnwanted fieldAn unnecessary field was passed.
FieldInvalidInvalid fieldAn input parameter failed validation.
FieldItemCountOutOfRangeField item count out of rangeThe number of field items exceeded the limit (for example, the number of images exceeded the limit).
PageSizeOutOfRangePage size out of rangeThe image size/parameter exceeded the limit.
ImageFormatInvalidInvalid image formatThe image format does not meet the requirements.
ImageSizeInvalidInvalid image sizeThe image size is too large or too small.
ImageDownloadFailureImage download failedThe image could not be downloaded from the URL. Check the link.
TaskPromptPolicyViolationPrompt policy violationThe prompt triggered security review and risk control.
CreationPolicyViolationCreation policy violationThe generated content triggered risk control.
AuditSubmitIllegalSubmission is invalidThe input did not pass security review.
CreditInsufficientInsufficient creditCredit is insufficient.
ModelUnavailableModel unavailableThe model is unavailable.
UnauthorizedUnauthorizedNot authenticated (check Authorization).
ForbiddenForbiddenThe request lacks permission.
TaskNotFoundTask not foundThe task_id could not be found.
QuotaExceededQuota exceededThe concurrency limit was exceeded.
TooManyRequestsToo many requestsThe request frequency is too high.
InternalServiceFailureInternal service failureInternal 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.

Generation results are temporary addresses that expire after 12 hours. Download them immediately after the task succeeds.

Built with VitePress ยท Deployed on Tencent EdgeOne Pages