logoUnode Docs
User GuideAPI ReferenceHelp & SupportBusiness Cooperation

Seedream Image Format (Image)

Seedream Image Format (Image)

Official Documentation

VolcEngine Seedream Image Generation API

📝 Introduction

Given a text prompt and/or reference image(s), Seedream models will generate new images. Seedream is Bytedance's high-quality image generation model family, supporting text-to-image, image-to-image, and sequential (multi-image set) generation via the VolcEngine channel.

🤖 Supported Models

Currently supported models include:

ModelDescription
doubao-seedream-4-5-251128Seedream 4.5 image generation model supporting text-to-image and image-to-image generation
doubao-seedream-5-0-260128Seedream 5.0 image generation model with enhanced quality, web search tool support, and PNG output

💡 Request Examples

Text-to-Image ✅

curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "A cute little sea otter",
    "size": "2048x2048",
    "response_format": "url"
  }'

Response Example:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1780599167,
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}

Image-to-Image (Reference Image) ✅

curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "A cute little sea otter wearing a beret",
    "image": "data:image/png;base64,<BASE64_DATA>",
    "size": "2048x2048"
  }'

Generate Image Set (Sequential Generation) ✅

curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "A series of illustrations showing a fox exploring different seasons",
    "extra_fields": {
      "sequential_image_generation": "auto",
      "sequential_image_generation_options": {
        "max_images": 4
      }
    }
  }'

Response Example:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1780599167,
  "data": [
    { "url": "https://example.com/image1.jpeg", "size": "2048x2048" },
    { "url": "https://example.com/image2.jpeg", "size": "2048x2048" },
    { "url": "https://example.com/image3.jpeg", "size": "2048x2048" },
    { "url": "https://example.com/image4.jpeg", "size": "2048x2048" }
  ],
  "usage": {
    "generated_images": 4,
    "output_tokens": 65536,
    "total_tokens": 65536
  }
}

Multi-Image Composition ✅

curl https://www.unodetech.xyz/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Create an elegant gift set containing these items",
    "image": [
      "data:image/png;base64,<BASE64_IMAGE_1>",
      "data:image/png;base64,<BASE64_IMAGE_2>",
      "data:image/png;base64,<BASE64_IMAGE_3>"
    ]
  }'

📮 Request

Endpoint

Create Image

POST /v1/images/generations

Create images based on text prompts and/or reference images.

Authentication Method

Include the following in the request header for API key authentication:

Authorization: Bearer $API_KEY

Where $API_KEY is your API key.

Request Body Parameters

ParameterTypeRequiredDescription
modelstringYesModel ID, e.g. doubao-seedream-5-0-260128
promptstringYesText prompt for image generation. Supports Chinese and English.
imagestring | string[]NoReference image(s) as data URLs (data:image/<format>;base64,...). Single image = string, multiple = array. Maximum 14 images.
sizestringNoOutput resolution. Options: 2K, 3K, 4K, or explicit <width>x<height> (e.g. 2048x2048). See size values for details. Default determined by model.
response_formatstringNo"url" (default) or "b64_json".
watermarkbooleanNoWhether to add an "AI Generated" watermark. Default: true.
extra_fieldsobjectNoSeedream-specific extended parameters. See Seedream extra_fields Reference below.

Size Values

ValueDescriptionModels
2K~2048px (model chooses exact dimensions based on prompt)5.0, 4.5
3K~3072px5.0, 4.5
4K~4096px5.0, 4.5
<width>x<height>Explicit pixel dimensions, e.g. 2048x2048. Must satisfy both minimum total pixels and aspect ratio constraints (see API docs for per-model limits).All

Seedream extra_fields Reference

The following parameters are supported in the extra_fields object for Seedream image generation models via the VolcEngine channel.

extra_fields Parameters

