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

# Seedream 5.5 Layer Decomposition

> The Seedream 5.5 Layer Decomposition API splits one image into a base image and up to 99 transparent PNG layers, with layer positions, names, descriptions, and optional text OCR.

> [!TIP]
>
> 1. After submission, a `task_id` will be returned. If you provided a `callback_url`, when the task status becomes `finished` or `failed`, a POST request will be sent to the `callback_url`.
> 2. Regardless of whether `callback_url` is provided, you can retrieve the response result through the unified [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) endpoint.

Use `seedream-5.5-layerize` to turn a flat poster, illustration, or product image into separate transparent layers that you can move, recolor, replace, or reuse. Each layer comes with its position on the canvas, a name, and a description. With `text_recognition`, regular text layers also return their text, line positions, and approximate styles. This model is the layer decomposition mode of [Seedream 5.5](https://docs.poyo.ai/api-manual/image-series/seedream-5-5.md), ByteDance Seed's image creation model released on November 9, 2026.

## Models

* **seedream-5.5-layerize** — One input image in; a base image plus transparent PNG layers out

## Features

* One base image plus up to 99 layers per request (`max_images` up to 100).
* Prompt-guided decomposition: describe which elements to separate, or leave the prompt out to separate the main elements automatically.
* Every layer is a transparent PNG with its bounding box on the base image, so the layers stack back into the original layout.
* Text OCR for regular text layers: full text, line positions, and approximate font, color, and text styles.
* `1K`, `1.5K`, `2K`, or `auto` output size.

## Required parameters

* `image_urls` (array of strings): Exactly 1 publicly accessible HTTP(S) image URL (JPEG or PNG, up to 10 MB, 512×512 to 6000×6000 pixels, aspect ratio between 1:16 and 16:1).

## Optional parameters

* `prompt` (string): How to split the image, up to 2,000 characters. Example: "Put each animal on its own layer and keep the rest of the scene in the base image." When the prompt is omitted, the model finds the main elements and puts each on its own layer.
* `resolution` (string): `1K`, `1.5K`, `2K`, or `auto`. Default is `auto`, which keeps the original size when it is between 1K and 2K, upscales smaller images to 1K, and downscales larger images to 2K. The base image keeps the aspect ratio of the input; each layer keeps its own aspect ratio at about the selected tier.
* `max_images` (integer): Maximum number of output images, including the base image, from 2 to 100. Default is `30`. Larger values give finer decomposition.
* `text_recognition` (boolean): Return OCR results for regular text layers in `layer.text_recognition`. Default is `false`.
* `output_format` (string): `png` or `jpeg` for the base image. Default is `png`. Layers are always transparent PNGs.
* `enable_safety_checker` (boolean): Content safety check. Default is `true`.

## Output

When the task finishes, `files` in [Query Task Status](https://docs.poyo.ai/api-manual/task-management/status.md) and in the callback lists one file per image, base image first. Each file has a `layer` object:

* `z_index` (integer): Stacking order. The base image is `0`; layers count up from `1`, and a higher value sits on top.
* `name` (string): Short layer name written by the model.
* `description` (string): Longer description of the layer content, such as color, material, and state.
* `bounding_box` (object): Position of the layer on the base image. `absolute` is `[left, top, right, bottom]` in base-image pixels; `normalized` is the same box on a 0–1000 scale.
* `text_recognition` (object): OCR result for a regular text layer when `text_recognition` is `true`. `text` holds the full text with line breaks; `lines` holds each line's `bounding_box` and `runs`, and each run has its `text` and a `style` with `similar_font_family`, `foreground_color`, `bold`, `italic`, `underline`, `strikethrough`, `shadow`, and `translucent`.

```json theme={"dark"}
{
  "files": [
    {
      "file_url": "https://storage.poyo.ai/images/task-unified-1794470400-abcd1234/task-unified-1794470400-abcd1234_1.png",
      "file_type": "image",
      "layer": { "z_index": 0 }
    },
    {
      "file_url": "https://storage.poyo.ai/images/task-unified-1794470400-abcd1234/task-unified-1794470400-abcd1234_2.png",
      "file_type": "image",
      "layer": {
        "z_index": 1,
        "name": "THANK YOU headline",
        "description": "Large bold navy headline text reading THANK YOU.",
        "bounding_box": {
          "absolute": [0, 172, 1366, 458],
          "normalized": [0, 224, 1000, 596]
        },
        "text_recognition": {
          "text": "THANK YOU",
          "lines": [
            {
              "bounding_box": {
                "absolute": [0, 172, 1366, 458],
                "normalized": [0, 224, 1000, 596]
              },
              "runs": [
                {
                  "text": "THANK YOU",
                  "style": {
                    "similar_font_family": "Arial",
                    "foreground_color": "#1B3A96",
                    "bold": true,
                    "italic": false,
                    "underline": false,
                    "strikethrough": false,
                    "shadow": false,
                    "translucent": false
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}
```

To rebuild the original image, scale each layer to `right - left` by `bottom - top`, place it at `(left, top)` on the base image, and stack layers in ascending `z_index`. Use `normalized` to place layers on a canvas of another size.

## Examples

### Automatic Layers

Separate the main elements of a poster with the default settings:

```json theme={"dark"}
{
  "model": "seedream-5.5-layerize",
  "input": {
    "image_urls": ["https://example.com/poster.png"]
  }
}
```

### Guided Layers

Choose which elements become layers:

```json theme={"dark"}
{
  "model": "seedream-5.5-layerize",
  "input": {
    "prompt": "Put each animal on its own layer and keep the rest of the scene in the base image",
    "image_urls": ["https://example.com/animal-illustration.png"],
    "resolution": "2K",
    "max_images": 40
  }
}
```

### Text Layers With OCR

Split an event poster and read its text layers:

```json theme={"dark"}
{
  "model": "seedream-5.5-layerize",
  "input": {
    "image_urls": ["https://example.com/event-poster.png"],
    "resolution": "1K",
    "max_images": 15,
    "text_recognition": true,
    "output_format": "jpeg"
  }
}
```

## Notes

* Credits are charged for the images actually returned, including the base image. At submission, your balance must cover `max_images` images.
* `auto` resolution is billed at the `2K` rate.
* The number of returned images follows the image content, up to `max_images`; a simple image yields fewer layers.
* Layer names and descriptions are written by the model.
* A request usually finishes in about 20 to 50 seconds; higher `max_images` values take longer.


## OpenAPI

````yaml api-manual/image-series/seedream-5-5-layerize.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: PoYo AI - Seedream 5.5 Layer Decomposition API
  description: >-
    The Seedream 5.5 Layer Decomposition API splits one image into a base image
    and up to 99 transparent PNG layers, with layer positions, names,
    descriptions, and optional text OCR.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Seedream 5.5 Layer Decomposition
      summary: Submit Seedream 5.5 Layer Decomposition Task
      description: >-
        Seedream 5.5 layer decomposition: one input image in, a base image plus
        transparent PNG layers out.
      operationId: submitSeedream55LayerizeTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              auto-layers:
                summary: Automatic Layers
                value:
                  model: seedream-5.5-layerize
                  input:
                    image_urls:
                      - https://example.com/poster.png
              guided-layers:
                summary: Guided Layers
                value:
                  model: seedream-5.5-layerize
                  input:
                    prompt: >-
                      Put each animal on its own layer and keep the rest of the
                      scene in the base image
                    image_urls:
                      - https://example.com/animal-illustration.png
                    resolution: 2K
                    max_images: 40
              text-layers:
                summary: Text Layers With OCR
                value:
                  model: seedream-5.5-layerize
                  input:
                    image_urls:
                      - https://example.com/event-poster.png
                    resolution: 1K
                    max_images: 15
                    text_recognition: true
                    output_format: jpeg
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - seedream-5.5-layerize
          description: Seedream 5.5 Layer Decomposition model identifier.
        callback_url:
          type: string
          format: uri
          description: Optional webhook URL for task completion or failure.
        input:
          type: object
          additionalProperties: false
          required:
            - image_urls
          description: >-
            Split one image into a base image and transparent PNG layers. The
            task returns one file per image, base image first; each file has a
            layer object.
          properties:
            image_urls:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
                format: uri
              description: >-
                Exactly 1 image URL to decompose. Must be an array. The URL must
                be a publicly accessible HTTP or HTTPS URL pointing to a JPEG or
                PNG image of up to 10 MB, from 512x512 to 6000x6000 pixels, with
                an aspect ratio between 1:16 and 16:1.
              example:
                - https://example.com/poster.png
            prompt:
              type: string
              maxLength: 2000
              description: >-
                Optional instruction for how to split the image, up to 2000
                characters (for example, put each animal on its own layer and
                keep the rest in the base image). When the prompt is omitted,
                the model finds the main elements and puts each on its own
                layer.
            resolution:
              type: string
              enum:
                - 1K
                - 1.5K
                - 2K
                - auto
              default: auto
              description: >-
                Output size tier. auto keeps the original size when it is
                between 1K and 2K, upscales smaller images to 1K, and downscales
                larger images to 2K; auto is billed as 2K. The base image keeps
                the aspect ratio of the input; each layer keeps its own aspect
                ratio at about the selected tier.
            max_images:
              type: integer
              minimum: 2
              maximum: 100
              default: 30
              description: >-
                Maximum number of output images, including the base image
                (2–100). Larger values give finer decomposition. The number of
                returned images follows the image content, and credits are
                charged for the images actually returned.
            text_recognition:
              type: boolean
              default: false
              description: >-
                Return OCR results for regular text layers in
                layer.text_recognition: the full text, line positions, and
                approximate styles (font, color, bold, italic, underline,
                strikethrough, shadow, translucency).
            output_format:
              type: string
              enum:
                - png
                - jpeg
              default: png
              description: >-
                Format of the base image. Layers are always PNG with
                transparency.
            enable_safety_checker:
              type: boolean
              default: true
              description: Content safety check.
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1794470400-abcd1234
              description: Unique task identifier for status tracking
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              example: not_started
              description: >-
                Task status. Always `not_started` right after submission. Use
                [Query Task Status](/api-manual/task-management/status) or
                `callback_url` to get later states.


                - `not_started`: Queued, waiting to be processed

                - `running`: Being generated

                - `finished`: Completed; results are in `files` or `output`

                - `failed`: Failed; details are in `error_message`
            created_time:
              type: string
              format: date-time
              example: '2026-11-12T10:30:00'
              description: ISO 8601 timestamp when the task was created
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            Business status code. `200` means success; any other value means the
            request failed. Always check this field: some validation errors
            return HTTP 200 with `code: 400` in the body.


            - `200`: Success

            - `400`: Invalid request parameters

            - `401`: Missing or invalid API key

            - `402`: Insufficient credits

            - `403`: Permission denied

            - `404`: Resource not found

            - `408`: Request timeout

            - `429`: Rate limit exceeded

            - `500`: Internal server error

            - `502`: Upstream service error

            - `503`: Service unavailable


            See [Error Codes](/api-manual/error-codes) for details.
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API endpoints require Bearer Token authentication.


        Create an API key: sign in to PoYo, open **Dashboard → API Key** at
        [poyo.ai/dashboard/api-key](https://poyo.ai/dashboard/api-key), and
        click to create a key.


        Add it to the request header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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