A set designer seen from behind carries a mid-century wooden armchair onto a bare photo studio stage, a lamp, a rug and a side table waiting along the wall in soft daylight.

Seedream 5.5 Layers API: access, pricing, code

Summary

Runway Dev gives you the official Seedream 5.5 Layers API from ByteDance.

Seedream 5.5 Layers splits one image into a base image and a set of transparent PNG layers, one per object.

The base image is the scene with those objects lifted out and the space behind them filled in, and each layer comes with its position and stacking order.

This page covers access, pricing, what a request returns, how to choose the layers, how to put them back together and code.

What is Seedream 5.5 Layers?

Seedream 5.5 Layers is the layer decomposition mode of Seedream 5.5, ByteDance’s image generation and editing model, released in November 2026. It takes one PNG or JPEG image and returns it as separate, editable pieces: a base image and a transparent PNG for each element it finds, such as a piece of furniture, a product, a plant or a frame on a wall.

Seedream 5.5 Layers is built for work that starts from a finished picture and needs to change part of it: move or remove an object, swap a product, restyle a room around the same furniture or hand a design team a layered file instead of a flat one. It splits the image on its own, or follows a prompt that names the elements to separate.

The source image: a mid-century kitchen with dark green tiles, walnut cabinets, an island with two bar stools, a refrigerator, open shelves and warm light rays The base image Seedream 5.5 Layers returned: the same room empty, green tile wall, concrete ceiling and floor, with every cabinet, appliance and object removed

The pair above is one request with no prompt: drag the divider to compare the source image with the base image the task returned, the room with every object it separated taken out.

What are the ways to use Seedream 5.5 Layers on Runway Dev?

You can use Seedream 5.5 Layers on Runway Dev three ways, all from one account:

Way in Best for What you need
Playground Splitting an image, then copying the request as code A Runway Dev account
API and SDKs Calling Seedream 5.5 Layers from your own code An API key, plus the Node or Python SDK if you want one
Coding agent Having Claude Code, Codex or Cursor build the API integration into your product, tool or pipeline The Runway Dev MCP and skills, and an API key for live calls

How do you get API access to Seedream 5.5 Layers?

You get API access to Seedream 5.5 Layers with a Runway Dev account and an API key:

  1. Create an account at https://dev.runway.com.
  2. Create an API key in your project’s dashboard.
  3. Add credits to your project’s balance.
  4. Store the key in your environment as RUNWAYML_API_SECRET.
  5. Send a request with "model": "seedream5.5_layers", one image in referenceImages and the X-Runway-Version header to POST /v1/text_to_image. The code below is ready to run.

How much does the Seedream 5.5 Layers API cost?

The Seedream 5.5 Layers API on Runway Dev is billed per image it returns, counting the base image and each layer: 2 credits ($0.02) per image at 1K or 2 credits ($0.02) per image at 1.5K, and 4 credits ($0.04) per image at 2K or with auto.

Option Credits USD
auto 4 credits per image $0.04 per image
1K 2 credits per image $0.02 per image
1.5K 2 credits per image $0.02 per image
2K 4 credits per image $0.04 per image
  • The source image, once per request: +0.8 credits ($0.008).
  • Billed for the base image and each layer returned.
  • Charged up front for the image cap you set, then refunded for any not returned.
  • Each request is rounded up to a whole credit.

Prices current as of November 18, 2026. 1 credit = $0.01.

How the billing works:

  • You pay for the images the task returns. A split into a base image and eight layers is billed for nine images, plus the charge for the source image listed under the table.
  • Credits are reserved up front for maxImages, then settled. A task holds credits for the most images it may return, and the images it doesn’t return are refunded when it finishes. A lower maxImages reserves less.
  • resolution sets the rate. auto, the default, sizes the output from your image and bills at the largest size’s rate. Send a smaller resolution for the lower rate.
  • A task that fails input moderation (SAFETY.INPUT.*) is still charged. See task failures for what each failure means.

Every rate is also listed in the docs pricing guide and on Runway Dev pricing.

What does the Seedream 5.5 Layers API return?

