ToAPIsToAPIs
Seedream-5.0-Pro

Seedream-5.0-Pro Image Generation

Generate high-quality images using Seedream 5.0 Pro model with 1K/2K resolution

POST
/v1/images/generations

Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.

  • Seedream 5.0 Pro high-quality image generation model from ByteDance Seed team
  • Use the model parameter to select doubao-seedream-5-0-pro
  • Parameters are largely the same as Seedream-5.0, but Pro supports 1K and 2K resolutions
  • Supports text-to-image, image-to-image, and multi-reference generation
  • Billing rule: the first reference image is free; billing starts from the second reference image
  • Async task management, query results by task ID

Important Change: For better performance and cost control, we no longer support passing base64 image data directly in image_urls. Please use the Upload Image API first to upload images and get URLs, then call this endpoint.

Authorizations

Authorizationstringheaderrequired

All endpoints require Bearer Token authentication

Get your API Key from the API Key Management Page

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

modelstringbodyrequireddefault: doubao-seedream-5-0-pro

Image generation model name

Example: "doubao-seedream-5-0-pro"

promptstringbodyrequired

Text description for image generation

sizestringbodydefault: 1:1

Image aspect ratio

When layer_decomposition is enabled, pass the 1K or 2K resolution preset directly in this field.

Supported aspect ratios:

  • 1:1 - Square (default)
  • 4:3 - Landscape 4:3
  • 3:4 - Portrait 3:4
  • 16:9 - Landscape widescreen
  • 9:16 - Portrait vertical
  • 3:2 - Landscape 3:2
  • 2:3 - Portrait 2:3
  • 21:9 - Ultra-wide
  • 9:21 - Ultra-tall
nintegerbodydefault: 1

Number of images to generate

Range: 1-10 (minimum 1, maximum 10)

Default: 1

Note:

  • The total of reference images + generated images must be ≤ 15
  • Must enter a plain number (e.g., 1), do not use quotes or it will cause an error

Charges will be pre-deducted based on generated image count and reference image count, with the first reference image free

layer_decompositionbooleanbodydefault: false

Enables the layer decomposition capability available only in Seedream 5.0 Pro.

  • false: returns a regular flattened image (default)
  • true: returns a base image plus independent transparent PNG layers

When enabled, each result.data[] item includes z_index; independent layers also include bounding_box, name, and description.

image_urlsstring[]body

Reference image URL list for image-to-image or image editing

⚠️ URL format only (base64 no longer supported)

  • Publicly accessible image URL (http:// or https://)
  • You can use the Upload Image API to upload local images and get URLs

Limitations:

  • Image count: 1-10
  • Image formats: jpeg, png
  • Aspect ratio (width/height) range: [1/3, 3]
  • Width and height (px) > 14
  • Size: not exceeding 10MB
  • Total pixels: not exceeding 6000×6000 px

Billing notes:

  • The first reference image is free
  • Billing applies from the second reference image onward
metadataobjectbody

Channel-specific parameters for advanced Seedream 5.0 Pro model configuration

metadata properties
metadata.resolutionstringbodydefault: 2K

Image resolution

Supported resolutions:

  • 1K - Basic resolution
  • 2K - Standard resolution (default)

Note: Seedream 5.0 Pro does not support 3K or 4K resolution; non-Pro Seedream 5.0 supports 2K and 3K

metadata.sequential_image_generationstringbodydefault: disabled

Sequential image generation mode (Doubao-specific feature)

Controls whether to generate multiple images:

  • disabled: Disable sequential mode, generates only 1 image even with multiple reference images (default)
  • auto: Enable sequential mode, can generate multiple images

Usage Notes:

  • ✅ Set n: 3 or use sequential_image_generation: "auto" + max_images: 3
  • ✅ Supports text-to-image sets: up to 10 images from text prompt only
  • ✅ Supports image-to-image sets: provide image_urls to generate multiple variations
  • ⚠️ When n > 1, it will automatically be set to auto

Note:

  • Total reference images + generated images must be ≤ 15
metadata.sequential_image_generation_optionsobjectbody

Sequential image generation options

Available when sequential_image_generation is set to auto

Properties:

  • max_images (integer): Specify the number of images to generate, Range: 1-10

Example:

"sequential_image_generation_options": { "max_images": 3 }
metadata.watermarkbooleanbodydefault: false

Whether to add a watermark to the generated image

  • true: Add watermark
  • false: No watermark (default)

Response

idstring

Unique task identifier for status queries

objectstring

Object type, always generation.task

modelstring

Model name used

statusstring

Task status

  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
progressinteger

Task progress percentage (0-100)

created_atinteger

Task creation timestamp (Unix timestamp)

metadataobject

Task metadata

completed_atinteger

Task completion timestamp (Unix timestamp). Returned only after the task completes.

expires_atinteger

Result file expiration timestamp (Unix timestamp). Download or persist the files before they expire.

resultobject

Generated result returned when status is completed.

result.typestring

Result type. Always image for image tasks.

result.dataarray

Image result list. With layer decomposition enabled, the first item is normally the base image and the remaining items are independent transparent PNG layers.

result.data[].urlstring

Public URL of the base image or independent layer.

result.data[].z_indexinteger

Layer stacking order. With layer decomposition enabled, the base image is normally 0 and independent layers increase from there.

result.data[].sizestring

Pixel dimensions of the base image or independent layer, for example 2048x2048.

result.data[].output_formatstring

File format of this result item. The base image can use the requested format; transparent independent layers use png.

result.data[].bounding_boxobject

Layer position on the base image, with absolute and normalized coordinates.

result.data[].bounding_box.absolutearray

Absolute pixel coordinates on the base image in [x1, y1, x2, y2] order, representing the top-left and bottom-right corners.

result.data[].bounding_box.normalizedarray

Normalized coordinates in [x1, y1, x2, y2] order, with values ranging from 0 to 1000.

result.data[].namestring

Layer name.

result.data[].descriptionstring

Description of the layer contents.

requestExample

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A cute panda playing in a bamboo forest",
    "size": "1:1",
    "n": 1,
    "metadata": {
      "resolution": "2K"
    }
  }'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A cute panda playing in a bamboo forest",
    "size": "1:1",
    "n": 1,
    "image_urls": [
      "https://example.com/panda.jpg"
    ],
    "metadata": {
      "resolution": "1K"
    }
  }'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "Precisely separate the image into a base image and independent transparent PNG layers.",
    "image_urls": [
      "https://example.com/office-desk.png"
    ],
    "size": "2K",
    "n": 1,
    "layer_decomposition": true
  }'

