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

# Seedream 5.5 Pro · Image to image

> Seedream 5.5 Pro Image to image parameters, limits, and copyable examples

## Introduction

Provide reference images and editing instructions for single-image editing, multi-image fusion, interactive editing, transparency, or layer decomposition. Ordinary editing returns one image; decomposition returns a base image and multiple layers. Regular printed text layers can also return rich-text OCR.

## Endpoint and authentication

```http theme={null}
POST https://api.gravitex.ai/v1/images/generations
```

Use `Authorization: Bearer sk-xxxxxxxxxx` and `Content-Type: application/json`. Image editing also accepts `/v1/images/edits` with the same JSON body. [Parameters and pricing](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5.md#authentication)

## Request parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | `dola-seedream-5-5-261028` |
| `prompt` | string | Editing: yes; decomposition: optional | Generation or editing instruction; specify elements to separate for decomposition |
| `image` | string / string\[] | Yes | Reference URL or Base64; up to 10 images for editing, exactly one for decomposition |
| `size` | string | No | Default `2K`; `1K`, `1.5K`, `2K`, or custom `WIDTHxHEIGHT`; decomposition defaults to `auto` |
| `output_format` | string | No | Default: `png`. `jpeg` / `png`; in decomposition, controls the base image only. Layers are always PNG. |
| `response_format` | string | No | Default: `url`. `url` (valid for 24 hours) or `b64_json` |
| `watermark` | boolean | No | Default: `true`. Add an AI-generated watermark in the bottom-right corner |
| `background` | string | No | Default: `auto`. `auto` / `transparent` / `opaque` |
| `optimize_prompt_options` | object | No | Default: `{"mode":"standard"}`. Only `standard` is supported |
| `layer_decomposition` | boolean | No | Default: `false`. [Enable layer decomposition](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5/edits.md#layer_decomposition) |
| `layer_decomposition_options` | object | No | [Decomposition configuration; active only when decomposition is enabled](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5/edits.md#layer_decomposition_options) |

For ordinary generation, omit `n` or use `1`; send separate requests for multiple results. See [shared parameters](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5.md#request-parameters) for full defaults and `safety_identifier`. Neither model supports `quality`, sequential generation, streaming, or web search.

### prompt

Required for editing. Describe how to use or change the reference images. Optional for decomposition: specify elements to separate, or omit to let the model identify the main elements. Keep Chinese prompts within 300 characters and English prompts within 600 words; overly long prompts may dilute details.

For interactive editing, identify a region with `<bbox>x1 y1 x2 y2</bbox>` using normalized `[0, 1000]` coordinates, with the origin at the top-left. Alternatively, draw boxes, arrows, or sketches on the reference and describe the intended changes.

### image

Accepts one string or an array of strings. Each entry is a server-accessible public URL or Base64 data URI in the form `data:image/<format>;base64,<data>`; use lowercase format names, for example `data:image/png;base64,iVBORw0...`.

| Limit | Ordinary editing | Layer decomposition |
| - | - | - |
| Count | Required, up to 10 | Required, exactly one |
| Formats | jpeg, png, webp, bmp, tiff, gif, heic, heif | png, jpeg |
| Width/height ratio | \[1/16, 16] | \[1/16, 16] |
| Width and height | Both greater than 14 px | Subject to total-pixel and aspect-ratio limits |
| Size per image | ≤ 30 MB | ≤ 30 MB |
| Total pixels | \[196, 6000×6000] | \[512×512, 6000×6000] |

> [!NOTE]
>
> Total pixels means width × height, not independent minimum dimensions. Transparency constraints are listed separately below.

### size

[Full size rules and dimension table](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5.md#size)

Decomposition supports only `1K`, `1.5K`, `2K`, and `auto` (default); custom pixel dimensions are not supported.

### background

| Value | Description |
| - | - |
| `auto` | Default; model decides from the prompt and output format. JPEG has no alpha channel. |
| `opaque` | RGB output without an alpha channel |
| `transparent` | RGBA output with an alpha channel; use PNG |

> [!NOTE]
>
> Native transparency works for text-to-image and image-to-image. Editing accepts up to 10 references without requiring alpha channels. Check `data[].background` for actual output transparency; it may differ from the request.

> [!WARNING]
>
> Never combine `background: "transparent"` with JPEG output. Do not pass `background` in decomposition mode.

### layer\_decomposition

Set `layer_decomposition: true` to split one image into one base image and up to 99 independent PNG layers with alpha channels. Default: `false`.

* `image` is required; exactly one input is accepted.
* Any layer failure fails the entire request; partial success is not supported.
* Requested layers beyond the limit may be omitted.
* The response includes `z_index`, `name`, `description`, and `bounding_box`.
* The base image and all layers are counted in `usage.generated_images`.

### layer\_decomposition\_options

Active only when `layer_decomposition` is `true`.

| Field | Type | Default | Range | Description |
| - | - | - | - | - |
| `max_images` | integer | `30` | \[2, 100] | Maximum output count, including the base image |
| `text_recognition` | boolean | `false` | `true` / `false` | Return rich-text OCR for regular printed text layers |

```json theme={null}
{
  "layer_decomposition_options": {
    "max_images": 20,
    "text_recognition": true
  }
}
```

If instructions are absent or vague, the model plans decomposition using image complexity and `max_images`; higher limits usually give finer layers. The upstream service reserves IPM (images per minute) quota using `max_images` and releases unused quota afterward. Non-text layers and irregular text such as handwriting or artistic lettering do not return OCR. Supported fonts: [Seedream 5.5 OCR fonts](https://console.byteplus.com/ark/region:ap-southeast-1/docs/ocr-supported-fonts)

## Request examples

Each example includes a complete JSON body and matching cURL. Replace `sk-xxxxxxxxxx` with your API Key. Input URLs are public and need no login. Response URLs illustrate structure only.

### Single-image editing

```json Request body theme={null}
{
  "model": "dola-seedream-5-5-261028",
  "prompt": "Keep the appearance of the dog in the reference image and replace the background with snowy mountains",
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-5-261028",
    "prompt": "Keep the appearance of the dog in the reference image and replace the background with snowy mountains",
    "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "size": "2K"
  }'
```

### Multi-image fusion

```json Request body theme={null}
{
  "model": "dola-seedream-5-5-261028",
  "prompt": "Place the dog from image 1 in the lakeside scene of image 2, preserving its appearance and matching lighting and perspective",
  "image": [
    "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg"
  ],
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-5-261028",
    "prompt": "Place the dog from image 1 in the lakeside scene of image 2, preserving its appearance and matching lighting and perspective",
    "image": [
      "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
      "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg"
    ],
    "size": "2K"
  }'
```

### Interactive editing

```json Request body theme={null}
{
  "model": "dola-seedream-5-5-261028",
  "prompt": "Edit only <bbox>0 0 1000 300</bbox>: make the background in that region light blue; keep the dog and all other regions unchanged",
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-5-261028",
    "prompt": "Edit only <bbox>0 0 1000 300</bbox>: make the background in that region light blue; keep the dog and all other regions unchanged",
    "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "size": "2K"
  }'
```

### Transparent image editing

```json Request body theme={null}
{
  "model": "dola-seedream-5-5-261028",
  "prompt": "Extract the dog from the reference image, remove the background, and output an image with a transparent background",
  "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
  "background": "transparent",
  "output_format": "png",
  "size": "2K"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-5-261028",
    "prompt": "Extract the dog from the reference image, remove the background, and output an image with a transparent background",
    "image": "https://images.unsplash.com/photo-1517849845537-4d257902454a?w=1024&fm=jpg",
    "background": "transparent",
    "output_format": "png",
    "size": "2K"
  }'
```

### Layer decomposition and OCR

```json Request body theme={null}
{
  "model": "dola-seedream-5-5-261028",
  "prompt": "Separate the regular printed text in the image into independent paragraph layers and recognize the text and its styles",
  "image": "https://raw.githubusercontent.com/tesseract-ocr/tessdoc/main/images/eurotext.png",
  "layer_decomposition": true,
  "layer_decomposition_options": {
    "max_images": 20,
    "text_recognition": true
  },
  "size": "2K",
  "output_format": "jpeg"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-5-261028",
    "prompt": "Separate the regular printed text in the image into independent paragraph layers and recognize the text and its styles",
    "image": "https://raw.githubusercontent.com/tesseract-ocr/tessdoc/main/images/eurotext.png",
    "layer_decomposition": true,
    "layer_decomposition_options": {
      "max_images": 20,
      "text_recognition": true
    },
    "size": "2K",
    "output_format": "jpeg"
  }'
```

### Automatic layer decomposition

```json Request body theme={null}
{
  "model": "dola-seedream-5-5-261028",
  "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
  "layer_decomposition": true,
  "safety_identifier": "5f4dcc3b5aa765d61d8327deb882cf99"
}
```

```bash cURL theme={null}
curl --location 'https://api.gravitex.ai/v1/images/generations' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "dola-seedream-5-5-261028",
    "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
    "layer_decomposition": true,
    "safety_identifier": "5f4dcc3b5aa765d61d8327deb882cf99"
  }'
```

Omit `prompt` to identify and split the main elements automatically. Defaults: `size: "auto"`, `max_images: 30`.

## Success response

Ordinary editing uses the shared response; `usage.input_images` reflects actual reference count. The excerpt below shows only the base image and one layer, while `usage` describes the full result. Therefore its `generated_images` exceeds the number of entries shown. URLs are illustrative. [Shared response](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5.md#success-response)

```json theme={null}
{
  "model": "dola-seedream-5-5-261028",
  "created": 1784696685,
  "data": [
    {
      "url": "https://example.com/base.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/layer-1.png",
      "size": "1273x265",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [383, 120, 1655, 384],
        "normalized": [187, 59, 808, 188]
      },
      "name": "Seedream title text",
      "description": "Large yellow serif Seedream title text",
      "text_recognition": {
        "text": "Seedream",
        "lines": [
          {
            "bounding_box": {
              "absolute": [383, 120, 1655, 384],
              "normalized": [187, 59, 808, 188]
            },
            "runs": [
              {
                "text": "Seedream",
                "style": {
                  "similar_font_family": "Playfair Display",
                  "foreground_color": "#F5C518",
                  "bold": true,
                  "italic": false,
                  "underline": false,
                  "strikethrough": false,
                  "shadow": false,
                  "translucent": false
                }
              }
            ]
          }
        ]
      }
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 8,
    "output_tokens": 23107,
    "total_tokens": 23107
  }
}
```

### Response fields

[Shared response fields](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5.md#response-fields)

| Additional field | Type | Description |
| - | - | - |
| `data[].z_index` | integer | Stacking order: base image is 0, layers start at 1; higher means above |
| `data[].name` | string | Model-generated layer name |
| `data[].description` | string | Detailed layer description |
| `data[].bounding_box.absolute` | integer\[4] | Layer pixel coordinates on the output base image: `[left, top, right, bottom]`; absent on the base image |
| `data[].bounding_box.normalized` | integer\[4] | Same coordinates normalized to `[0, 1000]`; absent on the base image |
| `data[].text_recognition` | object | Rich-text OCR; only when enabled and the layer contains regular printed text |

### text\_recognition

| OCR field | Type | Description |
| - | - | - |
| `text` | string | Full plain text, top-to-bottom and left-to-right; lines separated by `\n` |
| `lines[]` | array | One entry per text line |
| `lines[].bounding_box.absolute` / `.normalized` | integer\[4] | Line coordinates on the base image, following the same bounding-box rules |
| `lines[].runs[]` | array | Style runs; one entry if the entire line has the same style |
| `lines[].runs[].text` | string | Run text without newline characters |
| `lines[].runs[].style.similar_font_family` | string | Closest matching font, or `unknown` if recognition/confidence is insufficient |
| `lines[].runs[].style.foreground_color` | string | Uppercase `#RRGGBB`, without alpha |
| `lines[].runs[].style.bold` | boolean | Bold |
| `lines[].runs[].style.italic` | boolean | Italic glyphs; whole-layer rotation or perspective does not count |
| `lines[].runs[].style.underline` | boolean | Underline; excludes standalone rules and table borders |
| `lines[].runs[].style.strikethrough` | boolean | Strikethrough |
| `lines[].runs[].style.shadow` | boolean | Visible shadow, projection, or offset glow |
| `lines[].runs[].style.translucent` | boolean | Text itself is semitransparent; solid pale text does not count |

> [!NOTE]
>
> Styles are recognized automatically and may differ from exact original attributes.

> [!NOTE]
>
> **Reconstruct layers**: resize each layer to `(right - left) × (bottom - top)` using absolute coordinates, then place it at `(left, top)` on the base image. For normalized coordinates on a `W × H` canvas, the top-left position is `(left / 1000 × W, top / 1000 × H)`. Stack layers in ascending `z_index` order.

> [!WARNING]
>
> Result URLs expire after 24 hours. Download and persist them immediately.

## Pricing and errors

Reference images and outputs are billed separately; the base image and each layer count as individual outputs.

[Pricing](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5.md#pricing) · [Error handling](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.5.md#error-handling)


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