A Seedream 5.5 Layers task returns a base image and a set of layers, all as separate files. The base image is the scene with the separated objects removed and the area behind them filled in. Each layer is one object as a PNG with a transparent background, cropped to that object.

Here are the layers from the kitchen above, laid on a checkerboard that marks the transparent pixels:

Nineteen transparent layers on a checkerboard: a framed print, a rug, two bar stools, a bowl, the kitchen island, a vase of branches, a faucet, bottles, the range, a dish, a framed photo, a table lamp, a lower cabinet, the open shelves with their dishes, a door panel, a drawer front, the refrigerator and a potted plant

The completed task carries the files in two fields:

  • output lists a URL for every image, the base image included.
  • layers describes the same images, in the same order. Each entry has the image’s uri, a name, a zIndex and, for a layer, a boundingBox.
{
  "status": "SUCCEEDED",
  "output": ["https://…/layer-19.png", "…", "https://…/base.png"],
  "layers": [
    {
      "uri": "https://…/layer-19.png",
      "name": "Layer 19",
      "zIndex": 19,
      "boundingBox": {
        "absolute": [2274, 430, 2530, 695],
        "normalized": [888, 299, 988, 483]
      }
    },
    { "uri": "https://…/base.png", "name": "Base image", "zIndex": 0 }
  ]
}

What each field tells you:

  • zIndex is the stacking order. The base image is 0, and a higher number sits in front. Sort by zIndex rather than by position in the list: the base image can come last.
  • boundingBox.absolute places the layer in pixels of the base image, as left, top, right and bottom edges. boundingBox.normalized gives the same box in thousandths of the image’s width and height, for a canvas of any size.
  • name labels each image. With no prompt, layers are numbered. With a prompt, each one is named after what it holds, such as “Stainless steel double-door refrigerator”.
  • The base image follows outputFormat, PNG by default or JPEG. Layers are always PNG, so their transparency survives.

The refrigerator layer as the API returned it keeps its alpha channel, so you can open it in any editor and check the transparency yourself.

What inputs does Seedream 5.5 Layers accept?

Seedream 5.5 Layers accepts one image in referenceImages and an optional prompt, on POST /v1/text_to_image. The image is the picture to split, and it has to be a PNG or a JPEG within the size and shape limits in the layer input requirements.

POST /v1/text_to_image

Field Accepts
model (required) seedream5.5_layers
referenceImages (required) A list of up to 1 images
resolution One of auto, 1k, 1.5k or 2k
outputFormat One of png or jpeg
maxImages Whole number from 2 to 100
promptText Text, 1 to 4,000 characters

Images go in as an HTTPS URL, a runway:// URI from an upload or a data URI; inputs lists sizes and formats. Each table shows what a field accepts on its own. Rules that combine fields are checked when the task is submitted, and the API reference has them in full.

What each optional field changes:

  • promptText names the elements to separate. Left out, the model decides for itself. The next section shows the difference.
  • maxImages caps how many images the task returns, the base image included, and with it the credits reserved up front.
  • resolution sets the output size. auto, the default, sizes it from your image, and the inputs table lists the other values.
  • outputFormat sets the base image’s format: png, the default, or jpeg.

How do you choose which elements become layers with the Seedream 5.5 Layers API?

You choose the elements that become layers on Seedream 5.5 Layers by naming them in promptText. With no prompt, the model separates every element it finds, as in the kitchen above. With a prompt, it separates the ones you name and leaves the rest in the base image, which keeps the task smaller and cheaper. Set maxImages to the number of layers you expect plus the base image, so the task reserves only what it needs.

This request separates only the stools and the refrigerator from the same kitchen:

{
  "model": "seedream5.5_layers",
  "referenceImages": [
    {
      "uri": "https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-layers-api/kitchen-source-eddc18e9.jpg"
    }
  ],
  "promptText": "Separate the two bar stools and the refrigerator into their own layers",
  "maxImages": 4
}

Three transparent layers on a checkerboard, the right bar stool, the left bar stool and the stainless steel refrigerator, then the base image: the kitchen with the stools gone and wood cabinets where the refrigerator stood