FieldTypeDefaultDescriptionModels
sequential_image_generationstring"disabled""auto": model decides how many images to return as a set. "disabled": single image only.5.0, 4.5, 4.0
sequential_image_generation_optionsobject—Configuration for image set generation. Only effective when sequential_image_generation is "auto".5.0, 4.5, 4.0
sequential_image_generation_options.max_imagesinteger15Maximum number of images to generate in the set. Range: 1–15. Note: input reference images + generated images ≤ 15.5.0, 4.5, 4.0
toolsarray—Enable optional tools. Pass [{ "type": "web_search" }] to let the model search the web for timely content (e.g. current events, products). Increases latency. Actual search count returned in usage.tool_usage.web_search.5.0 only
streambooleanfalseEnable streaming output. Each image is returned as soon as it is ready rather than waiting for the full set. Note: response-side streaming is not currently handled by this router; the upstream will stream but the router responds non-streamingly.5.0, 4.5, 4.0
output_formatstring"jpeg"Output file format: "jpeg" or "png".5.0 only
optimize_prompt_optionsobject—Prompt optimization configuration.5.0, 4.5, 4.0
optimize_prompt_options.modestring"standard""standard": higher quality, slower. "fast": lower quality, faster. Note: "fast" is not supported on 5.0 or 4.5.5.0, 4.5, 4.0

📥 Response

Successful Response

The endpoint returns a response with the following top-level fields:

FieldTypeDescription
modelstringThe model ID used for generation
createdintegerUnix timestamp (in seconds) of when the image was created
dataarrayList of generated image objects
usageobjectToken usage for the API call

usage Fields

FieldTypeDescription
generated_imagesintegerNumber of images generated
output_tokensintegerTokens used for output
total_tokensintegerTotal tokens used

Image Object

Each object in the data array contains:

FieldTypeDescription
urlstringURL of the generated image. Returned when response_format is "url" (default).
b64_jsonstringBase64-encoded image data. Returned when response_format is "b64_json".
sizestringActual dimensions of the generated image (e.g. "2048x2048").

Example image object:

{
  "model": "doubao-seedream-5-0-260128",
  "created": 1780599167,
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}

🌟 Best Practices

Prompt Writing Tips

  1. Use clear and specific descriptions
  2. Specify important visual details
  3. Describe the expected artistic style and atmosphere
  4. Pay attention to composition and perspective instructions
  5. Seedream supports both Chinese and English prompts

Parameter Selection Tips

  1. Size Selection

    • 2K / 3K / 4K: Preset tiers where the model selects exact dimensions based on the prompt
    • <width>x<height>: Use explicit dimensions when you need a specific aspect ratio or resolution

  2. Image Set Generation

    • Set extra_fields.sequential_image_generation to "auto" to generate a coherent set of related images from a single prompt
    • Control the set size with extra_fields.sequential_image_generation_options.max_images (up to 15)
    • When using reference images, the total of input images + generated images must not exceed 15

  3. Reference Images

    • Pass reference images as base64 data URLs (data:image/png;base64,...) in the image field
    • Use up to 14 reference images for multi-image composition

Common Questions

  1. Image generation failed

    • Check if the prompt complies with content policies
    • Verify API key permissions
    • Confirm reference image format (must be base64 data URL, not file upload)

  2. Results do not match expectations

    • Optimize prompt descriptions with more specific visual detail
    • Adjust the size parameter
    • Try enabling prompt optimization via extra_fields.optimize_prompt_options

  3. Sequential generation returning only one image

    • Ensure extra_fields.sequential_image_generation is set to "auto" (default is "disabled")

Last updated on

Qwen Image Format (Image)

Previous Page

OpenAI Audio Format

Next Page

On this page

Seedream Image Format (Image)
📝 Introduction
🤖 Supported Models
💡 Request Examples
Text-to-Image ✅
Image-to-Image (Reference Image) ✅
Generate Image Set (Sequential Generation) ✅
Multi-Image Composition ✅
📮 Request
Endpoint
Create Image
Authentication Method
Request Body Parameters
Size Values
Seedream extra_fields Reference
extra_fields Parameters
📥 Response
Successful Response
usage Fields
Image Object
🌟 Best Practices
Prompt Writing Tips
Parameter Selection Tips
Common Questions