Name: Seedream 5.0 Lite API: Text to Image and Image Editing
Brand: magicapi
SKU: api-magicapi-image-generation-reasoning-editing-bytedance-seedream-5-lite
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Text-to-Image and Image Editing API (ByteDance Seedream 5.0 lite)

## Overview
Seedream 5.0 lite is an image model from ByteDance. Its developer describes it as image generation with built-in reasoning, example-based editing and deep domain knowledge.

Send a `prompt` (up to 4,000 characters) to generate an image, or add 1 to 14 images in `image_input` for image-to-image generation and multi-reference editing. Set `sequential_image_generation` to `auto` to let the model return several related images, up to `max_images`. Images come out at 2K or 3K in PNG or JPEG. The response is a list of image URLs.

## Features
- **Text-to-image**: prompts up to 4,000 characters; keeping them under 600 English words is recommended.
- **Multi-reference editing**: 1 to 14 images in `image_input` for single or multi-reference generation.
- **Image sets**: `sequential_image_generation` `auto` lets the model generate several related images (story scenes, character variations), up to `max_images` (1 to 15). Input plus generated images cannot exceed 15.
- **Resolution**: `2K` (2048 px, default) or `3K` (3072 px).
- **Aspect ratios**: `match_input_image` (default), `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`.
- **Formats**: `png` (default) or `jpeg`.

## Use Cases
1. **Editorial and fashion imagery**: detailed scenes from long, descriptive prompts, as in the example.
2. **Product and marketing visuals**: images in the aspect ratio of each placement.
3. **Reference-based editing**: restyle or combine existing images by passing them in `image_input`.
4. **Storyboards and character sheets**: sets of related images with `sequential_image_generation` set to `auto`.

## Visual Examples
### Example Input
A long fashion editorial prompt at `2K` with a `2:3` aspect ratio:

```json
{
  "size": "2K",
  "prompt": "A striking fashion editorial photograph of a model wearing an elaborate haute couture gown made entirely of living flowers \u2014 white peonies, pale pink roses, and trailing jasmine. She stands in a misty English garden at dawn. The dress cascades to the ground and merges with the garden floor. Dewdrops on every petal catch the first light. Her hair is pulled back severely, face serene, skin porcelain. A single monarch butterfly rests on her shoulder. The background is a soft impressionist blur of green hedgerows and pale sky. Shot on Phase One IQ4 150MP, every stamen and pistil razor sharp.",
  "aspect_ratio": "2:3"
}
```