When layer_decomposition is enabled, set size directly to the 1K or 2K resolution preset. Do not use an explicit WIDTHxHEIGHT pixel size. After submission, query GET /v1/images/generations/{task_id} for the complete layer result.

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A cute panda playing in a bamboo forest",
    "size": "1:1",
    "n": 4,
    "metadata": {
      "resolution": "2K",
      "sequential_image_generation": "auto",
      "sequential_image_generation_options": { "max_images": 4 },
      "watermark": false
    }
  }'
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "doubao-seedream-5-0-pro",
        "prompt": "A cute panda playing in a bamboo forest",
        "size": "1:1",
        "n": 1,
        "metadata": {
            "resolution": "2K"
        }
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "doubao-seedream-5-0-pro",
        "prompt": "A cute panda playing in a bamboo forest",
        "size": "1:1",
        "n": 1,
        "image_urls": ["https://example.com/panda.jpg"],
        "metadata": {
            "resolution": "1K"
        }
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'doubao-seedream-5-0-pro',
    prompt: 'A cute panda playing in a bamboo forest',
    size: '1:1',
    n: 1,
    metadata: {
      resolution: '2K'
    }
  })
});

const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'doubao-seedream-5-0-pro',
    prompt: 'A cute panda playing in a bamboo forest',
    size: '1:1',
    n: 1,
    image_urls: ['https://example.com/panda.jpg'],
    metadata: {
      resolution: '1K'
    }
  })
});

const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);

responseExample

{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "doubao-seedream-5-0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}
{
  "completed_at": 1787128810,
  "created_at": 1787128650,
  "expires_at": 1789720810,
  "id": "tsk_img_example_layer_decomposition",
  "model": "doubao-seedream-5-0-pro",
  "object": "generation.task",
  "progress": 100,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/images/example/base.jpg",
        "size": "1600x2848",
        "output_format": "jpeg",
        "z_index": 0
      },
      {
        "url": "https://files.toapis.com/images/example/layer-1.png",
        "size": "3040x955",
        "output_format": "png",
        "z_index": 1,
        "bounding_box": {
          "absolute": [0, 0, 1600, 503],
          "normalized": [0, 0, 999, 176]
        },
        "name": "Background office equipment",
        "description": "The monitor edge and file organizer extracted from the background"
      },
      {
        "url": "https://files.toapis.com/images/example/layer-2.png",
        "size": "1982x1162",
        "output_format": "png",
        "z_index": 2,
        "bounding_box": {
          "absolute": [800, 589, 1599, 1058],
          "normalized": [500, 207, 999, 371]
        },
        "name": "Stacked white papers",
        "description": "Several stacked white office papers extracted from the desk"
      }
    ]
  },
  "status": "completed"
}