How do you put Seedream 5.5 Layers back together?

You put Seedream 5.5 Layers back together by drawing the base image first, then each layer in rising zIndex order, scaled to fit its boundingBox.absolute and placed at its top-left corner. Each layer file is cropped to its object and returned at its own size, so resize it to the box rather than drawing it at its native size. Drawn that way, every layer lands where it was in the source image.

Leave a layer out, move its box or swap its file, and you get an edit with the rest of the picture untouched. Here, every layer of the kitchen went back on its base image at its box, except the two stools:

The kitchen rebuilt from its base image and layers, identical to the source except that the two bar stools are gone and the island stands alone

How do you use the Seedream 5.5 Layers API?

You use the Seedream 5.5 Layers API by sending seedream5.5_layers as the model to POST /v1/text_to_image with the image to split in referenceImages. This example request, in curl, Node and Python, splits the kitchen above with no prompt, which is the request that returned its layers:

curl

curl -X POST https://api.dev.runwayml.com/v1/text_to_image \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream5.5_layers",
    "referenceImages": [
      {
        "uri": "https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-layers-api/kitchen-source-eddc18e9.jpg"
      }
    ]
  }'

# The response carries the task id. Poll the task until it finishes:
curl https://api.dev.runwayml.com/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06"

Node.js

import RunwayML, { TaskFailedError } from '@runwayml/sdk';

// Reads your API key from RUNWAYML_API_SECRET.
const client = new RunwayML();

try {
  const task = await client.textToImage
    .create({
      model: 'seedream5.5_layers',
      referenceImages: [
        {
          uri: 'https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-layers-api/kitchen-source-eddc18e9.jpg',
        },
      ],
    })
    .waitForTaskOutput();
  console.log(task.output);
} catch (error) {
  if (error instanceof TaskFailedError) {
    console.error(error.taskDetails);
  } else {
    throw error;
  }
}

Python

from runwayml import RunwayML, TaskFailedError

# Reads your API key from RUNWAYML_API_SECRET.
client = RunwayML()

try:
    task = client.text_to_image.create(
        model="seedream5.5_layers",
        reference_images=[
            {
                "uri": "https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-layers-api/kitchen-source-eddc18e9.jpg",
            },
        ],
    ).wait_for_task_output()
    print(task.output)
except TaskFailedError as error:
    print(error.task_details)

Generation is asynchronous:

  • The create request returns a task ID right away, and the split runs in the background. A layer split takes longer than a single image, so poll with backoff.
  • Poll GET /v1/tasks/{id} with backoff until the status is SUCCEEDED, FAILED or CANCELLED. THROTTLED means the task is waiting in a queue, not rejected.
  • A SUCCEEDED task carries output and layers, as shown above. The URLs are temporary, so download the files you keep. See outputs.
  • The SDKs poll for you. waitForTaskOutput() and wait_for_task_output() raise TaskFailedError with the task’s details when it fails.

Why does a Seedream 5.5 Layers API request fail?

A call to Seedream 5.5 Layers fails in one of two places: with a validation error when you create the task, or as a task that ends with a failure code. The common ones:

  • A validation error on referenceImages: the request sent no image or more than one. Seedream 5.5 Layers splits exactly one image per request.
  • A rejected source image: it is a WebP, HEIC or another format, or outside the size or shape limits. Convert it to PNG or JPEG and check it against the layer input requirements.
  • A request rejected for credits: the balance doesn’t cover the reservation for maxImages. Add credits, or send a lower maxImages.
  • A validation error naming an unrecognized key: the request carries a field Seedream 5.5 Layers doesn’t take, such as ratio, outputCount or background from Seedream 5.5. Use resolution and maxImages instead.
  • SAFETY.INPUT.*: content moderation rejected the image or the prompt. The task is charged and shouldn’t be retried as is: change the inputs first.
  • THIRD_PARTY.UNAVAILABLE: the model’s provider didn’t return the layers, because of an outage or load. Wait, then retry.
  • An output link that stopped working: output URLs expire. Download the base image and layers when the task succeeds.

