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

# Seedream 5.5 API for Image Generation and Layer Decomposition

> Single image generation, image editing, transparent PNG output, and layer decomposition with rich-text recognition.

Check the [APIXO model catalog](https://apixo.ai/models) for current availability.

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| POST | `/api/v1/generateTask/seedream-5-5` | Create a generation task |
| GET | `/api/v1/statusTask/seedream-5-5?taskId=...` | Query task status |

## Authentication

Use your APIXO API key with `Authorization: Bearer YOUR_API_KEY`. Send JSON requests to `https://api.apixo.ai` with `Content-Type: application/json`.

## Request Body

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "A ceramic cup on a transparent background",
    "resolution": "1.5k",
    "aspect_ratio": "auto",
    "background": "transparent"
  }
}
```

## Parameters

| Parameter | Type | Rules |
| - | - | - |
| `request_type` | string | `async` for polling or `callback` for webhook delivery. |
| `callback_url` | string | Required when `request_type` is `callback`. Use a public HTTPS URL. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md). |
| `input.mode` | string | `text-to-image`, `image-to-image`, or `layer-decomposition`. Default `text-to-image`. |
| `input.prompt` | string | Required for generation and editing. Optional for layer decomposition. |
| `input.image_urls` | string\[] | Required for image-to-image (1–10 URLs) and decomposition (exactly one URL). Text-to-image ignores this field. |
| `input.resolution` | string | Accepts `1k`, `1.5k`, or `2k` (uppercase `K` also works). Generation and editing also accept `3k` with a concrete aspect ratio. Decomposition accepts omission for automatic sizing. |
| `input.aspect_ratio` | string | `auto`, `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, or `21:9`. Use a concrete ratio for `3k`. Decomposition ignores this field and uses automatic aspect ratio. |
| `input.size` | string | Custom width and height for generation or editing, such as `2880x2880`, `2880X2880`, or `2880*2880`. If provided, it takes precedence over `resolution` and `aspect_ratio`; otherwise both are required. Total pixels must be 921,600–8,294,400 and the width-to-height ratio must be 1:16–16:1. Decomposition ignores this field. |
| `input.background` | string | `auto` (default), `transparent`, or `opaque`. Transparent output requires PNG. Decomposition ignores this field. |
| `input.output_format` | string | `png` (default) or `jpeg`. In decomposition this controls the base image format. Other layers are PNG. |
| `input.watermark` | boolean | Default `false`. |
| `input.prompt_optimize_mode` | string | Optional. The supported value is `standard`, also the default. |
| `input.max_images` | integer | For `layer-decomposition`, the maximum total outputs including the base image, 2–100. Default 30. Text-to-image and image-to-image ignore this field and return one image. |
| `input.text_recognition` | boolean | Decomposition only. Include rich-text recognition when available. Default `false`. |

## Example

Submit a layer-decomposition task with the following request body.

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "layer-decomposition",
    "image_urls": ["https://example.com/poster.png"],
    "resolution": "2k",
    "max_images": 10,
    "text_recognition": true
  }
}
```

## Response

Task creation returns `data.taskId`. Poll the status endpoint or use a webhook for the result. The following example shows a successful decomposition.

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_123",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://example.com/base.png\",\"https://example.com/title.png\"]}",
    "layerDecomposition": [
      {"role": "base", "url": "https://example.com/base.png", "size": "2048x2048", "output_format": "png", "z_index": 0, "background": "opaque"},
      {
        "role": "layer",
        "url": "https://example.com/title.png",
        "size": "800x160",
        "output_format": "png",
        "z_index": 1,
        "background": "transparent",
        "bounding_box": {"absolute": [120, 80, 920, 240]},
        "text_recognition": {
          "text": "Summer Sale",
          "lines": [
            {
              "bounding_box": {"absolute": [0, 0, 800, 160]},
              "runs": [{"text": "Summer Sale", "style": {"bold": true}}]
            }
          ]
        }
      }
    ]
  }
}
```

## Status Response Fields

| Field | Description |
| - | - |
| `taskId` | Task identifier. |
| `state` | `pending`, `processing`, `success`, or `failed`. |
| `resultJson` | JSON string containing `resultUrls` in result order. |
| `layerDecomposition` | Base image followed by the layers. Items may also include `name`, `description`, normalized bounding boxes, and text recognition when available. |
| `failCode`, `failMsg` | Failure code and message. |

## Error Codes

Requests can fail validation for missing inputs, out-of-range image dimensions, or incompatible format and background options. A failed task includes `failCode` and `failMsg`.

## Billing

The initial charge is `$0.034` per output for `1k` and `1.5k`, and `$0.045` for `2k`. Explicit sizes and `3k` with a concrete ratio use the requested pixel count. Decomposition initially charges for up to `max_images` outputs at the selected rate, or `$0.045` per output when resolution is omitted.

Final billing uses the actual width × height of each returned image, including the base image and each layer in decomposition. Any overpayment is refunded; the charge does not exceed the initial charge. Text recognition and prompt optimization have no separate fee.

| Actual pixels per output | Price per output |
| - | -: |
| Up to and including 2,610,000 | `$0.034` |
| Above 2,610,000 and up to 4,630,000 | `$0.045` |
| Above 4,630,000 | `$0.090` |

The input price is `$0.015` per image, including the first. The total request charge is rounded up to the next `$0.001`.

## MCP integration

The [model schema](https://apixo.ai/docs/models/schemas/image/seedream-5-5.json) declares `mcp.attachments` for `input.image_urls` and `mcp.result` for decoding image URLs from `resultJson.resultUrls`. See [MCP model contracts](https://apixo.ai/docs/guides/mcp-model-contracts.md).


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