# Seedream AI API

> Provider: **BytePlus**
> Source: https://www.pixazo.ai/models/seedream

Advanced image generation and editing by ByteDance.

## Seedream 5

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/seedream-5-0-lite-edit/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Seedream 5.0 Lite Edit generate request - Seedream 5.0 Lite Image Edit API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/seedream-5-0-lite-edit/v1/seedream-5-0-lite-edit-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "add sunglasses to the cat",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg"
  ],
  "image_size": "square_hd",
  "num_images": 1,
  "seed": 42,
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/seedream-5-0-lite-edit/v1/seedream-5-0-lite-edit-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "add sunglasses to the cat",
    "image_urls": [
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg"
    ],
    "image_size": "square_hd",
    "num_images": 1,
    "seed": 42,
    "enable_safety_checker": True
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/seedream-5-0-lite-edit/v1/seedream-5-0-lite-edit-request';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  prompt: 'add sunglasses to the cat',
  image_urls: [
    'https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg'
  ],
  image_size: 'square_hd',
  num_images: 1,
  seed: 42,
  enable_safety_checker: true
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/seedream-5-0-lite-edit/v1/seedream-5-0-lite-edit-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "add sunglasses to the cat",
    "image_urls": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg"],
    "image_size": "square_hd",
    "num_images": 1,
    "seed": 42,
    "enable_safety_checker": true
  }'
