# doubao-seedream API

This document describes the input and output parameters for calling the `doubao-seedream-4.5` and `doubao-seedream-5-0-260128` models, for your reference when using the API.

---

## Request Parameters

### Request Body

| Field Name | Type | Required | Default | Description |
| ---------- | ---- | -------- | ------- | ----------- |
| model | string | Yes | - | The model name used in this request. Available values:<br>`doubao-seedream-4.5`<br>`doubao-seedream-5-0-260128` |
| prompt | string | Yes | - | Prompt for image generation. Supports both Chinese and English. Recommended to be within 300 Chinese characters or 600 English words. |
| images | array(string) | Optional | - | Input image data. Supports URL or Base64 encoding. Supports single or multiple images, up to 14 reference images.<br>Image URL: must be accessible.<br>Base64 format: `data:image/<format>;base64,<Base64>` (format must be lowercase, e.g., `data:image/png;base64,<base64_image>`). |
| size | string | Optional | - | Specifies image size. Two modes (cannot be mixed):<br>Mode 1: Specify resolution (e.g., 2K, 4K) and describe aspect ratio/shape/use case in prompt.<br>Mode 2: Specify exact width × height. Default: 2048x2048. Pixel range: [2560x1440=3686400, 4096x4096=16777216]. Aspect ratio range: [1/16, 16]. Recommended: 2048x2048, 2304x1728, 1728x2304, 2560x1440, 1440x2560, 2496x1664, 1664x2496, 3024x1296 |
| sequential_image_generation | string | Optional | disabled | Controls multi-image generation.<br>auto: model decides whether to return multiple images.<br>disabled: only one image is generated. |
| sequential_image_generation_options | object | Optional | - | Configuration for multi-image generation. Effective only when sequential_image_generation = auto. |
| sequential_image_generation_options.max_images | integer | Optional | - | Maximum number of images to generate. Range: [1, 15] |
| stream | Boolean | Optional | false | Whether to enable streaming mode.<br>false: return all images at once.<br>true: stream images as they are generated. |
| response_format | string | Optional | url | Image return format (jpeg only).<br>url: returns download link (valid for 24 hours).<br>b64_json: returns Base64-encoded JSON data. |
| watermark | Boolean | Optional | true | Whether to add watermark.<br>false: no watermark.<br>true: adds "AI-generated" watermark at bottom-right. |
| optimize_prompt_options | object | Optional | - | Prompt optimization configuration. |
| tools | array[object] | Optional | - | Tools configuration. Only supported by `doubao-seedream-5-0-260128`. |
| tools.type | string | Optional | web_search | `web_search`: enables web search. The model may retrieve real-time data (e.g., products, weather), improving timeliness but increasing latency. |
| output_format | string | Optional | jpeg | Output image format. Only supported by `doubao-seedream-5-0-260128`.<br>Options:<br>`png`<br>`jpeg` |

## Non-stream Response Parameters

| Field Name | Type | Description |
| ---------- | ---- | ----------- |
| model | `string` | Model ID used in this request (model-name-version). |
| created | `integer` | Unix timestamp (seconds) when the request was created. |
| data | `array` | Output image data or error info. |
| data.url | `string` | Image URL (when response_format = url). Valid for 24 hours. |
| data.b64_json | `string` | Base64 image data (when response_format = b64_json). |
| data.size | `string` | Image size in format `<width>x<height>`, e.g., 2048×2048. |
| data.error | `object` | Error object for image generation. |
| data.error.code | `string` | Error code. |
| data.error.message | `string` | Error message. |
| usage | `object` | Usage information. |
| usage.generated_images | `integer` | Number of successfully generated images (billing applies only to successful ones). |
| usage.output_tokens | `integer` | Tokens consumed by image generation.<br>Calculated as sum(width × height) / 256, rounded down. |
| usage.total_tokens | `integer` | Total tokens used (same as output_tokens). |
| error | `object` | Error object for the request. |
| error.code | `string` | Error code. |
| error.message | `string` | Error message. |

## Stream Response Parameters

When `stream=true`, the server uses Server-Sent Events (SSE) to push real-time updates.

### image_generation.partial_succeeded

Triggered when any image is successfully generated.

| Field Name | Type | Description |
| ---------- | ---- | ----------- |
| type | `string` | Event type: image_generation.partial_succeeded |
| model | `string` | Model ID |
| created | `integer` | Unix timestamp |
| image_index | `integer` | Index of image in request (starting from 0, increments regardless of success/failure) |
| url | `string` | Image URL (if response_format=url) |
| b64_json | `string` | Base64 image data (if response_format=b64_json) |
| size | `string` | Image size `<width>x<height>` |

### image_generation.partial_failed

Triggered when any image fails to generate.

| Field Name | Type | Description |
| ---------- | ---- | ----------- |
| type | `string` | Event type: image_generation.partial_failed |
| model | `string` | Model ID |
| created | `integer` | Unix timestamp |
| image_index | `integer` | Index of image |
| error | `object` | Error details |
| error.code | `string` | Error code |
| error.message | `string` | Error message |

### image_generation.completed

Triggered when all images are processed (success or failure).

| Field Name | Type | Description |
| ---------- | ---- | ----------- |
| type | `string` | Event type: image_generation.completed |
| model | `string` | Model ID |
| created | `integer` | Unix timestamp |
| usage | `object` | Usage info |
| usage.generated_images | `integer` | Number of successfully generated images |
| usage.output_tokens | `integer` | Token usage (sum(width × height)/256) |
| usage.total_tokens | `integer` | Total tokens used |

## Example

### OpenAI-Compatible API

`POST https://api-us-ca.umodelverse.ai/v1/images/generations`

<!-- tabs:start -->
#### ** curl **
```bash
curl --location 'https://api-us-ca.umodelverse.ai/v1/images/generations' \
  --header "Authorization: Bearer $MODELVERSE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedream-4.5",
    "prompt": "Convert image to pencil sketch",
    "images": ["https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg"],
    "size": "2k",
    "watermark": false,
    "stream": false,
    "response_format":"url"
  }'
```

#### ** seedream-5.0 with web search **

```bash
curl --location 'https://api-us-ca.umodelverse.ai/v1/images/generations' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "Create a 5-day weather forecast infographic for Shanghai in a modern flat illustration style, clearly showing weather, temperature, and outfit suggestions.",
    "size": "2k",
    "tools": [
      {
          "type": "web_search"
      }
  ],
    "output_format":"jpeg",
    "response_format": "url",
    "watermark": false
}'
```

#### ** python **

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api-us-ca.umodelverse.ai/v1",
    api_key=os.getenv("MODELVERSE_API_KEY", "YOUR_API_KEY")
)

response = client.images.generate(
    model="doubao-seedream-4.5",
    prompt="Convert to quick pencil sketch",
    extra_body={
        "images":["https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg"],
        "size":"2K",
        "response_format":"url",
        "watermark":False
    }
)

print(response.data[0].url)
```

<!-- tabs:end -->

### Response
```json
{
	"model": "doubao-seedream-4-5-251128",
	"created": 1767939740,
	"data": [{
		"url": "https://xxxxxx",
		"size": "2048x2048"
	}],
	"usage": {
		"generated_images": 1,
		"output_tokens": 16384,
		"total_tokens": 16384
	}
}
```