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

> ByteDance Seedream 4.0 image generation API for text-to-image and image-to-image workflows with 1K, 2K, and 4K output presets

## Overview

Seedream 4.0 is a ByteDance image model for text-to-image generation and reference-guided image generation. It supports 1K, 2K, and 4K output presets, up to 10 generated images per task, optional sequential generation, and prompt optimization with `standard` or `fast`.

| Capability            | Value                                                     |
| --------------------- | --------------------------------------------------------- |
| Model ID              | `seedream-4-0`                                            |
| Modes                 | `text-to-image`, `image-to-image`                         |
| Prompt length         | 1-5000 characters                                         |
| Reference images      | 1-14 URLs for `image-to-image`                            |
| Images per task       | `max_images` is required, 1-10                            |
| Resolution tiers      | `1K`, `2K`, `4K`                                          |
| Aspect ratios         | `1:1`, `2:3`, `3:2`, `4:3`, `3:4`, `9:16`, `16:9`, `21:9` |
| Size input            | `1K`, `2K`, `4K`, `2048x2048`, `2048X2048`, `2048*2048`   |
| Sequential generation | `disabled`, `auto`                                        |
| Prompt optimization   | `standard`, `fast`                                        |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint                                   | Purpose                               |
| ------ | ------------------------------------------ | ------------------------------------- |
| `POST` | `/generateTask/seedream-4-0`               | Submit a generation task              |
| `GET`  | `/statusTask/seedream-4-0?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

This minimal request submits a text-to-image task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/seedream-4-0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "mode": "text-to-image",
      "prompt": "a sunrise train passing through snowy hills",
      "max_images": 2,
      "resolution": "1K",
      "aspect_ratio": "16:9",
      "prompt_optimize_mode": "fast"
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save the `taskId`; you need it to poll for the final result.

## Request body

### Text-to-image

```json theme={null}
{
  "input": {
    "mode": "text-to-image",
    "prompt": "a clean architectural concept of a coastal library",
    "max_images": 2,
    "resolution": "1K",
    "aspect_ratio": "16:9",
    "prompt_optimize_mode": "fast"
  }
}
```

### Image-to-image

```json theme={null}
{
  "input": {
    "mode": "image-to-image",
    "prompt": "turn this sketch into a cinematic concept frame",
    "image_urls": [
      "https://example.com/reference-1.png"
    ],
    "max_images": 2,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "sequential_image_generation": "auto",
    "prompt_optimize_mode": "standard"
  }
}
```

### Explicit size

```json theme={null}
{
  "input": {
    "mode": "text-to-image",
    "prompt": "an editorial interior still",
    "max_images": 1,
    "size": "2048*2048"
  }
}
```

## Parameters

<ParamField body="request_type" type="string" default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Seedream 4.0 input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" required>
      Generation mode. Supported values: `text-to-image`, `image-to-image`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Text prompt describing the desired image or edit. Supports 1-5000 characters after trimming whitespace.
    </ParamField>

    <ParamField body="max_images" type="integer" required>
      Number of images to request. Supported range: 1-10.
    </ParamField>

    <ParamField body="image_urls" type="string[]">
      Reference image URLs. Required for `image-to-image`. Supports 1-14 URLs. URLs should be public, directly accessible image files.
    </ParamField>

    <ParamField body="resolution" type="string" default="2K">
      Output resolution preset. Supported values: `1K`, `2K`, `4K`. When `resolution + aspect_ratio` and `size` are both provided, `resolution + aspect_ratio` takes precedence.
    </ParamField>

    <ParamField body="aspect_ratio" type="string">
      Optional output aspect ratio. Supported values: `1:1`, `2:3`, `3:2`, `4:3`, `3:4`, `9:16`, `16:9`, `21:9`.
    </ParamField>

    <ParamField body="size" type="string">
      Optional explicit size or preset token. Preset tokens are case-insensitive and support `1K`, `2K`, and `4K`. Pixel strings accept `x`, `X`, or `*` separators, such as `2048x2048`, `2048X2048`, or `2048*2048`. Custom pixel sizes must use 16-pixel granularity, keep aspect ratio between `1/16` and `16`, and keep total pixels between `921,600` and `16,777,216` (`1280x720` to `4096x4096` equivalent). Unsupported custom values may be adjusted to the nearest supported output size.
    </ParamField>

    <ParamField body="sequential_image_generation" type="string" default="disabled">
      Sequential image mode. Supported values: `disabled`, `auto`.
    </ParamField>

    <ParamField body="prompt_optimize_mode" type="string" default="standard">
      Prompt optimization mode. Supported values: `standard`, `fast`.
    </ParamField>
  </Expandable>
</ParamField>

### Size presets from `resolution + aspect_ratio`

When `aspect_ratio` is provided, APIXO maps `resolution` and `aspect_ratio` to these output dimensions:

| Aspect ratio | `1K` size   | `2K` size   | `4K` size   |
| ------------ | ----------- | ----------- | ----------- |
| `1:1`        | `1024x1024` | `2048x2048` | `4096x4096` |
| `2:3`        | `832x1248`  | `1664x2496` | `3328x4992` |
| `3:2`        | `1248x832`  | `2496x1664` | `4992x3328` |
| `3:4`        | `864x1152`  | `1728x2304` | `3520x4704` |
| `4:3`        | `1152x864`  | `2304x1728` | `4704x3520` |
| `9:16`       | `736x1312`  | `1600x2848` | `3040x5504` |
| `16:9`       | `1312x736`  | `2848x1600` | `5504x3040` |
| `21:9`       | `1568x672`  | `3136x1344` | `6240x2656` |

## Polling and delivery guidance

Seedream 4.0 tasks are asynchronous.

| Resolution | Typical generation time | Recommended first poll  | Poll interval |
| ---------- | ----------------------- | ----------------------- | ------------- |
| `1K`       | 20s-30s                 | 15s after task creation | 3s            |
| `2K`       | 25s-35s                 | 20s after task creation | 3s-5s         |
| `4K`       | 40s-55s                 | 30s after task creation | 5s            |

For production systems, prefer `callback_url` instead of tight polling loops.

## Billing

Seedream 4.0 is billed per generated image. The current public APIXO price is a single flat rate for this model.

| Unit                | APIXO price       |
| ------------------- | ----------------- |
| Per generated image | `$0.0290 / image` |

Billing behavior:

```text theme={null}
precharge = requested max_images * unit price
final charge = successful images * unit price
```

If fewer images succeed than requested, APIXO automatically adjusts the final charge to the actual number of successful outputs.