Name: Seedream 5 Pro API: Text to Image and Image Layers
Brand: magicapi
SKU: api-magicapi-text-to-image-high-resolution-bytedance-seedream-5-pro
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Text-to-Image Generator API (ByteDance Seedream 5 Pro)

## Overview
Seedream 5 Pro is ByteDance's text-to-image and image editing model. Its developer describes it as its flagship model, generating sharp 1K and 2K images from text or up to 10 reference images.

The model has two modes:
- **Standard mode** (default): describe the image in `prompt` (up to 4000 characters) and optionally add 1 to 10 reference images in `image_input` for image-to-image generation.
- **Layer decomposition mode** (`layer_decomposition: true`): send exactly one image in `image_input` and the model splits it into a base image plus up to 16 element layers. The prompt is optional here: name the elements to split out, or leave it blank to detect all major elements.

The output is a list of image URLs.

## Features
- **Text to image**: prompts up to 4000 characters, including text to render in the image.
- **Reference images**: 1 to 10 images in `image_input` guide generation in standard mode.
- **Layer decomposition**: split one image into a base image plus up to 16 element layers.
- **Sizes**: `1K` or `2K` (default) in standard mode; layer decomposition also accepts `1.5K` and `auto`, which sizes the output from the input image.
- **Aspect ratios**: `match_input_image` (default), `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`. Ignored in layer decomposition mode.
- **Output format**: `png` (default) or `jpeg`. In layer decomposition mode this applies to the base image only; layers are always PNG.

## Use Cases
1. **Marketing and editorial images**: scenes, posters and banners at 2K from a detailed prompt.
2. **Images with text**: titles and labels rendered inside the image, as in the example.
3. **Reference-based generation**: new images that follow the subject or style of up to 10 reference images.
4. **Layered assets for editing**: split a flat image into separate element layers to rework in a design tool.

## Visual Examples
### Example Input
A long prompt describing a misty forest meadow at dawn with the words "Seedream 5 Pro" in pink embroidered lettering, `size` `2K`, `aspect_ratio` `match_input_image`, no reference images, PNG output.

```json
{
  "size": "2K",
  "prompt": "A tranquil forest meadow bathed in soft morning light, shot from a low angle beneath overhanging oak branches draped with pale lichen and moss. Dense, dark tree canopy frames the top of the frame, with hazy sunbeams (crepuscular rays) streaming diagonally through the misty woodland in the background, illuminating drifting particles of dust and pollen in the air. Below, a sunlit clearing of lush, dewy green grass and wild sedges stretches out, with a clump of bright, glossy iris-like leaves standing out in the left foreground. Muted, atmospheric color palette of deep forest greens, soft golden-white light, and diffused shadow. Documentary-style nature photography, shallow atmospheric depth, slightly desaturated and moody, evoking a quiet, magical early-morning stillness. Vertical portrait orientation. The words \"Seedream 5 Pro\" appear centered in the middle of the image, rendered in a pink embroidered thread texture \u2014 raised stitched lettering with visible thread grain, soft drop shadow, and a slightly frayed, tactile fabric-patch look, as if machine-embroidered onto the scene.",
  "image_input": [],
  "aspect_ratio": "match_input_image",
  "output_format": "png"
}
```