### Example Output
![Seedream 5.0 lite output: a model in a gown made of white peonies and pink roses in a misty garden at dawn, with a monarch butterfly on her shoulder](https://blog.api.market/wp-content/uploads/2026/10/seedream-5-lite-output-426wx2w5-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes | none | up to 4000 characters | Text prompt for image generation. Maximum 4000 characters. Keeping prompts under 600 English words is recommended for best results. |
| `image_input` | array of URLs | No | `[]` |  | Input image(s) for image-to-image generation. List of 1-14 images for single or multi-reference generation. |
| `size` | string | No | `2K` | `2K`, `3K` | Image resolution: 2K (2048px) or 3K (3072px). |
| `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. Use 'match_input_image' to automatically match the input image's aspect ratio. |
| `sequential_image_generation` | string | No | `disabled` | `disabled`, `auto` | Group image generation mode. 'disabled' generates a single image. 'auto' lets the model decide whether to generate multiple related images (e.g., story scenes, character variations). |
| `max_images` | integer | No | `1` | `1` to `15` | Maximum number of images to generate when sequential_image_generation='auto'. Range: 1-15. Total images (input + generated) cannot exceed 15. |
| `output_format` | string | No | `png` | `png`, `jpeg` | Output image format. |
| `return_byteplus_urls` | boolean | No | `false` |  | Return image URLs hosted by BytePlus (ByteDance's cloud) instead of downloaded copies. These URLs expire after 24 hours. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.044 per API unit.
- **1 API unit = 1 output image.**
- With `sequential_image_generation` set to `disabled` (the default), each request returns one image and costs $0.044. With `auto`, the model can return up to `max_images` images and each one is billed.
- Size (`2K` or `3K`), aspect ratio, output format and reference images do not change the price per image.
- **Example cost**: the example request returned 1 image = **$0.044**.
- **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/image-generation-reasoning-editing-bytedance-seedream-5-lite`

### 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. The example took about 38 seconds.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/image-generation-reasoning-editing-bytedance-seedream-5-lite/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "bytedance/seedream-5-lite",
    "input": {
      "size": "2K",
      "prompt": "A striking fashion editorial photograph of a model wearing an elaborate haute couture gown made entirely of living flowers \u2014 white peonies, pale pink roses, and trailing jasmine. She stands in a misty English garden at dawn. The dress cascades to the ground and merges with the garden floor. Dewdrops on every petal catch the first light. Her hair is pulled back severely, face serene, skin porcelain. A single monarch butterfly rests on her shoulder. The background is a soft impressionist blur of green hedgerows and pale sky. Shot on Phase One IQ4 150MP, every stamen and pistil razor sharp.",
      "aspect_ratio": "2:3"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "426wx2w5exrmt0d1c6rae68jkc",
  "version": "bytedance/seedream-5-lite",
  "status": "starting",
  "created_at": "2026-10-22T03:38:41.057Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/image-generation-reasoning-editing-bytedance-seedream-5-lite/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "426wx2w5exrmt0d1c6rae68jkc",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/seedream-5-lite-output-426wx2w5-api-market.jpg"
  ],
  "error": null,
  "created_at": "2026-10-22T03:38:41.057Z",
  "started_at": "2026-10-22T03:38:41.257Z",
  "completed_at": "2026-10-22T03:39:18.666Z"
}
```

`output` is a list of image URLs, one per generated 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 missing `prompt`, more than 14 entries in `image_input` or a `size` other than `2K` or `3K`.
- **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/image-generation-reasoning-editing-bytedance-seedream-5-lite";

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-lite", 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 striking fashion editorial photograph of a model wearing an elaborate haute couture gown made entirely of living flowers \u2014 white peonies, pale pink roses, and trailing jasmine. She stands in a misty English garden at dawn. The dress cascades to the ground and merges with the garden floor. Dewdrops on every petal catch the first light. Her hair is pulled back severely, face serene, skin porcelain. A single monarch butterfly rests on her shoulder. The background is a soft impressionist blur of green hedgerows and pale sky. Shot on Phase One IQ4 150MP, every stamen and pistil razor sharp.",
    "aspect_ratio": "2:3"
  }).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/image-generation-reasoning-editing-bytedance-seedream-5-lite"


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-lite", "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")


print(create_and_wait_for_prediction({
    "size": "2K",
    "prompt": "A striking fashion editorial photograph of a model wearing an elaborate haute couture gown made entirely of living flowers \u2014 white peonies, pale pink roses, and trailing jasmine. She stands in a misty English garden at dawn. The dress cascades to the ground and merges with the garden floor. Dewdrops on every petal catch the first light. Her hair is pulled back severely, face serene, skin porcelain. A single monarch butterfly rests on her shoulder. The background is a soft impressionist blur of green hedgerows and pale sky. Shot on Phase One IQ4 150MP, every stamen and pistil razor sharp.",
    "aspect_ratio": "2:3"
}))
```

## FAQ
- **How many images does one request return?**
  - One by default. With `sequential_image_generation` set to `auto`, the model decides how many related images to make, up to `max_images`. Each image costs $0.044.
- **Can I edit an existing image?**
  - Yes. Pass 1 to 14 images in `image_input` and describe the change in `prompt`. Leave `aspect_ratio` at `match_input_image` to keep the input's proportions.
- **Which resolutions are available?**
  - `2K` (2048 px, default) and `3K` (3072 px), at the same price per image.
- **How long can the prompt be?**
  - Up to 4,000 characters. Prompts under 600 English words are recommended.
- **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`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## 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.0 lite API by ByteDance: generate 2K or 3K images from text, edit with up to 14 reference images, or create sets of related images.