```

## Output

```
{
  "request_id": "seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=seedream-5-0-lite-edit&operation=seedream-5-0-lite-edit-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Seedream 5.0 Lite Edit generate request

Parameter

Required

Type

Description

prompt

Yes

string

Text instruction describing the edit to apply to the input image(s).

image\_urls

Yes

array<string>

One or more publicly accessible image URLs to edit. Must be reachable by the API server. Accepted formats: JPG, JPEG, PNG, WEBP.

image\_size

No

string | object

Output size preset or custom dimensions. Presets: "square\_hd", "square", "portrait\_4\_3", "portrait\_16\_9", "landscape\_4\_3", "landscape\_16\_9". Custom: {"width": 1024, "height": 1024}. Defaults to match input.

num\_images

No

integer

Number of images to generate. Range: 1-4. Defaults to 1.

seed

No

integer

Seed for deterministic generation. Use the same seed with the same prompt and image to reproduce results.

enable\_safety\_checker

No

boolean

When true, activates content safety filtering to block inappropriate or harmful outputs. Defaults to true.

## Example Request

```
{
  "prompt": "add sunglasses to the cat",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg"
  ],
  "image_size": "square_hd",
  "num_images": 1,
  "seed": 42,
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.035"
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-0-lite-edit' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-0-lite-edit",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedream-5-0-lite-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-0-lite-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:07.503Z",
  "updated_at": "2026-04-17T11:42:15.000Z",
  "completed_at": "2026-04-17T11:42:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type (image/jpeg or image/png)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/seedream-5-0-lite-text-to-image/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Seedream 5.0 Lite Text to Image generate request - Seedream 5.0 Lite Text to Image API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/seedream-5-0-lite-text-to-image/v1/seedream-5-0-lite-text-to-image-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "a majestic lion in a field of flowers, golden hour lighting, cinematic",
  "image_size": "square_hd",
  "num_images": 1,
  "seed": 42,
  "enable_safety_checker": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/seedream-5-0-lite-text-to-image/v1/seedream-5-0-lite-text-to-image-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "a majestic lion in a field of flowers, golden hour lighting, cinematic",
    "image_size": "square_hd",
    "num_images": 1,
    "seed": 42,
    "enable_safety_checker": True
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/seedream-5-0-lite-text-to-image/v1/seedream-5-0-lite-text-to-image-request';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  prompt: 'a majestic lion in a field of flowers, golden hour lighting, cinematic',
  image_size: 'square_hd',
  num_images: 1,
  seed: 42,
  enable_safety_checker: true
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/seedream-5-0-lite-text-to-image/v1/seedream-5-0-lite-text-to-image-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "a majestic lion in a field of flowers, golden hour lighting, cinematic",
    "image_size": "square_hd",
    "num_images": 1,
    "seed": 42,
    "enable_safety_checker": true
  }'
```

## Output

```
{
  "request_id": "seedream-5-0-lite-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-lite-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=seedream-5-0-lite-text-to-image&operation=seedream-5-0-lite-text-to-image-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Seedream 5.0 Lite Text to Image generate request

Parameter

Required

Type

Description

prompt

Yes

string

Text prompt describing the image to generate. Be specific and descriptive for best results.

image\_size

No

string | object

Size preset or custom dimensions. Presets: "square\_hd", "square", "portrait\_4\_3", "portrait\_16\_9", "landscape\_4\_3", "landscape\_16\_9". Custom: {"width": 1024, "height": 1024}. Defaults to "square\_hd".

num\_images

No

integer

Number of images to generate. Range: 1-4. Defaults to 1.

seed

No

integer

Seed for deterministic generation. Use the same seed with the same prompt to reproduce results.

enable\_safety\_checker

No

boolean

When true, activates content safety filtering to block inappropriate or harmful outputs. Defaults to true.

## Example Request

```
{
  "prompt": "a majestic lion in a field of flowers, golden hour lighting, cinematic",
  "image_size": "square_hd",
  "num_images": 1,
  "seed": 42,
  "enable_safety_checker": true
}
```

## Response

```
{
  "request_id": "seedream-5-0-lite-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-lite-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.035"
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'seedream-5-0-lite-text-to-image' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "seedream-5-0-lite-text-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedream-5-0-lite-text-to-image",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/seedream-5-0-lite-text-to-image_019d9b3e-9e95-75e3-7533-a5f1149cd9f94"
```

## Response (Completed)

```
{
  "request_id": "seedream-5-0-lite-text-to-image_019d9b3e-9e95-75e3-7533-a5f1149cd9f94",
  "status": "COMPLETED",
  "model_id": "seedream-5-0-lite-text-to-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedream-5-0-lite-text-to-image_019d9b3e-9e95-75e3-7533-a5f1149cd9f94/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-04-17T11:41:06.171Z",
  "updated_at": "2026-04-17T11:41:57.000Z",
  "completed_at": "2026-04-17T11:41:57.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type (image/jpeg or image/png)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

## Seedream 4.5

### Image to Image (Image Editing)

## Base URL

```
https://gateway.pixazo.ai/byteplus/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Seedream 4.5 Image to Image (Edit Image)

## Request Code

HTTP Python JavaScript cURL

```http
POST https://gateway.pixazo.ai/byteplus/v1/getEditImage
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "model": "seedream-4-5-251128",
  "prompt": "Make the cat eye blue",
  "image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
  "size": "2K",
  "guidance_scale": 6,
  "seed": 42
}
```

```python
import requests

url = "https://gateway.pixazo.ai/byteplus/v1/getEditImage"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "model": "seedream-4-5-251128",
    "prompt": "Make the cat eye blue",
    "image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
    "size": "2K",
    "guidance_scale": 6,
    "seed": 42
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```javascript
const url = 'https://gateway.pixazo.ai/byteplus/v1/getEditImage';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  model: "seedream-4-5-251128",
  prompt: "Make the cat eye blue",
  image: "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
  size: "2K",
  guidance_scale: 6,
  seed: 42
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```bash
curl -X POST "https://gateway.pixazo.ai/byteplus/v1/getEditImage" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
  "model": "seedream-4-5-251128",
  "prompt": "Make the cat eye blue",
  "image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
  "size": "2K",
  "guidance_scale": 6,
  "seed": 42
}'
```

## Output

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=bytedance-text-to-image&operation=edit-image)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Seedream 4.5 Image to Image (Edit Image)

Parameter

Required

Type

Description

model

No

string

Model ID. Use `seedream-4-5-251128` for Seedream 4.5, or `seededit-3-0-i2i-250628` for Seededit 3.0.

prompt

Yes

string

Text prompt describing the edit to apply to the image.

image

Yes

string

Publicly accessible URL of the source image, or a Base64 data URL (`data:image/<format>;base64,...`).

size

No

string

Output size. For Seedream 4.5: `2K` or `4K`. Seededit supports `adaptive`.

seed

No

integer

Random seed. Range: \[-1, 2147483647\]. `-1` (or unset) randomizes.

guidance\_scale

No

float

Strength of the prompt vs. the image. Range: \[1, 10\]. Higher = follow prompt more closely.

response\_format

No

string

Deprecated for queue flow — response always contains an R2 URL in `output.media_url`.

watermark

No

boolean

When `true`, adds an "AI-generated" watermark.

## Example Request

```
{
  "model": "seedream-4-5-251128",
  "prompt": "Make the cat eye blue",
  "image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
  "size": "2K",
  "guidance_scale": 6,
  "seed": 42
}
```

## Response

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.04"
}
```

### Error via Status/Webhook

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "byteplus",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "byteplus",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1776429228529-aq8fsc3s5k7-1.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-04-17T12:33:13.000Z",
  "updated_at": "2026-04-17T12:33:13.000Z",
  "completed_at": "2026-04-17T12:33:13.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type (image/jpeg)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a request** to the API endpoint above
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use the `X-Webhook-URL` header to receive a callback instead of polling.

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/byteplus/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Seedream 4.5 Text to Image

## Request Code

HTTP Python JavaScript cURL

```http
POST https://gateway.pixazo.ai/byteplus/v1/getTextToImage
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "model": "seedream-4-5-251128",
  "prompt": "a fisheye close-up of a cat face, playful dramatic effect",
  "size": "2K",
  "seed": 42
}
```

```python
import requests

url = "https://gateway.pixazo.ai/byteplus/v1/getTextToImage"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "model": "seedream-4-5-251128",
    "prompt": "a fisheye close-up of a cat face, playful dramatic effect",
    "size": "2K",
    "seed": 42
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```javascript
const url = 'https://gateway.pixazo.ai/byteplus/v1/getTextToImage';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  model: "seedream-4-5-251128",
  prompt: "a fisheye close-up of a cat face, playful dramatic effect",
  size: "2K",
  seed: 42
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```bash
curl -X POST "https://gateway.pixazo.ai/byteplus/v1/getTextToImage" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
  "model": "seedream-4-5-251128",
  "prompt": "a fisheye close-up of a cat face, playful dramatic effect",
  "size": "2K",
  "seed": 42
}'
```

## Output

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=bytedance-text-to-image&operation=text-to-image)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Seedream 4.5 Text to Image

