# BytePlus Seedream

import { Steps } from '@astrojs/starlight/components'

Invoke supports BytePlus's **Seedream** image generation family through the BytePlus Ark API. Seedream is a strong fit for 2K/4K generations and multi-reference image composition.

## Getting an API Key

<Steps>
1. Open the [BytePlus Console](https://console.byteplus.com/) and sign in.
2. Enable the **Ark** (model serving) product.
3. Create an API key with access to the Seedream models you plan to use.
</Steps>

## Configuration

Add your key to `api_keys.yaml` in your Invoke root directory:

```yaml
external_seedream_api_key: "your-seedream-api-key"

# Optional — change only if you need a different regional endpoint
external_seedream_base_url: "https://ark.ap-southeast.bytepluses.com"
```

Restart Invoke for the change to take effect.

## Available Models

| Model | Modes | Reference Images | Batch | Native Size |
| --- | --- | --- | --- | --- |
| **Seedream 5.0** | txt2img, img2img | up to 14 | up to 15 | 2K |
| **Seedream 5.0 Lite** | txt2img, img2img | up to 14 | up to 15 | 2K |
| **Seedream 4.5** | txt2img, img2img | up to 14 | up to 15 | 2K |
| **Seedream 4.0** | txt2img, img2img | up to 14 | up to 15 | 2K |

The 4.x / 5.x models are batch-capable and accept up to 14 reference images per request.

:::note[Model IDs]
BytePlus uses date-stamped model IDs (e.g. `seedream-5-0-260128`). When BytePlus releases a new dated revision, the starter model IDs in Invoke need to be updated. Seedream 3.0 T2I (`seedream-3-0-t2i-250415`) was deprecated by BytePlus and replaced by Seedream 4.0.
:::

### Supported Aspect Ratios

All Seedream models share the same aspect ratio set: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`, rendered at 2K.

## Provider-Specific Options

Selecting a Seedream model adds a **Provider options** section to the Generate panel with two toggles:

- **Watermark** — When enabled, BytePlus adds a small watermark to the output. Off by default.
- **Optimize Prompt** — When enabled, BytePlus rewrites your prompt server-side for better generation quality. Useful for short prompts; disable if you want the exact wording preserved.

Both are recorded in the image metadata and restored by **Recall All** and **Remix**. The Size section lists the provider's 2K sizes per aspect ratio under **Provider size**.

## Canvas

Seedream models advertise `img2img`, so they can generate from the Canvas: an empty bounding box runs text-to-image, and a filled one sends the composited bounding box as the init image. Invoke asks for the provider size whose aspect ratio is closest to the bounding box's. A text-to-image result is scaled to cover the bounding box and cropped to it from the center, so it is never stretched; when the shapes differ, a strip at two opposite edges is cut off. For image-to-image, the init image is resized to the provider size and the result is resized back to the exact bounding box. The render size, denoising strength, control layers and regional guidance do not apply and are not offered. Inpainting and outpainting are not available.

**Seed** and **guidance scale** are not accepted by the 4.x / 5.x family.

## Reference Images

4.x and 5.x Seedream models accept up to 14 reference images alongside the prompt. Invoke's standard reference-image panel is used — drag images in, and they are forwarded as base64 PNGs to the API.

## Tips

<Steps>
1. For multi-image composition (e.g. character + product), Seedream 4.5 is a good default.
2. When running large batches (`num_images > 1` on 4.x / 5.x), Invoke uses the `sequential_image_generation` API flag — each image is returned as it completes.
3. Set `external_seedream_base_url` if you need to route through a region-specific Ark endpoint.
</Steps>