# Seedream 5.5 API: access, pricing and code

> Get the official Seedream 5.5 API from ByteDance on Runway Dev: image generation, reference editing, transparent PNGs, price per image and code.

Author: Alex Breg · Published: 2026-11-17 · Updated: 2026-11-17 · Source: https://dev.runway.com/learn/seedream-5-5-api

## Summary

Runway Dev gives you the official Seedream 5.5 API from ByteDance.\
\
Seedream 5.5 creates images from a prompt and edits them from reference images, with precise changes that leave the rest of the picture as it was.\
\
It can return a PNG with a transparent background, ready for product cutouts, stickers and overlays.\
\
This page covers access, pricing, inputs, image editing, transparent backgrounds and code, and how your coding agent can build the integration for you.

## What is Seedream 5.5?

Seedream 5.5 is [ByteDance's image generation and editing model](https://seed.bytedance.com/en/seedream5_5), released in November 2026. It takes a text prompt of up to 4,000 characters and up to 10 images as references, and returns images in eight aspect ratios at three sizes, or in a shape the model picks.

Seedream 5.5 makes targeted edits: change a color, swap an object or move a product into a new scene, and the parts of the image you didn't ask about stay put. It renders natural light and fine materials for photoreal work, and it writes transparent and semi-transparent backgrounds natively, so a cutout comes straight from the model with no background-removal step.

![A flower seller seen from behind ties a bunch of ranunculus at a street market stall in the early morning, buckets of ranunculus and tulips around her on wet cobblestones](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/market-hero-74af57f0.jpg 'One request, prompt only, on Seedream 5.5: 2 credits ($0.02) per image at 1.5K.')

```text
A documentary photograph of a flower seller arranging buckets of ranunculus and tulips at a street market stall in the early morning, seen from behind and to the side, her hands tying a bunch with string, wet cobblestones, soft overcast light, natural color, 35mm film look.
```

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

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

| Way in                                                                                                                 | Best for                                                                                          | What you need                                                   |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [Playground](https://dev.runway.com/endpoints/text_to_image?modelId=seedream5.5)                                       | Trying a prompt, then copying the request as code                                                 | A Runway Dev account                                            |
| [API](https://docs.dev.runwayml.com/guides/using-the-api/) and [SDKs](https://docs.dev.runwayml.com/api-details/sdks/) | Calling Seedream 5.5 from your own code                                                           | An API key, plus the Node or Python SDK if you want one         |
| [Coding agent](https://dev.runway.com/learn/build-with-your-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    |
| [Workflows](https://dev.runway.com/workflows)                                                                                                | Seedream 5.5 as one step with other models, run with one API call                                 | A workflow built in the Runway app and published as an endpoint |

Seedream 5.5 is also available in [Model Router](https://dev.runway.com/model-routers), a saved config you send with the request instead of a model ID. You set what to optimize for (cost, quality or latency), a maximum cost per generation and the models allowed, and the router picks one for each request sent to `POST /v1/generate/image`.

## How do you get API access to Seedream 5.5?

You get API access to Seedream 5.5 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"` 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 API cost?

The Seedream 5.5 API on Runway Dev is billed per image it returns: 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.

| Resolution | Credits | USD |
| --- | --- | --- |
| 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 |

- Each reference image, per generated image: +0.8 credits ($0.008).
- 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 each image returned.** `outputCount` multiplies the charge, so a request for several images is billed for each one.
- **`ratio` sets the rate.** Each value belongs to one of the sizes, and the `auto_` values bill at the rate of the size they name.
- **Each reference image adds a charge per generated image**, listed under the table, and the total is rounded up to a whole credit per request.
- **A transparent background costs the same** as an opaque image of the same size.
- **A task that fails input moderation (`SAFETY.INPUT.*`) is still charged.** See [task failures](https://docs.dev.runwayml.com/errors/task-failures) for what each failure means.

Every rate is also listed in the [docs pricing guide](https://docs.dev.runwayml.com/guides/pricing/) and on [Runway Dev pricing](https://dev.runway.com/pricing).

## What inputs does Seedream 5.5 accept?

Seedream 5.5 accepts a prompt of up to 4,000 characters and up to 10 images as references, all on `POST /v1/text_to_image`. What the model does depends on what you send.

With a prompt alone, Seedream 5.5 creates a new image, as in the flower market above.

With reference images, the prompt says what to do with them: edit a photo, combine several objects in one scene or place a product somewhere new. The model reads the references in the order you send them, so the prompt names each one by its place in the list, Figure 1, Figure 2 and so on. Each reference goes in `referenceImages` as an object with the image in `uri`:

```json
"referenceImages": [{ "uri": "https://example.com/tote.jpg" }]
```

![A natural canvas tote bag with a printed green leaf standing on a white table](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/tote-product-a9173925.jpg 'Figure 1')

![A person seen from behind walks through a farmers market with the same canvas tote on their shoulder, the green leaf print visible, crates of tomatoes and greens on both sides](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/tote-market-48651a06.jpg 'One reference image on Seedream 5.5: the bag keeps its shape, canvas and leaf print in a new scene.')

```text
The tote bag from Figure 1 carried on the shoulder of a person walking through a farmers market on a sunny morning, seen from behind, the printed green leaf visible on the bag, crates of vegetables on both sides, natural color, 35mm documentary photograph.
```

Here is every field:

### `POST /v1/text_to_image`

| Field | Accepts |
| --- | --- |
| `model` (required) | `seedream5.5` |
| `promptText` (required) | Text, 1 to 4,000 characters |
| `ratio` (required) | One of `1024:1024`, `1152:864`, `864:1152`, `1424:800`, `800:1424`, `1248:832`, `832:1248`, `1568:672`, `1536:1536`, `1792:1344`, `1344:1792`, `2048:1152`, `1152:2048`, `1872:1248`, `1248:1872`, `2352:1008`, `2048:2048`, `2368:1776`, `1776:2368`, `2816:1584`, `1584:2816`, `2496:1664`, `1664:2496`, `3136:1344`, `auto_1k`, `auto_1.5k` or `auto_2k` |
| `outputFormat` | One of `png` or `jpeg` |
| `background` | One of `transparent` or `opaque` |
| `referenceImages` | A list of up to 10 images |
| `outputCount` | Whole number from 1 to 4 |

Images go in as an HTTPS URL, a `runway://` URI from an [upload](https://docs.dev.runwayml.com/assets/uploads) or a data URI; [inputs](https://docs.dev.runwayml.com/assets/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](https://docs.dev.runwayml.com/api/) has them in full.

A few more rules change what you send:

- **`ratio` is required, and it sets the size, the shape and the price at once.** Each value is a width and height in pixels at 1K, 1.5K and 2K, and the `auto_` values let the model pick the shape at one of those sizes.
- **`outputCount` returns several images from one request**, and each one is billed.
- **`outputFormat` sets the file the task returns**: `png`, the default, or `jpeg`.
- **`background` decides what fills the space around the subject**: `transparent` or `opaque`. Left out, the model decides from the prompt. The next section shows it.

## How do you edit images with the Seedream 5.5 API?

You edit an image with the Seedream 5.5 API by sending it as a reference on `POST /v1/text_to_image` and describing the change in `promptText`. There is no separate edit endpoint. The prompt names the image as Figure 1, says what changes and lists what has to stay, and Seedream 5.5 leaves the parts you list as they were.

A common case is colorway variants for a store catalog. A shop photographs a product once and needs the same shot in every color it sells, with the same light, props and framing, so shoppers compare only the color. Each colorway is one request with the original photo as its reference:

```json
{
  "model": "seedream5.5",
  "ratio": "1536:1536",
  "referenceImages": [
    {
      "uri": "https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/tote-product-a9173925.jpg"
    }
  ],
  "promptText": "Change the canvas of the tote bag in Figure 1 to deep navy blue and print the leaf in white. Keep the bag's shape, stitching, handles, the white table, the wall and the lighting exactly the same."
}
```

![Three versions of the same product photo side by side: the natural canvas tote with a green leaf, the same tote in navy with a white leaf and in terracotta with a cream leaf, with the table, the dried pampas grass and the light unchanged](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/tote-colorways-c41778b3.jpg 'Figure 1, then two colorways edited from it on Seedream 5.5: only the canvas and the print change.')

The terracotta version sends the same request with "terracotta orange" and "cream" in place of the navy and white. A few choices keep a set of variants consistent:

- **Send the same `ratio` as the source photo**, so the edit keeps its framing instead of recomposing the shot.
- **Send one request per colorway**, in parallel. `outputCount` returns several takes of the same prompt, not different colors.
- **Repeat the keep list in every prompt.** Naming the table, the wall and the light is what holds them in place from one variant to the next.
- **Each edit is billed as a new image plus the reference charge**, so a catalog of colorways costs one image and one reference per color.

## How do you generate images with a transparent background with the Seedream 5.5 API?

You generate an image with a transparent background on Seedream 5.5 by sending `"background": "transparent"` with the request. The model returns a PNG whose alpha channel is clear around the subject, so the image drops onto any color, photo or layout with no background-removal step. It works from a prompt alone or from reference images, and costs the same as an opaque image of the same size.

Say in the prompt what the subject is and that it stands alone ("a product cutout", "a sticker", "a logo on a transparent background"), as the request in the code below does. A transparent background needs the `png` output format, the default.

To pull apart an image you already have into several transparent pieces, one per object, use [Seedream 5.5 Layers](https://dev.runway.com/learn/seedream-5-5-layers-api) instead: it returns the scene behind the objects and each object as its own transparent PNG.

## How do you use the Seedream 5.5 API?

You use the Seedream 5.5 API by sending `seedream5.5` as the model to `POST /v1/text_to_image`. This example request, in curl, Node and Python, creates a square product cutout on a transparent background:

**curl**

```bash
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",
    "promptText": "A product cutout of a potted monstera plant in a matte terracotta pot, soft studio lighting, on a transparent background",
    "ratio": "1536:1536",
    "background": "transparent"
  }'

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

```javascript
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',
      promptText: 'A product cutout of a potted monstera plant in a matte terracotta pot, soft studio lighting, on a transparent background',
      ratio: '1536:1536',
      background: 'transparent',
    })
    .waitForTaskOutput();
  console.log(task.output);
} catch (error) {
  if (error instanceof TaskFailedError) {
    console.error(error.taskDetails);
  } else {
    throw error;
  }
}
```

**Python**

```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",
        prompt_text="A product cutout of a potted monstera plant in a matte terracotta pot, soft studio lighting, on a transparent background",
        ratio="1536:1536",
        background="transparent",
    ).wait_for_task_output()
    print(task.output)
except TaskFailedError as error:
    print(error.task_details)
```

![Checkerboard](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/plant-checkerboard-71dfb057.jpg 'The request above, as Seedream 5.5 returns it: drag the divider to see the same PNG over a checkerboard, which marks the transparent pixels, and over a blue page.') ![On a blue page](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/plant-on-blue-0653b796.jpg)

The [PNG as the API returned it](https://d3phaj0sisr2ct.cloudfront.net/devportal/learn/images/seedream-5-5-api/plant-transparent-0ccd06bb.png) keeps its alpha channel, so you can open it in any editor and check the transparency yourself.

Generation is asynchronous:

- **The create request returns a task ID right away**, and the image is made in the background.
- **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`**, a list with one URL per image. The URLs are temporary, so download the images you keep. See [outputs](https://docs.dev.runwayml.com/assets/outputs).
- **The SDKs poll for you.** `waitForTaskOutput()` and `wait_for_task_output()` raise `TaskFailedError` with the task's details when it fails.
- **To use your own rules instead of one fixed model**, send a [Model Router](https://dev.runway.com/learn/choosing-the-right-model)'s `configId` to `POST /v1/generate/image` in place of the model.

## Why does a Seedream 5.5 API request fail?

A call to Seedream 5.5 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:

- **`SAFETY.INPUT.*`**: content moderation rejected an input, the prompt or a reference image. The suffix hints at which one but may not match. The task is charged and shouldn't be retried as is: change the inputs first.
- **`SAFETY.OUTPUT.*`**: the generated image was rejected by moderation. Change the prompt or references before you try again.
- **`ASSET.INVALID`**: a reference image can't be used, for example because of its format or size. Check it against the [Seedream 5.5 input requirements](https://docs.dev.runwayml.com/assets/inputs#seedream-55-inputs) and fix it before retrying.
- **`THIRD_PARTY.UNAVAILABLE`**: the model's provider didn't return the image, because of an outage or load. Wait, then retry.
- **A validation error on `background`**: `transparent` was sent with `"outputFormat": "jpeg"`. Send `png`, or leave `outputFormat` out.
- **A validation error on `ratio`**: the field is missing, or the value isn't in this model's list, often because it came from another model. Take it from the inputs above.
- **A validation error naming an unrecognized key**: the request carries a field `POST /v1/text_to_image` doesn't take, such as `size` or `image` from ByteDance's own API. Use `ratio` and `referenceImages` instead.
- **An output link that stopped working**: output URLs expire. Download the image when the task succeeds.

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

Runway Dev serves Seedream 5.5 next to [Runway's own models and other labs' models](https://dev.runway.com/models/catalog), 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.

A coding agent can do the Seedream 5.5 integration for you on Runway Dev, end to end. Connect the [Runway Dev MCP](https://docs.dev.runwayml.com/guides/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, and when a task fails it looks up the reason and fixes it. The [Runway Dev skills](https://github.com/runwayml/skills) show the agent how to integrate with the official SDKs and how to build with models, Model Routers, Recipes and Workflows.

With [Workflows](https://dev.runway.com/workflows), Seedream 5.5 becomes one step of a larger pipeline: place a product in new scenes, pick the best take and animate it with a video model, then run the whole pipeline with a single API call. Workflows don't need to be built by a developer. A creative or marketing teammate builds and tests one visually in the [Runway app](https://app.runwayml.com/workflows) ([how Workflows work](https://help.runwayml.com/hc/en-us/articles/45763528999699-Introduction-to-Workflows)), then [publishes it as an endpoint](https://help.runwayml.com/hc/en-us/articles/50682960972947-Publishing-a-Workflow-as-an-Endpoint) that your code calls. When the team updates the workflow, your code keeps calling the same endpoint.

## FAQ

**How do I get API access to Seedream 5.5?**

Create a Runway Dev account at dev.runway.com, make an API key and add credits. Then send `seedream5.5` as the model to `POST /v1/text_to_image`. To have a coding agent write the integration instead, connect the Runway Dev MCP and install the Runway Dev skills: the agent builds it from your live account, with the prices and input limits your project has today.

**What does each Seedream 5.5 image size cost?**

On Runway Dev, Seedream 5.5 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. Each reference image adds a charge per generated image, and `outputCount` multiplies the total. Prices are current as of November 18, 2026.

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

Runway Dev's Seedream 5.5 API runs the official Seedream 5.5 model from ByteDance. You call it with your Runway Dev API key and the model ID `seedream5.5`, like every other model on Runway Dev.

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

The model ID is `seedream5.5`, sent as `model` to `POST /v1/text_to_image`. Its layer decomposition sibling, Seedream 5.5 Layers, is `seedream5.5_layers` on the same endpoint.

**Can Seedream 5.5 split an image into layers?**

Seedream 5.5 splits an image into layers through its sibling model, Seedream 5.5 Layers (`seedream5.5_layers`). Send one image and it returns the background as a base image and each object as its own transparent PNG, with each layer's position and stacking order. The [Seedream 5.5 Layers API page](https://dev.runway.com/learn/seedream-5-5-layers-api) covers it.

**What sizes and aspect ratios does Seedream 5.5 support?**

Seedream 5.5 returns images at 1K, 1.5K and 2K in square, portrait, landscape and wide shapes, and the `auto_` values let the model pick the shape at a size. Each `ratio` value is a width and height in pixels, and the inputs table on this page lists every one.

**Can I use Seedream 5.5 without writing code?**

You can use Seedream 5.5 on Runway Dev without writing code yourself. The playground sends a request from a form and gives it back as code, and a coding agent connected to the Runway Dev MCP writes the integration for you. A creative or marketing teammate can also build a workflow around Seedream 5.5 in the Runway app and publish it as an endpoint your app calls.

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

One Runway Dev API key calls 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, or the rules of a Model Router.

**Why did my call to Seedream 5.5 fail with SAFETY.INPUT.TEXT?**

`SAFETY.INPUT.TEXT` means content moderation rejected an input of your request; the suffix hints at the prompt but may not match. The task is charged and shouldn't be retried as is, so change the prompt or inputs before you send it again.

**Can I switch from Seedream 5.5 to another image model without changing my code?**

A Model Router lets you change models without touching your code. Send its `configId` to `POST /v1/generate/image`, and change the models it may use, its priority or its cost cap in the router.