### Example Output
![Seedream 5 Pro output: a misty forest meadow in morning light with the words Seedream 5 Pro in pink embroidered lettering](https://blog.api.market/wp-content/uploads/2026/10/seedream-5-pro-output-k0m16hss-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | No | `""` | up to 4000 characters | Text prompt. In standard mode, describes the image to generate. In layer decomposition mode it is optional: describe which elements to split out, or leave blank to auto-detect all major elements. Maximum 4000 characters. |
| `image_input` | array of strings (URLs) | No | `[]` |  | Input image URLs. In standard mode, 1 to 10 reference images for image-to-image generation. In layer decomposition mode, exactly one image to decompose. |
| `layer_decomposition` | boolean | No | `false` |  | Split a single input image into a base image plus separate element layers (up to 16). Requires exactly one input image. |
| `size` | string | No | `2K` | `1K`, `1.5K`, `2K`, `auto` | Image resolution. Standard mode supports 1K and 2K. Layer decomposition mode supports 1K, 1.5K, 2K and auto; auto sizes the base image and layers from the input image. |
| `aspect_ratio` | string | No | `match_input_image` | `match_input_image`, `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9` | Image aspect ratio (ignored in layer decomposition mode). Use match_input_image to match the input image's aspect ratio. |
| `output_format` | string | No | `png` | `png`, `jpeg` | Output image format. In layer decomposition mode this only controls the base image; layers are always returned as PNG. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.029 per API unit.
- **1 API unit = 1 output image at the base rate**, multiplied by the factor for the mode and size:

| Mode and `size` | Factor | Price per image |
| --- | --- | --- |
| Standard, `1K` | 2 | $0.058 |
| Standard, `2K` (default) | 4 | $0.116 |
| Layer decomposition (`layer_decomposition: true`), any size | 2 | $0.058 |

- With the defaults (`size` `2K`, `layer_decomposition` `false`) each image costs $0.116. Any other combination is billed at factor 4 ($0.116 per image).
- Every image URL in `output` is billed as one image.
- **Example cost**: the example returned one 2K image in standard mode: 4 API units = **$0.116**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/text-to-image-high-resolution-bytedance-seedream-5-pro`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-image-high-resolution-bytedance-seedream-5-pro/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "bytedance/seedream-5-pro",
    "input": {
      "size": "2K",
      "prompt": "A tranquil forest meadow bathed in soft morning light, shot from a low angle beneath overhanging oak branches draped with pale lichen and moss. Dense, dark tree canopy frames the top of the frame, with hazy sunbeams (crepuscular rays) streaming diagonally through the misty woodland in the background, illuminating drifting particles of dust and pollen in the air. Below, a sunlit clearing of lush, dewy green grass and wild sedges stretches out, with a clump of bright, glossy iris-like leaves standing out in the left foreground. Muted, atmospheric color palette of deep forest greens, soft golden-white light, and diffused shadow. Documentary-style nature photography, shallow atmospheric depth, slightly desaturated and moody, evoking a quiet, magical early-morning stillness. Vertical portrait orientation. The words \"Seedream 5 Pro\" appear centered in the middle of the image, rendered in a pink embroidered thread texture \u2014 raised stitched lettering with visible thread grain, soft drop shadow, and a slightly frayed, tactile fabric-patch look, as if machine-embroidered onto the scene.",
      "image_input": [],
      "aspect_ratio": "match_input_image",
      "output_format": "png"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "k0m16hsst9rmt0d1c6rtbf461r",
  "version": "bytedance/seedream-5-pro",
  "status": "starting",
  "created_at": "2026-10-22T03:39:27.212Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-image-high-resolution-bytedance-seedream-5-pro/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "k0m16hsst9rmt0d1c6rtbf461r",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/seedream-5-pro-output-k0m16hss-api-market.jpg"
  ],
  "error": null,
  "created_at": "2026-10-22T03:39:27.212Z",
  "started_at": "2026-10-22T03:39:27.225Z",
  "completed_at": "2026-10-22T03:40:33.516Z"
}
```

`output` is a list of image URLs. The example returned one image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a `size` or `aspect_ratio` that is not in the list, or a `prompt` longer than 4000 characters.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.
## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-image-high-resolution-bytedance-seedream-5-pro";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "bytedance/seedream-5-pro", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
    "size": "2K",
    "prompt": "A tranquil forest meadow bathed in soft morning light, shot from a low angle beneath overhanging oak branches draped with pale lichen and moss. Dense, dark tree canopy frames the top of the frame, with hazy sunbeams (crepuscular rays) streaming diagonally through the misty woodland in the background, illuminating drifting particles of dust and pollen in the air. Below, a sunlit clearing of lush, dewy green grass and wild sedges stretches out, with a clump of bright, glossy iris-like leaves standing out in the left foreground. Muted, atmospheric color palette of deep forest greens, soft golden-white light, and diffused shadow. Documentary-style nature photography, shallow atmospheric depth, slightly desaturated and moody, evoking a quiet, magical early-morning stillness. Vertical portrait orientation. The words \"Seedream 5 Pro\" appear centered in the middle of the image, rendered in a pink embroidered thread texture \u2014 raised stitched lettering with visible thread grain, soft drop shadow, and a slightly frayed, tactile fabric-patch look, as if machine-embroidered onto the scene.",
    "image_input": [],
    "aspect_ratio": "match_input_image",
    "output_format": "png"
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-image-high-resolution-bytedance-seedream-5-pro"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "bytedance/seedream-5-pro", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


output = create_and_wait_for_prediction({
    "size": "2K",
    "prompt": "A tranquil forest meadow bathed in soft morning light, shot from a low angle beneath overhanging oak branches draped with pale lichen and moss. Dense, dark tree canopy frames the top of the frame, with hazy sunbeams (crepuscular rays) streaming diagonally through the misty woodland in the background, illuminating drifting particles of dust and pollen in the air. Below, a sunlit clearing of lush, dewy green grass and wild sedges stretches out, with a clump of bright, glossy iris-like leaves standing out in the left foreground. Muted, atmospheric color palette of deep forest greens, soft golden-white light, and diffused shadow. Documentary-style nature photography, shallow atmospheric depth, slightly desaturated and moody, evoking a quiet, magical early-morning stillness. Vertical portrait orientation. The words \"Seedream 5 Pro\" appear centered in the middle of the image, rendered in a pink embroidered thread texture \u2014 raised stitched lettering with visible thread grain, soft drop shadow, and a slightly frayed, tactile fabric-patch look, as if machine-embroidered onto the scene.",
    "image_input": [],
    "aspect_ratio": "match_input_image",
    "output_format": "png"
})
print(output)
```

## FAQ
- **How many images does a request return?**
  - The example returned one image in standard mode. Each URL in `output` is billed as one image.
- **Can I use reference images?**
  - Yes. Put 1 to 10 image URLs in `image_input`. Keep `aspect_ratio` at `match_input_image` to follow the input image's shape.
- **What does layer decomposition do?**
  - With `layer_decomposition` set to `true` and exactly one image in `image_input`, the model splits that image into a base image plus up to 16 element layers. Layers are always PNG.
- **How can I lower the cost?**
  - Use `size` `1K` ($0.058 per image) instead of the default `2K` ($0.116 per image).
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Seedream 5 Pro API by ByteDance: generate 1K or 2K images from text or up to 10 reference images, or split one image into a base image and separate layers.