v1.0 to v1.0

---

name: seedream-image

description: Generate and edit AI images with Seedream (ByteDance) via AceDataCloud API. Use when creating images from text prompts, editing existing images, or working with high-resolution outputs. Supports Seedream 4.0, 4.5, and 5.0 models.

license: Apache-2.0

metadata:

author: acedatacloud

version: "1.0"

compatibility: Requires ACEDATACLOUD_API_TOKEN in .env file (see _shared/authentication.md). Optionally pair with mcp-seedream for tool-use.

---

# Seedream Image Generation

Generate and edit AI images through AceDataCloud's Seedream (ByteDance) API.

> **Setup:** See [authentication](../_shared/authentication.md) for token setup.

## Quick Start

```bash

curl -X POST https://api.acedata.cloud/seedream/images \

-H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \

-H "Content-Type: application/json" \

-d '{"prompt": "a cyberpunk cat wearing VR goggles in a neon city", "model": "doubao-seedream-5-0-260128"}'

```

> **Async:** See [async task polling](../_shared/async-tasks.md). Poll via `POST /seedream/tasks` with `{"id": "..."}`.

## Models

| Model | Version | Best For |

|-------|---------|----------|

| `doubao-seedream-5-0-260128` | Seedream 5.0 | Latest, highest quality (default) |

| `doubao-seedream-4-5-251128` | Seedream 4.5 | High quality, balanced |

| `doubao-seedream-4-0-250828` | Seedream 4.0 | Reliable generation |

## Workflows

### 1. Text-to-Image

```json

POST /seedream/images

{

"prompt": "a serene Japanese garden with cherry blossoms and a red bridge",

"model": "doubao-seedream-5-0-260128",

"size": "1K"

}

```

### 2. Image Editing (Image-to-Image)

Edit an existing image by providing the source image URL(s) and a descriptive prompt. Seedream 5.0 Pro, 5.0 Lite, 4.5, and 4.0 all support image input.

```json

POST /seedream/images

{

"prompt": "change the sky to a golden sunset",

"model": "doubao-seedream-5-0-260128",

"image": ["https://example.com/photo.jpg"]

}

```

### 3. Async Generation with Task Polling

Pass a `callback_url` to receive results asynchronously via webhook, or poll `/seedream/tasks` for the result:

```json

POST /seedream/images

{

"prompt": "an epic fantasy landscape",

"model": "doubao-seedream-5-0-260128",

"callback_url": "https://api.acedata.cloud/health"

}

```

Poll the returned `task_id`:

```json

POST /seedream/tasks

{"id": "<task_id>"}

```

## Parameters

### Generation

| Parameter | Values | Description |

|-----------|--------|-------------|

| `model` | see Models table | Model to use (required) |

| `prompt` | string | Image description (required) |

| `size` | `"1K"`, `"2K"`, `"3K"`, `"4K"`, `"adaptive"` | Output resolution; available presets depend on the selected model |

| `sequential_image_generation` | `"auto"`, `"disabled"` | Generate related images in sequence (5.0, 4.5, 4.0 only) |

| `stream` | boolean | Stream images as they're generated (5.0, 4.5, 4.0 only) |

| `watermark` | boolean | Add AI-generated watermark (default: true) |

| `output_format` | `"jpeg"`, `"png"` | Output file format (Seedream 5.0 only; default: jpeg) |

| `response_format` | `"url"`, `"b64_json"` | Response format (default: url) |

| `tools` | array | Enable tools, e.g. `[{"type": "web_search"}]` (Seedream 5.0 only) |

| `callback_url` | string | Webhook URL for async delivery; returns `task_id` immediately |

### Editing

| Parameter | Required | Description |

|-----------|----------|-------------|

| `image` | Yes (for editing) | Array of image URLs or base64 strings (max 10MB each) |

| `prompt` | Yes | Describe the desired edit |

## Gotchas

- Model names now use the `doubao-*` naming convention (e.g. `doubao-seedream-5-0-260128`)

- Image editing uses the same `/seedream/images` endpoint with the `image` array parameter (no separate edit endpoint)

- `size` replaces separate `width`/`height` params; use `"1K"` for 1024×1024, `"2K"` for 2048×2048, etc.

- 5.0 Pro supports `1K`/`2K`; 5.0 Lite supports `2K`/`3K`/`4K`; 4.5 supports `2K`/`4K`; 4.0 supports `1K`/`2K`/`4K`; `adaptive` selects a size from the reference image

- `stream` and `sequential_image_generation` are only available for Seedream 5.0, 4.5, and 4.0

- Pass `callback_url` to get a `task_id` immediately and avoid blocking; poll `/seedream/tasks` for the result — use `"https://api.acedata.cloud/health"` as a placeholder to force async mode without a real webhook

> **MCP:** `pip install mcp-seedream` | Hosted: `https://seedream.mcp.acedata.cloud/mcp` | See [all MCP servers](../_shared/mcp-servers.md)