Admin Dashboard
Total Keys
-
Active Keys
-
Suspended Keys
-
Total Requests (All Time)
-
| ID | API Key | Owner | Quota | Used | Status | Expires | Actions | |
|---|---|---|---|---|---|---|---|---|
| Loading... | ||||||||
| ID | API Key | Owner | Model | Status | Response Time | Timestamp | Error |
|---|---|---|---|---|---|---|---|
| Loading... | |||||||
Complete reference for the SeedDream Image Generation API Gateway
All customer API endpoints require authentication via a Bearer token in the Authorization header.
Authorization: Bearer kikaku_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠️ Security: Never share your API key publicly. Keep it stored in environment variables or secure vault.
| Feature | seedream-4.5 | seedream-4.0 |
|---|---|---|
| Model ID (internal) | seedream-4-5-251128 | seedream-4-0-250828 |
| Text to image | ✅ | ✅ |
| Text to grouped images | ✅ | ✅ |
| Single image to image | ✅ | ✅ |
| Multi-reference images to image | ✅ | ✅ |
| Streaming output | ✅ | ✅ |
| Resolution | 2K, 4K | 1K, 2K, 4K |
| Output format | jpeg | jpeg |
| Prompt optimization | standard | standard, fast |
| Max images/minute | 500 | 500 |
Generate images using SeedDream models. The gateway proxies your request to BytePlus Ark API with the real credentials, tracks quota, and logs the request.
curl -X POST ${BASE_URL}/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "seedream-4.5",
"prompt": "A beautiful sunset over the ocean, photorealistic, 8K quality",
"size": "2K",
"response_format": "url",
"watermark": false
}'
{
"model": "seedream-4.5",
"prompt": "Change the background to a tropical beach",
"image": "https://example.com/your-reference-image.jpg",
"size": "2K",
"response_format": "url",
"watermark": false
}
{
"model": "seedream-4.5",
"prompt": "Replace the clothing in image 1 with the outfit from image 2",
"image": [
"https://example.com/person.jpg",
"https://example.com/outfit.jpg"
],
"sequential_image_generation": "disabled",
"size": "2K",
"response_format": "url",
"watermark": false
}
Use the n parameter (1–8) to generate multiple images. The gateway automatically sets sequential_image_generation: "auto", max_images, and stream: false for you.
curl -X POST ${BASE_URL}/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "seedream-4.5",
"prompt": "Generate 4 illustrations of a courtyard across the four seasons",
"size": "2K",
"n": 4,
"response_format": "url",
"watermark": false
}'
💡 How it works: When n > 1, the gateway sends sequential_image_generation: "auto" with stream: false to the SeedDream API. If the API returns fewer images than requested, the gateway automatically makes parallel individual API calls to fill the remaining slots, ensuring you always receive the requested number of images.
Or use the native SeedDream parameters directly (requires stream: false):
{
"model": "seedream-4.5",
"prompt": "Generate 4 illustrations of a courtyard across the four seasons",
"size": "2K",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {
"max_images": 4
},
"stream": false,
"response_format": "url",
"watermark": false
}
⚠️ Important: When using native sequential_image_generation parameters directly, you must set "stream": false. Without it, the API may only return 1 image. Using the n shortcut is recommended as the gateway handles this automatically.
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Model name: seedream-4.0 or seedream-4.5 |
| prompt | string | Yes | Text description of the image to generate (max 10,000 chars) |
| n | integer | No | Number of images to generate (1–8). Automatically enables batch mode via sequential_image_generation. Default: 1 |
| image | string | string[] | No | Reference image URL(s) for image-to-image generation. Single URL or array of up to 14 URLs |
| size | string | No | Output resolution: 1K, 2K, 4K, or specific pixels like 2048x2048 |
| response_format | string | No | url (download link) or b64_json (Base64 encoded). Default: url |
| output_format | string | No | jpeg (default) or png. Note: 4.5/4.0 only support jpeg |
| watermark | boolean | No | true to add "AI generated" watermark, false for none. Default: false |
| stream | boolean | No | Enable streaming output for progressive image delivery. Default: false |
| sequential_image_generation | string | No | auto (generate multiple related images) or disabled (single image). Default: disabled. Requires stream: false. Auto-set when using n > 1 |
| sequential_image_generation_options | object | No | { "max_images": N } — Max images to generate (input refs + output ≤ 15). Auto-set when using n > 1 |
| optimize_prompt_options | object | No | { "mode": "standard" | "fast" } — Prompt optimization. fast only for seedream-4.0 |
{
"created": 1234567890,
"data": [
{
"url": "https://ark-doc.tos-ap-southeast-1.bytepluses.com/...",
"size": "2048x2048",
"index": 0
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 1,
"total_tokens": 1
}
}
{
"created": 1234567890,
"data": [
{
"b64_json": "/9j/4AAQSkZJRgABAQ...(base64 encoded image data)",
"size": "2048x2048",
"index": 0
}
]
}
{
"created": 1234567890,
"data": [
{ "url": "https://...image1.jpg", "size": "2048x2048" },
{ "url": "https://...image2.jpg", "size": "2048x2048" },
{ "url": "https://...image3.jpg", "size": "2048x2048" },
{ "url": "https://...image4.jpg", "size": "2048x2048" }
],
"usage": {
"generated_images": 4,
"output_tokens": 65536,
"total_tokens": 65536
}
}
💡 Note: Image URLs are temporary and expire after 24 hours. Download and save generated images promptly.
Two methods to specify output size (cannot be used together):
Specify resolution and describe aspect ratio in prompt
{ "size": "2K" }
Specify exact width x height in pixels
{ "size": "2048x2048" }
| Aspect Ratio | seedream-4.0 (1K) | seedream-4.0 / 4.5 (2K) | seedream-4.0 / 4.5 (4K) |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 3:4 | 864x1152 | 1728x2304 | 3520x4704 |
| 4:3 | 1152x864 | 2304x1728 | 4704x3520 |
| 16:9 | 1312x736 | 2848x1600 | 5504x3040 |
| 9:16 | 736x1312 | 1600x2848 | 3040x5504 |
| 3:2 | 1248x832 | 2496x1664 | 4992x3328 |
| 2:3 | 832x1248 | 1664x2496 | 3328x4992 |
| 21:9 | 1568x672 | 3136x1344 | 6240x2656 |
Note: seedream-4.5 does not support 1K. seedream-4.0 supports all three (1K, 2K, 4K).
curl -X POST YOUR_BASE_URL/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer kikaku_YOUR_API_KEY" \
-d '{
"model": "seedream-4.5",
"prompt": "Vibrant close-up editorial portrait, model with piercing gaze, wearing a sculptural hat, rich color blocking, Vogue magazine cover aesthetic",
"size": "2K",
"response_format": "url",
"watermark": false
}'
import requests
API_KEY = "kikaku_YOUR_API_KEY"
BASE_URL = "YOUR_BASE_URL"
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
},
json={
"model": "seedream-4.5",
"prompt": "A beautiful sunset over the ocean",
"size": "2K",
"response_format": "url",
"watermark": False
}
)
data = response.json()
print(data["data"][0]["url"])
const axios = require('axios');
const API_KEY = 'kikaku_YOUR_API_KEY';
const BASE_URL = 'YOUR_BASE_URL';
const response = await axios.post(
`${BASE_URL}/v1/images/generations`,
{
model: 'seedream-4.5',
prompt: 'A beautiful sunset over the ocean',
size: '2K',
response_format: 'url',
watermark: false
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
}
}
);
console.log(response.data.data[0].url);
<?php
$apiKey = 'kikaku_YOUR_API_KEY';
$baseUrl = 'YOUR_BASE_URL';
$ch = curl_init("$baseUrl/v1/images/generations");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
"Authorization: Bearer $apiKey"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'model' => 'seedream-4.5',
'prompt' => 'A beautiful sunset over the ocean',
'size' => '2K',
'response_format' => 'url',
'watermark' => false
]));
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo $data['data'][0]['url'];
Check your own API key quota, usage count, and detailed statistics.
curl -X GET YOUR_BASE_URL/v1/usage \
-H "Authorization: Bearer kikaku_YOUR_API_KEY"
{
"owner_name": "John Doe",
"email": "john@example.com",
"quota_limit": 1000,
"used_count": 42,
"remaining": 958,
"status": "active",
"created_at": "2025-01-01T00:00:00.000Z",
"expires_at": "2025-12-31T23:59:59.000Z",
"stats": {
"total_requests": 42,
"successful_requests": 40,
"failed_requests": 2,
"avg_response_time_ms": 3200
}
}
View your own request history with pagination and date filtering.
| Query Parameter | Type | Description |
|---|---|---|
| start_date | string (ISO date) | Filter logs from this date |
| end_date | string (ISO date) | Filter logs until this date |
| page | integer | Page number (default: 1) |
| limit | integer | Results per page (default: 20, max: 100) |
curl -X GET "YOUR_BASE_URL/v1/logs?page=1&limit=20" \
-H "Authorization: Bearer kikaku_YOUR_API_KEY"
To ensure fair usage and prevent abuse:
429 Too Many Requests when exceededRateLimit-Limit, RateLimit-Remaining, RateLimit-Reset| HTTP Code | Error | Description |
|---|---|---|
| 400 | Bad Request | Missing required parameter or unsupported model |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | API key suspended or expired |
| 429 | Too Many Requests | Rate limit or quota exceeded |
| 500 | Internal Server Error | Server error or upstream API failure |
| 504 | Request Timeout | Upstream API took too long (>120s) |
Image input requirements:
Retention: Generated image URLs expire after 24 hours. Save images promptly.
Quota: Each API key has a maximum request quota. Check usage via GET /v1/usage.
All admin endpoints require the X-Admin-Secret header.
| Method | Endpoint | Description |
|---|---|---|
| POST | /admin/keys | Create new API key |
| GET | /admin/keys | List all keys with usage stats |
| PUT | /admin/keys/:id | Full edit (name, email, quota, status, expiry, used_count) |
| PATCH | /admin/keys/:id | Quick update quota or status |
| DELETE | /admin/keys/:id | Revoke key (soft delete) |
| GET | /admin/logs | View all request logs (with filters) |
Loading gallery...