> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gregapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# doubao-seedream-5.0

Call the Doubao Seedream 5.0 series image models through the OpenAI-compatible interface, covering `doubao-seedream-5.0`, `doubao-seedream-5.0-lite`, and `doubao-seedream-5.0-pro`, with text-to-image and image-to-image support.

All requests are forwarded to Volcengine Ark through GregAPI. You do not need to sign requests yourself; just carry the GregAPI API Key in the header.

```bash theme={null}
export BASE_URL="https://api.gregapi.com/v1"
export TOKEN="oh-xxxxxxxxxxxxxxxx"
```

Consistently use:

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

## Model overview

| Model | Model ID (version mapping) | Resolution | Output format | Key capabilities |
| - | - | - | - | - |
| `doubao-seedream-5.0` | `doubao-seedream-5-0-260128` | `2K` / `3K` / `4K` | png / jpeg | Group generation, multi-image group generation, streaming, online search |
| `doubao-seedream-5.0-lite` | `doubao-seedream-5-0-lite-260128` | `2K` / `3K` / `4K` | png / jpeg | Lightweight, cost-effective; group generation, streaming, online search |
| `doubao-seedream-5.0-pro` | `doubao-seedream-5-0-pro-260628` | `1K` / `1.5K` / `2K` | png / jpeg | Interactive editing, layer decomposition |

### Per-model notes

* `doubao-seedream-5.0`: the base Seedream 5.0 with online search for broader knowledge, reference consistency, and professional scene quality; supports text-to-image, image-to-image, text-to-group, multi-image-to-group, and streaming.
* `doubao-seedream-5.0-lite`: the lightweight Seedream 5.0 with better speed and cost; capabilities match the base (group generation, streaming, online search).
* `doubao-seedream-5.0-pro`: built for high-precision creation; supports interactive editing (coordinate / bounding box / arrow localization) and layer decomposition (1 base image + up to 16 layers); does not support text-to-group, streaming, or online search.

## Endpoint

### Endpoint

```http theme={null}
POST /v1/images/generations
```

### Request headers

```http theme={null}
Authorization: Bearer <TOKEN>
Content-Type: application/json
```

On the console side, bind the `doubao-seedream-*` model name to a Doubao / VolcArk channel (`ChannelTypeVolcArk`) to access it through the unified OpenAI-style interface.

## Request parameters

### Base parameters (OpenAI-compatible)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | ✅ | `doubao-seedream-5.0` / `doubao-seedream-5.0-lite` / `doubao-seedream-5.0-pro` |
| `prompt` | string | ✅ | Image description; recommended no more than 300 Chinese characters or 600 English words |
| `size` | string | ❌ | Resolution tier or exact size. Tier depends on the model: `2K` / `3K` / `4K` for `5.0` / `5.0-lite`, `1K` / `1.5K` / `2K` for `5.0-pro`; also accepts pixel sizes like `2048x2048` |
| `n` | integer | ❌ | Omit for single-image requests; ordinary single-image generation does not support `n>1` |
| `response_format` | string | ❌ | `url` (default) or `b64_json` |
| `quality` | string | ❌ | Image quality, e.g. `high` / `standard` |
| `style` | string | ❌ | Image style, e.g. `vivid` / `natural` |

Group-generation and streaming parameters such as `stream=true`, `tools`, `sequential_image_generation`, and `sequential_image_generation_options` only apply to models that support them (`5.0` and `5.0-lite`); `5.0-pro` does not support these.

### Volcengine Ark-specific parameters

| Parameter | Type | Description |
| - | - | - |
| `image` | string / string\[] | Reference image URL or complete Data URI; bare Base64 is not accepted. A single image may be a string or a single-element array |
| `watermark` | boolean | Whether to add a watermark; default `true` |
| `output_format` | string | Output format: `png` / `jpeg` |

### Base64 reference image format

Each reference image in `image` must be a publicly accessible image URL, or one of these complete Data URIs:

* JPEG: `data:image/jpeg;base64,<full Base64>`
* PNG: `data:image/png;base64,<full Base64>`

The MIME type must match the actual image format, with no spaces or line breaks immediately after the comma. Passing bare Base64 such as `/9j/...` or `iVBOR...` is parsed as a URL and may return HTTP 400 or `InvalidParameter`. `response_format="b64_json"` only controls the output format and will not automatically add a prefix for the input `image`.

## Response format

### Non-streaming response

```json theme={null}
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://...",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}
```

### Base64 response (`response_format=b64_json`)

```json theme={null}
{
  "created": 1589478378,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

`b64_json` is raw Base64 without a Data URI prefix. To reuse the generated result as an `image` input, prepend `data:image/jpeg;base64,` or `data:image/png;base64,`.

## Examples

### Text-to-image

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "doubao-seedream-5.0-pro",
  "prompt": "A cute panda eating bamboo in a bamboo forest, with dappled sunlight through the leaves",
  "size": "2K",
  "response_format": "url"
}'
```

For image-to-image with a reference image, or to use `doubao-seedream-5.0` / `doubao-seedream-5.0-lite`, simply replace `model` (and optionally the `size` tier).

### Image-to-image (Base64 Data URI)

Replace `<full JPEG image Base64>` with the full Base64 of a JPEG image, keeping the leading `data:image/jpeg;base64,`. For PNG images, use `data:image/png;base64,` instead.

```bash theme={null}
curl -X POST "https://api.gregapi.com/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "model": "doubao-seedream-5.0-pro",
  "prompt": "Convert this image to a watercolor style",
  "image": [
    "data:image/jpeg;base64,<full JPEG image Base64>"
  ],
  "size": "2K",
  "response_format": "b64_json"
}'
```

On success, read and decode the image from `data[0].b64_json`. For a single image, `image` can also be written as a single complete Data URI string.

## FAQ

### How to choose a model?

* For high-precision editing, precise localization, and layer decomposition: use `doubao-seedream-5.0-pro`.
* For group generation, streaming, online search, or broader knowledge and consistency: use `doubao-seedream-5.0` or `doubao-seedream-5.0-lite` (lite is more cost-effective).

### How long is the image URL valid?

Generated image URLs are usually valid for 24 hours. Download and save them to your own storage within the validity period.

### How to remove the watermark?

Set `"watermark": false` in the request body to disable the model watermark (provided the current model and account configuration allow it).

### What to do when images won't upload for image-to-image?

* Confirm the `image` field uses a publicly accessible HTTPS URL or a complete Data URI (e.g. `data:image/jpeg;base64,<full Base64>`);
* On `InvalidParameter` / `invalid url specified`, check whether bare Base64 was passed by mistake, and add a prefix matching the actual format;
* `response_format="b64_json"` is an output setting and cannot replace the Data URI prefix required for input images;
* For large images, compress them in advance to avoid exceeding the upstream size limit.

## Billing

* Billed by the number of successfully generated images;
* Failed generations are usually not billed (subject to the upstream bill);
* See the Doubao Seedream entries under "Model Pricing" in the console for specific prices.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.