Kikaku API - Admin Dashboard

ID	API Key	Owner	Email	Quota	Used	Status	Expires	Actions
Loading...

ID	API Key	Owner	Model	Status	Response Time	Timestamp	Error
Loading...

🔑 Authentication

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.

🤖 Supported Models & Capabilities

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

POST /v1/images/generations

Generate images using SeedDream models. The gateway proxies your request to BytePlus Ark API with the real credentials, tracks quota, and logs the request.

Basic Text-to-Image 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
}'

Image-to-Image Request (single reference)

{
  "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
}

Multi-Image Blending (multiple references)

{
  "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
}

Grouped Image Generation (batch)

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.

📋 Request Parameters Reference

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

📤 Response Format

Success Response (response_format: "url")

{
  "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
  }
}

Success Response (response_format: "b64_json")

{
  "created": 1234567890,
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ...(base64 encoded image data)",
      "size": "2048x2048",
      "index": 0
    }
  ]
}

Batch Response (n > 1)

{
  "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.

📐 Image Output Dimensions

Two methods to specify output size (cannot be used together):

Method 1: Resolution Preset

Specify resolution and describe aspect ratio in prompt

{ "size": "2K" }

Method 2: Exact Pixels

Specify exact width x height in pixels

{ "size": "2048x2048" }

Recommended Dimensions by Model

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).

💻 Code Examples

▶ cURL

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
}'

▶ Python (requests)

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"])

▶ Node.js (axios)

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

<?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'];

GET /v1/usage

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"

Response

{
  "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
  }
}

GET /v1/logs

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"

⚡ Rate Limiting

To ensure fair usage and prevent abuse:

10 requests per minute per API key
Returns HTTP 429 Too Many Requests when exceeded
Rate limit headers included in response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset

❌ Error Codes

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)

⚠️ Usage Limitations

Image input requirements:

Supported formats: JPEG, PNG, WEBP, BMP, TIFF, GIF
Aspect ratio (width/height): Between 1/16 and 16
Width and height: Greater than 14px
Max file size: 10 MB per image
Max total pixels: 6000 × 6000 = 36,000,000 px
Max reference images: 14 images per request

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.

🛡️ Admin Endpoints

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)

Kikaku API Gateway

API Keys

📖 API Documentation

Table of Contents

🔑 Authentication

🤖 Supported Models & Capabilities

POST /v1/images/generations

Basic Text-to-Image Request

Image-to-Image Request (single reference)

Multi-Image Blending (multiple references)

Grouped Image Generation (batch)

📋 Request Parameters Reference

📤 Response Format

Success Response (response_format: "url")

Success Response (response_format: "b64_json")

Batch Response (n > 1)

📐 Image Output Dimensions

Method 1: Resolution Preset

Method 2: Exact Pixels

Recommended Dimensions by Model

💻 Code Examples

GET /v1/usage

Response

GET /v1/logs

⚡ Rate Limiting

❌ Error Codes

⚠️ Usage Limitations

🛡️ Admin Endpoints

Kikaku API Gateway

API Keys

📖 API Documentation

Table of Contents

🔑 Authentication

🤖 Supported Models & Capabilities

POST /v1/images/generations

Basic Text-to-Image Request

Image-to-Image Request (single reference)

Multi-Image Blending (multiple references)

Grouped Image Generation (batch)

📋 Request Parameters Reference

📤 Response Format

Success Response (response_format: "url")

Success Response (response_format: "b64_json")

Batch Response (n > 1)

📐 Image Output Dimensions

Method 1: Resolution Preset

Method 2: Exact Pixels

Recommended Dimensions by Model

💻 Code Examples

GET /v1/usage

Response

GET /v1/logs

⚡ Rate Limiting

❌ Error Codes

⚠️ Usage Limitations

🛡️ Admin Endpoints

Create New API Key

✏️ Edit API Key