> ## 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

> The Seedream 5.5 API generates an image from a prompt or edits up to 10 reference images. It supports 1K, 1.5K, and 2K output, eight aspect ratios, and transparent PNG backgrounds.

> [!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` to create product shots, posters, stickers, and other images from a prompt, or to edit and combine up to 10 reference images with the same model ID. Seedream 5.5 is ByteDance Seed's image creation model, released on November 9, 2026. It keeps unedited regions stable across repeated edits and outputs native transparent PNGs.

To split an image into a base image and transparent layers, use [Seedream 5.5 Layer Decomposition](https://docs.poyo.ai/api-manual/image-series/seedream-5-5-layerize.md).

## Models

* **seedream-5.5** — Text-to-image when `image_urls` is omitted; image editing with 1 to 10 reference images when `image_urls` is provided

## Features

* Text-to-image generation from prompts of 5 to 5,000 characters.
* Image editing and multi-reference composition with up to 10 reference images.
* Consistent multi-round editing: pass the previous result as the next reference image and the regions you leave out of the prompt stay the same.
* Native transparent output: set `background` to `transparent` for an RGBA PNG with full or partial transparency, from a prompt or from reference images.
* Eight aspect ratios at `1K`, `1.5K`, or `2K` (up to 3136×1344 at `21:9`).
* PNG or JPEG output.

## Input modes

* **Text-to-image** — Omit `image_urls`. `size` defaults to `1:1`.
* **Image editing** — Pass 1 to 10 URLs in `image_urls`. Refer to the images in the prompt by their order (image 1, image 2, and so on). `size` defaults to `auto`, which follows the reference images.

## Required parameters

* `prompt` (string): Description of the image or the requested edit, 5–5,000 characters. For an edit, say what changes and what stays the same.

## Optional parameters

* `image_urls` (array of strings): 1 to 10 publicly accessible HTTP(S) reference image URLs (JPEG, PNG, or WEBP, up to 10 MB each). Selects image editing mode.
* `size` (string): `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, or `auto`. Defaults to `1:1` for text-to-image and `auto` for image editing. `auto` applies to image editing. See [Size](#size).
* `resolution` (string): `1K`, `1.5K`, or `2K`. Default is `2K`. Sets the pixel tier for the selected `size`.
* `background` (string): `auto`, `transparent`, or `opaque`. Default is `auto`, where the prompt and output format decide the background. `transparent` returns an RGBA image with an alpha channel and needs `output_format` `png`. `opaque` returns an RGB image.
* `output_format` (string): `png` or `jpeg`. Default is `png`.
* `enable_safety_checker` (boolean): Content safety check. Default is `true`.

## Size

Each aspect ratio maps to fixed pixel dimensions at the selected `resolution`:

| `size` | `1K` | `1.5K` | `2K` |
| - | - | - | - |
| `1:1` | 1024×1024 | 1536×1536 | 2048×2048 |
| `4:3` | 1152×864 | 1792×1344 | 2368×1776 |
| `3:4` | 864×1152 | 1344×1792 | 1776×2368 |
| `16:9` | 1424×800 | 2048×1152 | 2816×1584 |
| `9:16` | 800×1424 | 1152×2048 | 1584×2816 |
| `3:2` | 1248×832 | 1872×1248 | 2496×1664 |
| `2:3` | 832×1248 | 1248×1872 | 1664×2496 |
| `21:9` | 1568×672 | 2352×1008 | 3136×1344 |

* `auto` (image editing): The output follows the reference images at about the pixel area of the selected `resolution`.

## Examples

### Text To Image

A 2K 16:9 product shot (2816×1584):

```json theme={"dark"}
{
  "model": "seedream-5.5",
  "input": {
    "prompt": "A ceramic pour-over coffee set on a walnut counter, soft morning window light, steam rising from the cup, minimalist product photography",
    "size": "16:9",
    "resolution": "2K"
  }
}
```

### Multi-Reference Edit

Combine two reference images, referring to each one by its position in `image_urls`:

```json theme={"dark"}
{
  "model": "seedream-5.5",
  "input": {
    "prompt": "Put the handbag from image 2 on the wooden table in image 1. Keep the lighting, background, and camera angle of image 1 unchanged.",
    "image_urls": [
      "https://example.com/living-room.png",
      "https://example.com/handbag.png"
    ],
    "resolution": "2K"
  }
}
```

### Transparent PNG

A sticker on a transparent background:

```json theme={"dark"}
{
  "model": "seedream-5.5",
  "input": {
    "prompt": "A red paper lantern with golden tassels, flat illustration sticker, isolated subject on a transparent background",
    "size": "1:1",
    "resolution": "1K",
    "background": "transparent",
    "output_format": "png"
  }
}
```

## Notes

* Each request generates one image.
* Pass `image_urls` as an array, including for a single image.
* For multi-round editing, use the previous result as the next reference image and keep `background` at `opaque` or `auto` until the final transparent step.
* A request usually finishes in about 20 to 35 seconds.


## OpenAPI

````yaml api-manual/image-series/seedream-5-5.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: PoYo AI - Seedream 5.5 API
  description: >-
    The Seedream 5.5 API generates an image from a prompt or edits up to 10
    reference images. It supports 1K, 1.5K, and 2K output, eight aspect ratios,
    and transparent PNG backgrounds.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Seedream 5.5
      summary: Submit Seedream 5.5 Task
      description: >-
        Seedream 5.5 text-to-image generation and image editing with up to 10
        reference images.
      operationId: submitSeedream55Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-image:
                summary: Text To Image
                value:
                  model: seedream-5.5
                  input:
                    prompt: >-
                      A ceramic pour-over coffee set on a walnut counter, soft
                      morning window light, steam rising from the cup,
                      minimalist product photography
                    size: '16:9'
                    resolution: 2K
              multi-reference-edit:
                summary: Multi-Reference Edit
                value:
                  model: seedream-5.5
                  input:
                    prompt: >-
                      Put the handbag from image 2 on the wooden table in image
                      1. Keep the lighting, background, and camera angle of
                      image 1 unchanged.
                    image_urls:
                      - https://example.com/living-room.png
                      - https://example.com/handbag.png
                    resolution: 2K
              transparent-png:
                summary: Transparent PNG
                value:
                  model: seedream-5.5
                  input:
                    prompt: >-
                      A red paper lantern with golden tassels, flat illustration
                      sticker, isolated subject on a transparent background
                    size: '1:1'
                    resolution: 1K
                    background: transparent
                    output_format: png
      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
          description: >-
            Seedream 5.5 model identifier. Omit image_urls for text-to-image;
            pass 1–10 image_urls for image editing.
        callback_url:
          type: string
          format: uri
          description: Optional webhook URL for task completion or failure.
        input:
          type: object
          additionalProperties: false
          required:
            - prompt
          description: >-
            Generate one image. With image_urls, edit or combine the reference
            images.
          properties:
            prompt:
              type: string
              minLength: 5
              maxLength: 5000
              description: >-
                Prompt describing the image or the requested edit, 5–5000
                characters. For an edit, say what changes and what stays the
                same, and refer to reference images by their order (image 1,
                image 2, and so on).
            image_urls:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: string
                format: uri
              description: >-
                Optional 1–10 reference image URLs. Passing this field selects
                image editing. Pass it as an array, including for a single
                image. Each URL must be a publicly accessible HTTP or HTTPS URL
                pointing to a JPEG, PNG, or WEBP image of up to 10 MB.
              example:
                - https://example.com/living-room.png
                - https://example.com/handbag.png
            size:
              type: string
              enum:
                - '1:1'
                - '4:3'
                - '3:4'
                - '16:9'
                - '9:16'
                - '3:2'
                - '2:3'
                - '21:9'
                - auto
              description: >-
                Aspect ratio or auto. Aspect ratios: 1:1, 4:3, 3:4, 16:9, 9:16,
                3:2, 2:3, 21:9; their pixel size comes from resolution. auto
                applies to image editing and follows the reference images at
                about the pixel area of the selected resolution. Defaults to 1:1
                for text-to-image and auto for image editing.
              example: '16:9'
            resolution:
              type: string
              enum:
                - 1K
                - 1.5K
                - 2K
              default: 2K
              description: >-
                Pixel tier for the selected size. 1K: 1:1 1024x1024, 4:3
                1152x864, 3:4 864x1152, 16:9 1424x800, 9:16 800x1424, 3:2
                1248x832, 2:3 832x1248, 21:9 1568x672. 1.5K: 1:1 1536x1536, 4:3
                1792x1344, 3:4 1344x1792, 16:9 2048x1152, 9:16 1152x2048, 3:2
                1872x1248, 2:3 1248x1872, 21:9 2352x1008. 2K: 1:1 2048x2048, 4:3
                2368x1776, 3:4 1776x2368, 16:9 2816x1584, 9:16 1584x2816, 3:2
                2496x1664, 2:3 1664x2496, 21:9 3136x1344.
            background:
              type: string
              enum:
                - auto
                - transparent
                - opaque
              default: auto
              description: >-
                Background of the output image. auto lets the prompt and output
                format decide. transparent returns an RGBA image with an alpha
                channel (full or partial transparency) and needs output_format
                png. opaque returns an RGB image.
            output_format:
              type: string
              enum:
                - png
                - jpeg
              default: png
              description: Output image format.
            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.