> ## 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.0 Pro · Image to image

> Seedream 5.0 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.

## 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.0.md#authentication)

## Request parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | `dola-seedream-5-0-pro-260628` |
| `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: `jpeg`. `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: `opaque`. `opaque` / `transparent` |
| `optimize_prompt_options` | object | No | Default: `{"mode":"standard"}`. `mode`: `standard` (higher quality, slower) or `fast` (faster, slightly lower quality) |
| `layer_decomposition` | boolean | No | Default: `false`. [Enable layer decomposition](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.0/edits.md#layer_decomposition) |

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.0.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.0.md#size)

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

### background

| Value | Description |
| - | - |
| `opaque` | RGB output without an alpha channel (Default) |
| `transparent` | RGBA output with an alpha channel; use PNG |

> [!WARNING]
>
> 5.0 Pro does not support text-only transparent output. Transparent editing requires exactly one reference image with an existing alpha channel.

> [!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 16 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`.

## 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-0-pro-260628",
  "prompt": "Preserve the appearance of the dog in the reference image and render it as a watercolor illustration",
  "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-0-pro-260628",
    "prompt": "Preserve the appearance of the dog in the reference image and render it as a watercolor illustration",
    "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-0-pro-260628",
  "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-0-pro-260628",
    "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-0-pro-260628",
  "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",
  "output_format": "png"
}
```

```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-0-pro-260628",
    "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",
    "output_format": "png"
  }'
```

### Transparent image editing

```json Request body theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "Give the colored shapes in the reference image a metallic finish and preserve the transparent background",
  "image": "https://raw.githubusercontent.com/pnggroup/libpng/libpng16/pngtest.png",
  "background": "transparent",
  "output_format": "png"
}
```

```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-0-pro-260628",
    "prompt": "Give the colored shapes in the reference image a metallic finish and preserve the transparent background",
    "image": "https://raw.githubusercontent.com/pnggroup/libpng/libpng16/pngtest.png",
    "background": "transparent",
    "output_format": "png"
  }'
```

### Layer decomposition

```json Request body theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "Separate the sky, mountains, lake, and foreground in the reference image into independent layers",
  "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
  "layer_decomposition": 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-0-pro-260628",
    "prompt": "Separate the sky, mountains, lake, and foreground in the reference image into independent layers",
    "image": "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=1024&fm=jpg",
    "layer_decomposition": true,
    "size": "2K",
    "output_format": "jpeg"
  }'
```

## 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.0.md#success-response)

```json theme={null}
{
  "model": "dola-seedream-5-0-pro-260628",
  "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"
    }
  ],
  "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.0.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 |

> [!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.0.md#pricing) · [Error handling](https://docs.gravitex.ai/en/api-reference/endpoint/seedream-5.0.md#error-handling)


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