Parameter

Required

Type

Description

model

No

string

Model ID. Use `seedream-4-5-251128` for Seedream 4.5.

prompt

Yes

string

Text prompt describing the image to generate.

size

No

string

Output size. For Seedream 4.5: `2K` or `4K`.

seed

No

integer

Random seed. Range: \[-1, 2147483647\]. Use the same seed+prompt to reproduce results.

response\_format

No

string

Deprecated for queue flow — response always contains an R2 URL in `output.media_url`.

watermark

No

boolean

When `true`, adds an "AI-generated" watermark.

## Example Request

```
{
  "model": "seedream-4-5-251128",
  "prompt": "a fisheye close-up of a cat face, playful dramatic effect",
  "size": "2K",
  "seed": 42
}
```

## Response

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.04"
}
```

### Error via Status/Webhook

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "byteplus",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "byteplus",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1776429228529-aq8fsc3s5k7-1.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-04-17T12:33:13.000Z",
  "updated_at": "2026-04-17T12:33:13.000Z",
  "completed_at": "2026-04-17T12:33:13.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type (image/jpeg)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a request** to the API endpoint above
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use the `X-Webhook-URL` header to receive a callback instead of polling.

## Seedream 4

### Image to Image (Image Editing — Multi-Ref)

## Base URL

```
https://gateway.pixazo.ai/byteplus/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Seedream 4 Multi-Image Edit

## Request Code

HTTP Python JavaScript cURL

```http
POST https://gateway.pixazo.ai/byteplus/v1/getEditMultiImage
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Girl holding the cat",
  "image": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png"
  ]
}
```

```python
import requests

url = "https://gateway.pixazo.ai/byteplus/v1/getEditMultiImage"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "Girl holding the cat",
    "image": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg","https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png"]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```javascript
const url = 'https://gateway.pixazo.ai/byteplus/v1/getEditMultiImage';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  prompt: "Girl holding the cat",
  image: ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg","https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png"]
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```bash
curl -X POST "https://gateway.pixazo.ai/byteplus/v1/getEditMultiImage" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
  "prompt": "Girl holding the cat",
  "image": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png"
  ]
}'
```

## Output

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=bytedance-text-to-image&operation=edit-multi-image)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Seedream 4 Multi-Image Edit

Parameter

Required

Type

Description

prompt

Yes

string

Text prompt describing how to combine or edit the input images.

image

Yes

array<string>

Array of 2+ publicly accessible image URLs to edit together.

model

No

string

Model ID. Defaults to Seedream 4 multi-image edit.

size

No

string

Output size preset (`2K`, `4K`, or `adaptive`).

seed

No

integer

Random seed. Range: \[-1, 2147483647\].

watermark

No

boolean

When `true`, adds an "AI-generated" watermark.

## Example Request

```
{
  "prompt": "Girl holding the cat",
  "image": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1757499948018-hntkjsg9kj.jpg",
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png"
  ]
}
```

## Response

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance. Required: $0.04"
}
```

### Error via Status/Webhook

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "byteplus",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "byteplus_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "byteplus",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/byteplus/1776429228529-aq8fsc3s5k7-1.jpg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-04-17T12:33:13.000Z",
  "updated_at": "2026-04-17T12:33:13.000Z",
  "completed_at": "2026-04-17T12:33:13.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type (image/jpeg)

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a request** to the API endpoint above
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use the `X-Webhook-URL` header to receive a callback instead of polling.