What does Runway Dev add when you call Seedream 5.5 Layers?

Runway Dev serves Seedream 5.5 Layers next to Runway’s own models and other labs’ models, behind one API key and one credit balance: you build with a single key and pay a single bill, instead of an account, a key and an invoice per lab. The same key calls Seedream 5.5, so one integration can generate an image and split it into layers.

A coding agent can do the Seedream 5.5 Layers integration for you on Runway Dev, end to end. Connect the Runway Dev MCP and the agent works from your live account: the models your project can call with their current prices and input limits, your credit balance and the record behind any task. It writes the integration against what the API accepts today, including the code that places each layer at its box, and when a task fails it looks up the reason and fixes it. The Runway Dev skills show the agent how to integrate with the official SDKs and how to build with models, Model Routers, Recipes and Workflows.

FAQ

How do I get API access to Seedream 5.5 Layers?

Create a Runway Dev account at dev.runway.com, make an API key and add credits. Then send seedream5.5_layers as the model to POST /v1/text_to_image with one image in referenceImages. To have a coding agent write the integration instead, connect the Runway Dev MCP and install the Runway Dev skills.

What does each Seedream 5.5 Layers resolution cost?

On Runway Dev, Seedream 5.5 Layers costs 2 credits ($0.02) per image at 1K or 2 credits ($0.02) per image at 1.5K, and 4 credits ($0.04) per image at 2K, the rate auto bills at, for the base image and for each layer. The source image adds the charge listed in the price table, and credits for maxImages are reserved up front, then refunded for images not returned. Prices are current as of November 18, 2026.

Is the Seedream 5.5 Layers API on Runway Dev the official model?

Runway Dev’s Seedream 5.5 Layers API runs the official Seedream 5.5 model from ByteDance in its layer decomposition mode. You call it with your Runway Dev API key and the model ID seedream5.5_layers, like every other model on Runway Dev.

Is there an API that splits an image into layers?

Seedream 5.5 Layers on Runway Dev splits one image into a base image and transparent PNG layers through an API. Send the image to POST /v1/text_to_image with seedream5.5_layers as the model, and the completed task lists every layer with its position and stacking order.

How do I get transparent PNG layers from a flat image?

Send the flat image to Seedream 5.5 Layers. Every layer it returns is a PNG with an alpha channel, cropped to one object, and the base image holds the scene behind them. The layers field gives each PNG’s box, so you can place it back on the base image exactly.

How many layers does Seedream 5.5 Layers return?

Seedream 5.5 Layers returns as many layers as it finds elements, up to maxImages minus the base image. A busy scene with no prompt can return many, like the nineteen layers of the kitchen on this page, and a prompt that names a few elements returns those.

Can Seedream 5.5 Layers export a PSD file?

Seedream 5.5 Layers returns each layer as its own PNG with its position and stacking order, rather than one PSD. Those three facts are what a layered file holds, so your code or a coding agent can assemble them into a PSD, a Figma file or a canvas in your app.

What is the Seedream 5.5 Layers model ID on Runway Dev?

The model ID is seedream5.5_layers, sent as model to POST /v1/text_to_image. Seedream 5.5, the generation model it comes from, is seedream5.5 on the same endpoint.

Can I use Seedream 5.5 Layers without writing code?

You can use Seedream 5.5 Layers on Runway Dev without writing code yourself. The playground splits an image from a form and gives the request back as code, and a coding agent connected to the Runway Dev MCP writes the integration for you.

Does the same Runway Dev API key work for Seedream 5.5 Layers and other models?

One Runway Dev API key calls Seedream 5.5 Layers, Seedream 5.5 and every other model your project can use, Runway’s own and other labs’, with the same SDKs, task flow and credit balance. Switching models means changing the model field.

Why did my call to Seedream 5.5 Layers fail with a SAFETY.INPUT code?

A SAFETY.INPUT.* failure means content moderation rejected the image or the prompt you sent; the suffix hints at which one but may not match. The task is charged and shouldn’t be retried as is, so change the image or prompt before you send it again.

Start building on Runway Dev