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

# Doubao Seedream Image Generation API

> Use `POST /v1/images/generations` to call the Doubao Seedream series image generation endpoint.

# Doubao Seedream Image Generation API

The Doubao Seedream series sends requests through a unified image generation entry point, which is suitable for text-to-image and also supports image-to-image via the `image` array to pass reference images.

* The unified entry point is `POST /v1/images/generations`.
* Pass the specific Seedream model name in `model`.
* Pass the pixel dimension string directly in `size`, for example `2048x2048` or `2560x1440`.
* `image` supports image URLs or Base64 arrays, making it suitable for image-to-image and multi-reference-image scenarios.
* Responses are usually compatible with the OpenAI Images style, commonly `url` or `b64_json`.

## Currently Available Models

* `doubao-seedream-4-0-250828`
* `seedream-4-0-250828`
* `doubao-seedream-4-5-251128`
* `doubao-seedream-5-0-260128`

## Method and Path

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

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/images/generations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "doubao-seedream-4-0-250828",
      "prompt": "A cute little sea otter floating on the sea under sunlight, cinematic, high-detail",
      "n": 1,
      "size": "2048x2048"
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/images/generations",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "doubao-seedream-4-0-250828",
          "prompt": "A cute little sea otter floating on the sea under sunlight, cinematic, high-detail",
          "n": 1,
          "size": "2048x2048",
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "doubao-seedream-4-0-250828",
      prompt: "A cute little sea otter floating on the sea under sunlight, cinematic, high-detail",
      n: 1,
      size: "2048x2048",
    }),
  });

  console.log(await response.json());
  ```
</CodeGroup>

## Image-to-Image Example

```json theme={null}
{
  "model": "doubao-seedream-4-5-251128",
  "prompt": "Preserve the subject and atmosphere of the reference image, and redraw it into a more premium advertising poster",
  "n": 1,
  "size": "2560x1440",
  "image": [
    "BASE64_IMAGE_1",
    "https://example.com/reference-2.png"
  ]
}
```

## Response Example

<ResponseExample>
  ```json 200 - URL theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://.../images/doubao-img-abc123.png",
        "revised_prompt": "A cute little sea otter floating on the sea under sunlight, cinematic, high-detail"
      }
    ]
  }
  ```

  ```json 200 - Base64 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "revised_prompt": "A cute little sea otter floating on the sea under sunlight, cinematic, high-detail"
      }
    ]
  }
  ```
</ResponseExample>

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  The Doubao Seedream model name. Common values include `doubao-seedream-4-0-250828`, `doubao-seedream-4-5-251128`, and `doubao-seedream-5-0-260128`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Generation prompt. It is recommended to pass this explicitly for both text-to-image and image-to-image.
</ParamField>

<ParamField body="n" type="integer">
  Number of images to generate. The Apifox you provided treats this as required; from the existing unified image DTO, this field is an optional pointer type in the gateway. To keep behavior consistent with the current plugin, it is recommended to pass `1`.
</ParamField>

<ParamField body="size" type="string">
  Output size, passed directly as width and height pixel values. These Doubao models are typically mapped to fixed pixel sizes based on fixed ratios.
</ParamField>

<ParamField body="image" type="array<string> | string">
  Optional reference image input. Your Apifox definition describes this as "image URL or BASE64 array"; the current plugin also encodes reference images into a Base64 array and puts them in this field.
</ParamField>

<ParamField body="response_format" type="string">
  Optional response format. Common values are `url` and `b64_json`. If omitted, the final response format depends on the upstream service and the gateway compatibility layer.
</ParamField>

<ParamField body="quality" type="string">
  Quality field. The unified image DTO supports accepting it, but whether Doubao actually consumes this field depends on the final upstream service.
</ParamField>

<ParamField body="style" type="string | object">
  Style field. The unified image DTO supports accepting it; whether it takes effect depends on the specific Doubao channel.
</ParamField>

<ParamField body="background" type="string | object">
  Background control field. The unified image DTO supports accepting it; whether it takes effect depends on the specific Doubao channel.
</ParamField>

<ParamField body="watermark" type="boolean">
  Explicit watermark switch. In the current unified image DTO, this field uses a pointer type, and `false` is semantically different from omitting it.
</ParamField>

## Size Mapping

Your Apifox is consistent with the plugin's `DOUBAO_SIZE_MAP`, so you can use the table below:

| Aspect Ratio | `size` Value |
| ------------ | ------------ |
| `1:1`        | `2048x2048`  |
| `4:3`        | `2304x1728`  |
| `3:4`        | `1728x2304`  |
| `16:9`       | `2560x1440`  |
| `9:16`       | `1440x2560`  |
| `3:2`        | `2496x1664`  |
| `2:3`        | `1664x2496`  |
| `21:9`       | `3024x1296`  |

<Info>
  Unlike Gemini, the interfaces in this Doubao series do not pass a "ratio enum" in your existing plugin. Instead, the ratio is first mapped to a specific pixel size, and that size is then written into `size`.
</Info>

## Text-to-Image vs Image-to-Image

| Scenario       | Key Fields                  | Description                                      |
| -------------- | --------------------------- | ------------------------------------------------ |
| Text-to-image  | `prompt` + `size`           | The most basic usage                             |
| Image-to-image | `prompt` + `size` + `image` | `image` can contain one or more reference images |

## Response

<ResponseField name="created" type="integer">
  Generation timestamp.
</ResponseField>

<ResponseField name="data[].url" type="string">
  Returned image URL. When the current plugin encounters this field, it will download the image locally again.
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  Returned image Base64 data. The current plugin will preferentially use this field.
</ResponseField>

<ResponseField name="data[].revised_prompt" type="string">
  Some upstream services return an adjusted prompt.
</ResponseField>

## Related Interfaces

* [Image Model Support Matrix](/en/images/model-matrix)
* [Image Series Overview](/en/images/overview)
* [OpenAI Images Compatibility Overview](/en/images/gpt-image-1/overview)