# Kerox — Full Documentation > Base API URL: https://api.kerox.ai/v1 | OpenAPI: https://api.kerox.ai/openapi.json | Index: https://kerox.ai/llms.txt --- # Introduction > Generate images and videos through one API with native model parameters, transparent per-task billing, and webhooks. ## What Kerox does Kerox gives you a single HTTP API for image and video generation models from makers such as ByteDance and Alibaba. Every model uses the same task lifecycle (`POST /v1/tasks`, poll or receive a webhook, download outputs), while keeping each model's native input parameters intact. - **Base URL**: `https://api.kerox.ai/v1` - **Authentication**: `Authorization: Bearer ` - **Format**: JSON requests and responses (except multipart uploads to `/v1/files`) - **Currency**: USD strings with 4 decimal places (`"0.0300"`), billed directly from your wallet ## Core endpoints | Endpoint | Purpose | | --- | --- | | `POST /v1/tasks` | Create a generation task (optionally wait up to 60 s synchronously) | | `GET /v1/tasks/{id}` | Poll a task's status, outputs, cost, and error details | | `GET /v1/tasks` | List recent tasks with cursor pagination and filters | | `POST /v1/tasks/{id}/cancel` | Cancel a `queued` task and release its hold | | `GET /v1/models` | List models with live `input_schema` and your account's pricing | | `POST /v1/estimate` | Estimate cost for a request without creating a task or holding funds | | `POST /v1/files` | Upload reference images, videos, or audio (7-day retention) | | `GET /v1/account` | Read balance, held amount, limits, and the number of tasks in progress | | `GET /v1/usage` | Usage and spend by day and model | ## Native and unified formats By default, `input` follows the model maker's native parameter names (`format: "native"`), documented in each model's `input_schema`. When you want to switch between models without rewriting common fields (`prompt`, `images`, `aspect_ratio`, `resolution`, `duration`), pass `format: "unified"` on supported models. ## Next steps - [Quickstart](https://kerox.ai/docs/quickstart): Create a key and generate your first image in about two minutes. - [Pricing & billing](https://kerox.ai/docs/pricing-billing): How wallet holds, settlements, refunds, and token-billed video rates work. - [API reference](https://kerox.ai/docs/api): Interactive OpenAPI 3.1 reference with Try it support. - [Models](https://kerox.ai/docs/models): Browse schemas, parameters, and live prices generated from config. --- # Quickstart > Make your first image in about two minutes: create a key, submit a task, read the result. ## Create an API key Sign in to the [Console](/console/api-keys) with the 6-digit code we email you (your first sign-in creates the account), top up your balance, and create a key under **API → API keys**. Store it in an environment variable: the full key is shown only once, when you create it. ```bash export KEROX_API_KEY="kx_live_your_api_key_here" ``` ## Submit a task Send a `POST` request to `https://api.kerox.ai/v1/tasks`. Passing `wait_seconds: 30` lets short image tasks finish in a single HTTP request; if the task takes longer, the response returns the current `queued` or `running` task object so you can poll or wait for a webhook. ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedream-5.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "wait_seconds": 30 }' ``` ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedream-5.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K", }, "wait_seconds": 30, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'bytedance/seedream-5.5', input: { prompt: 'editorial portrait of a ceramicist in morning sunlight, 35mm film', size: '2K', }, wait_seconds: 30, }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` > **Save the output within 7 days** > > Generated image and video URLs expire 7 days after completion (see `expires_at`). Download and store anything you want to keep in your own object storage. ## Read the result When `status` is `"succeeded"`, outputs appear under `output.images` or `output.videos`, and `cost` shows the settled USD amount (the price of the image; see the [model's page](/docs/models) for current prices). If `status` is still `"queued"` or `"running"`, poll `GET /v1/tasks/{id}` or configure a webhook. ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedream-5.5", "status": "succeeded", "source": "api", "format": "native", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "output": { "images": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png", "content_type": "image/png", "width": 2048, "height": 2048 } ] }, "error": null, "cost": { "amount": "0.0280", "currency": "USD", "status": "settled" }, "metadata": null, "warnings": [], "created_at": "2026-11-20T08:01:02Z", "started_at": "2026-11-20T08:01:02Z", "completed_at": "2026-11-20T08:01:10Z", "expires_at": "2026-11-27T08:01:10Z" } ``` ## Next steps - [Webhooks](https://kerox.ai/docs/webhooks): Get notified when video tasks finish. - [Files & inputs](https://kerox.ai/docs/files): Send reference images and first frames. - [MCP server](https://kerox.ai/docs/mcp): Let Claude Code or Cursor call Kerox. --- # Authentication > Authenticate API requests with Bearer API keys and manage key lifecycle safely. ## Bearer API keys Pass your API key in the `Authorization` header on every request to `https://api.kerox.ai/v1`: ```bash curl https://api.kerox.ai/v1/account \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```python import os import requests resp = requests.get( "https://api.kerox.ai/v1/account", headers={"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"}, timeout=30, ) print(resp.json()) ``` ```javascript const res = await fetch('https://api.kerox.ai/v1/account', { headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}` }, }); console.log(await res.json()); ``` `GET /v1/models` and `GET /v1/models/{id}` can be called without a key to inspect public rates and schemas. Passing your key returns your account's effective pricing (including any account-level or model-specific discount). ## Key security & rotation - **Hashed at rest**: Kerox only stores a cryptographic hash of each key. The full key is shown once, when you create it in [Console → API → API keys](/console/api-keys). - **Server-side only**: Do not embed live API keys in client-side browser apps or mobile binaries. - **Zero-downtime rotation**: Create a new key, deploy it to your services, verify traffic on the new key in the console, and then revoke the old key. A revoked key is rejected with HTTP `401` (`invalid_api_key`); allow up to a minute for the revocation to reach every server. ## Account prerequisites Before `POST /v1/tasks` accepts submissions: 1. Your email address must be verified, which signing in with an emailed code or with Google does (otherwise HTTP `403` `email_not_verified`). 2. Your account must be active (otherwise HTTP `403` `account_disabled`). 3. Your available wallet balance must cover the estimated task cost (otherwise HTTP `402` `insufficient_balance`). --- # Pricing & billing > Pay-as-you-go wallet billing in USD, pre-submission cost estimates, automatic failure refunds, and token-billed video pricing. ## How wallet billing works Kerox bills in USD directly from your wallet — no subscriptions or opaque credit conversions. Every task follows three ledger states: 1. **Hold (`cost.status: "held"`)**: When you submit `POST /v1/tasks`, Kerox calculates the estimated cost and places a hold on your available balance. 2. **Settle (`cost.status: "settled"`)**: When the task succeeds, Kerox settles the actual cost and releases any excess hold back to your balance. 3. **Refund (`cost.status: "refunded"`)**: If the task fails, times out, or is canceled while `queued`, the entire hold is refunded automatically (`cost.amount: "0.0000"`). ## Current model rates All numbers below are calculated directly from the live model catalog configuration. Sign in or call `GET /v1/models` with your API key to see any account-level or per-model discounts. | Model | ID | Billing | Kerox rate | Notes | | --- | --- | --- | --- | --- | | Seedream 5.5 | `bytedance/seedream-5.5` | Per image | 1K/1.5K: $0.0160, 2K: $0.0280 | Save 20% vs official | | Seedream 5.0 Pro | `bytedance/seedream-5.0-pro` | Per image | 1K/1.5K: $0.0360, 2K: $0.0720 | Save 20% vs official | | Seedream 4.5 | `bytedance/seedream-4.5` | Per image | $0.0320 | Save 20% vs official | | Seedream 4.0 | `bytedance/seedream-4.0` | Per image | $0.0270 | Save 10% vs official | | Seedream 5.0 Lite | `bytedance/seedream-5.0-lite` | Per image | $0.0315 | Save 10% vs official | | Seedance 2.5 | `bytedance/seedance-2.5` | Billed by tokens | Approx. $0.2196 / s (720p) | 16:9 without reference video; lower rate with reference video | | Seedance 2.0 | `bytedance/seedance-2.0` | Billed by tokens | Approx. $0.1436 / s (720p) | 16:9 without reference video; lower rate with reference video | | Seedance 2.0 Fast | `bytedance/seedance-2.0-fast` | Billed by tokens | Approx. $0.0968 / s (720p) | 16:9 without reference video; lower rate with reference video | | Seedance 2.0 Mini | `bytedance/seedance-2.0-mini` | Billed by tokens | Approx. $0.0605 / s (720p) | 16:9 without reference video; lower rate with reference video | ## Seedance video pricing (billed by tokens) Seedance video models are shown as **Approx. $/s** so you can compare durations at a glance, while actual settlement is **billed by tokens**: - **Two rate tiers**: - **Without reference video**: standard per-second estimate applied to the output duration. - **With reference video**: lower unit rate applied to the combined duration (`output seconds + reference video seconds`). - **Token formula**: `tokens = (output seconds + reference video seconds) × width × height × frame rate / 1024`, with width and height from the requested resolution and aspect ratio. Each model's page, and `pricing.token_formula` in `GET /v1/models`, give the formula with that model's frame rate. - **Aspect ratio & audio**: Per-second estimates are converted at `16:9` without reference video. At the same resolution, other aspect ratios differ by less than 5%. Turning audio on or off does not change the price. - **Estimate before submitting**: Studio shows the estimated cost before you click Generate, and API callers can send the same request body to `POST /v1/estimate`. The final charge follows the tokens of the finished video. ## Estimating cost before submission `POST /v1/estimate` accepts the same payload as `POST /v1/tasks`, never creates a task, never holds balance, and does not count against per-minute submission rate limits. The `amount` it returns is what submitting the request would hold. `exact` is `false` when the final charge depends on the result, as it does for token-billed models. ```bash curl -X POST https://api.kerox.ai/v1/estimate \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedance-2.5", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow" } ], "resolution": "720p", "duration": 5 } }' ``` ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/estimate", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedance-2.5", "input": { "content": [ {"type": "text", "text": "a red fox running through fresh snow"} ], "resolution": "720p", "duration": 5, }, }, timeout=30, ) print(resp.json()) ``` ```javascript const res = await fetch('https://api.kerox.ai/v1/estimate', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'bytedance/seedance-2.5', input: { content: [ { type: 'text', text: 'a red fox running through fresh snow' }, ], resolution: '720p', duration: 5, }, }), }); console.log(await res.json()); ``` ## Top-ups & balance alerts Request a top-up from [Console → Wallet](/console/wallet) (minimum $5). We reply in Support with payment details, and your balance updates as soon as the payment is confirmed. Low-balance emails are off by default: turn them on and set the amount in [Console → Settings](/console/settings). You can also read your balance at any time with `GET /v1/account`. --- # Tasks & polling > Understand the task lifecycle, synchronous waiting, polling, cancellation, and result retention. ## Task lifecycle Every generation request creates a task object (`object: "task"`) that moves through a fixed set of states: - `queued`: Accepted and funds held; waiting to start. Only `queued` tasks can be canceled. - `running`: Actively generating. - `succeeded`: Terminal state. Outputs appear in `output` and `cost.status` is `"settled"`. - `failed`: Terminal state. Error details appear in `error` and `cost.status` is `"refunded"`. - `canceled`: Terminal state. Canceled while `queued`; `cost.status` is `"refunded"`. ## Synchronous wait vs. polling For fast image models, pass `wait_seconds` (1–60) on `POST /v1/tasks` so the request waits until the task finishes or the timeout elapses. For video models or longer runs, submit with `wait_seconds: 0` (the default) and either receive a [Webhook](/docs/webhooks) or poll `GET /v1/tasks/{id}` every 2–5 seconds. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```python import os import time import requests headers = {"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"} task_id = "task_01JD8X9B4Q2M7T8N3K5P6R1S0V" while True: task = requests.get( f"https://api.kerox.ai/v1/tasks/{task_id}", headers=headers, timeout=30, ).json() if task["status"] in ("succeeded", "failed", "canceled"): print(task) break time.sleep(3) ``` ```javascript const headers = { Authorization: `Bearer ${process.env.KEROX_API_KEY}` }; const taskId = 'task_01JD8X9B4Q2M7T8N3K5P6R1S0V'; while (true) { const res = await fetch(`https://api.kerox.ai/v1/tasks/${taskId}`, { headers }); const task = await res.json(); if (['succeeded', 'failed', 'canceled'].includes(task.status)) { console.log(task); break; } await new Promise((resolve) => setTimeout(resolve, 3000)); } ``` ## Listing & canceling tasks - **List tasks**: `GET /v1/tasks?status=succeeded&model=bytedance/seedance-2.5&limit=20&cursor=...` returns your tasks newest first, across API, Studio, and MCP. Filter with `status`, `model`, and `source`; `limit` is 1–100 (default 20). When `has_more` is `true`, pass `next_cursor` as `cursor` for the next page. - **Cancel a queued task**: `POST /v1/tasks/{id}/cancel` cancels a `queued` task and immediately refunds the hold. If the task is already `running` or finished, the API returns HTTP `409` (`task_not_cancelable`). ## Metadata, timeouts & retention - **Metadata**: Attach up to 4 KB of arbitrary JSON in `metadata` (for example `{"order_id": "A1001"}`); it is returned verbatim on queries and webhooks. - **Timeouts**: Image tasks time out after 10 minutes and video tasks after 60 minutes by default (exact per-model limit is `timeout_seconds` in `GET /v1/models/{id}`). Timed-out tasks fail with `timeout` and refund in full. - **Retention**: Generated files expire 7 days after completion (`expires_at`). Task metadata and ledger entries are kept permanently. --- # Webhooks > Receive push notifications when tasks finish and verify Standard Webhooks HMAC-SHA256 signatures. ## Events & payload Kerox sends an HTTP `POST` request with `Content-Type: application/json` to the task's `webhook_url` (or, when the task has none, the default endpoint URL you set in [Console → API → Webhook](/console/webhooks)) whenever a task reaches a terminal state. Only `https://` URLs are accepted. `data` is the full task object, the same as `GET /v1/tasks/{id}` returns: - `task.succeeded` - `task.failed` - `task.canceled` ```json { "type": "task.succeeded", "created_at": "2026-11-20T08:01:10Z", "data": { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedream-5.5", "status": "succeeded", "source": "api", "format": "native", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "output": { "images": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png", "content_type": "image/png", "width": 2048, "height": 2048 } ] }, "error": null, "cost": { "amount": "0.0280", "currency": "USD", "status": "settled" }, "metadata": { "order_id": "A1001" }, "warnings": [], "created_at": "2026-11-20T08:01:02Z", "started_at": "2026-11-20T08:01:02Z", "completed_at": "2026-11-20T08:01:10Z", "expires_at": "2026-11-27T08:01:10Z" } } ``` ## Signature verification (Standard Webhooks) Every delivery is signed using the [Standard Webhooks](https://www.standardwebhooks.com/) specification and carries three headers. Verifying the signature is optional but recommended: it proves the delivery came from Kerox. | Header | Value | | --- | --- | | `webhook-id` | Unique delivery ID (`msg_...`), unchanged across retries — use it for deduplication | | `webhook-timestamp` | Unix timestamp in seconds when the signature was generated | | `webhook-signature` | One or more `v1,` signatures separated by spaces (two appear during the 24 h key-rotation overlap) | The signed string is `{webhook-id}.{webhook-timestamp}.{raw_body}`, signed with **HMAC-SHA256** using the base64-decoded bytes of your signing secret (shown in [Console → API → Webhook](/console/webhooks)) after stripping the `whsec_` prefix. > **Verify the raw request body** > > Compute the HMAC over the exact UTF-8 bytes received on the wire before parsing or re-serializing JSON. Reject timestamps more than 5 minutes from the current time to prevent replay attacks. ### Verify with the Standard Webhooks SDK ```javascript const wh = new Webhook(process.env.KEROX_WEBHOOK_SECRET); export async function handleKeroxWebhook(rawBody, headers) { // Throws if the signature is invalid or the timestamp is outside the 5-minute window. const event = wh.verify(rawBody, { 'webhook-id': headers['webhook-id'], 'webhook-timestamp': headers['webhook-timestamp'], 'webhook-signature': headers['webhook-signature'], }); console.log(event.type, event.data.id, event.data.status); } ``` ```python import os from standardwebhooks.webhooks import Webhook wh = Webhook(os.environ["KEROX_WEBHOOK_SECRET"]) def handle_kerox_webhook(raw_body: bytes, headers: dict[str, str]): event = wh.verify(raw_body, headers) print(event["type"], event["data"]["id"], event["data"]["status"]) ``` ### Verify manually with built-in crypto ```javascript export function verifyKeroxSignature(rawBody, headers, secret) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signatureHeader = headers['webhook-signature']; if (!id || !timestamp || !signatureHeader) { throw new Error('Missing webhook signature headers'); } const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)); if (!Number.isFinite(ageSeconds) || ageSeconds > 300) { throw new Error('Webhook timestamp outside tolerance'); } const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64'); const expected = crypto .createHmac('sha256', key) .update(`${id}.${timestamp}.${rawBody}`) .digest(); const valid = signatureHeader.split(' ').some((entry) => { const [version, sig] = entry.split(','); if (version !== 'v1' || !sig) return false; const actual = Buffer.from(sig, 'base64'); return actual.length === expected.length && crypto.timingSafeEqual(actual, expected); }); if (!valid) throw new Error('Invalid webhook signature'); return JSON.parse(rawBody); } ``` ```python import base64 import hashlib import hmac import json import time def verify_kerox_signature(raw_body: str, headers: dict[str, str], secret: str): msg_id = headers.get("webhook-id", "") timestamp = headers.get("webhook-timestamp", "") sig_header = headers.get("webhook-signature", "") if not (msg_id and timestamp and sig_header): raise ValueError("Missing webhook signature headers") if abs(int(time.time()) - int(timestamp)) > 300: raise ValueError("Webhook timestamp outside tolerance") key = base64.b64decode(secret.removeprefix("whsec_")) expected = hmac.new( key, f"{msg_id}.{timestamp}.{raw_body}".encode("utf-8"), hashlib.sha256, ).digest() for entry in sig_header.split(" "): parts = entry.split(",", 1) if len(parts) != 2 or parts[0] != "v1": continue if hmac.compare_digest(base64.b64decode(parts[1]), expected): return json.loads(raw_body) raise ValueError("Invalid webhook signature") ``` ## Retries, rotation & best practices - **Success criteria**: Return any HTTP `2xx` within **10 seconds**. Any non-2xx response or timeout counts as failed. - **Retry schedule**: Backoff intervals of `1m, 5m, 15m, 30m, 1h, 2h, 3h, 4h, 4h, 4h, 4h` — up to **12 attempts** over ~24 hours. Deliveries are kept for 7 days, and a failed delivery can be resent from [Console → API → Webhook](/console/webhooks). - **Secret rotation**: Rotating your signing secret in the console keeps the previous secret valid for **24 hours**, during which `webhook-signature` includes both `v1,...` signatures separated by a space. - **Idempotency**: Deduplicate on `webhook-id`, acknowledge with `200` quickly, and process downloads asynchronously. You can always fall back to `GET /v1/tasks/{id}`. --- # Files & inputs > Pass reference images, first frames, videos, or audio via public HTTPS URLs, /v1/files uploads, or small data URIs. ## Three ways to pass media inputs Any file field in `input` (reference images, first/last frames, reference videos, audio) accepts: 1. **Public `https://` URLs** directly reachable by Kerox. 2. **Kerox file URLs** created via `POST /v1/files` (up to **200 MB** per file, retained for **7 days**). 3. **Inline base64 data URIs** (`data:image/png;base64,...`) up to **3 MB total** per request (entire request body must stay ≤ 4 MB). ## Presigned upload (recommended for large files) Send file metadata as JSON to `POST /v1/files`. Kerox returns a presigned `upload_url` (valid for 15 minutes), the `upload_headers` to send with the upload, and the final `url` to pass into `POST /v1/tasks`. `PUT` the file to `upload_url` with those headers. The upload is signed for the `content_type` and `size` you declared, so `size` must be the file's exact size in bytes; a different size or type is refused. ```bash # 1. Request a presigned PUT URL. "size" is the file's exact size in bytes. RESPONSE=$(curl -s -X POST https://api.kerox.ai/v1/files \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"filename\": \"frame.png\", \"content_type\": \"image/png\", \"size\": $(wc -c < frame.png | tr -d ' ') }") printf '%s\n' "$RESPONSE" # 2. Take upload_url from the response and upload the bytes to it UPLOAD_URL=$(printf '%s' "$RESPONSE" | sed -n 's/.*"upload_url": *"\([^"]*\)".*/\1/p') curl -X PUT "$UPLOAD_URL" \ -H "Content-Type: image/png" \ --data-binary @frame.png ``` ```python import os import requests headers = {"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"} with open("frame.png", "rb") as fh: data = fh.read() file_obj = requests.post( "https://api.kerox.ai/v1/files", headers={**headers, "Content-Type": "application/json"}, json={"filename": "frame.png", "content_type": "image/png", "size": len(data)}, timeout=30, ).json() requests.put( file_obj["upload_url"], headers=file_obj["upload_headers"], data=data, timeout=120, ).raise_for_status() print("Use in task input:", file_obj["url"]) ``` ```javascript const data = await fs.readFile('frame.png'); const res = await fetch('https://api.kerox.ai/v1/files', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ filename: 'frame.png', content_type: 'image/png', size: data.byteLength, }), }); const fileObj = await res.json(); const put = await fetch(fileObj.upload_url, { method: 'PUT', headers: fileObj.upload_headers, body: data, }); if (!put.ok) throw new Error(`Upload failed: ${put.status}`); console.log('Use in task input:', fileObj.url); ``` ## Direct multipart upload (≤ 4 MB) For files up to 4 MB, upload in a single `multipart/form-data` request with form field `file`. The response returns `status: "ready"` and the usable `url` immediately. ```bash curl -X POST https://api.kerox.ai/v1/files \ -H "Authorization: Bearer $KEROX_API_KEY" \ -F "file=@frame.png" ``` ## Checking status & retention - Call `GET /v1/files/{id}` to check a presigned upload: `"pending"` until the bytes have arrived, then `"ready"`. - Uploaded files are deleted automatically after **7 days**. - Uploads accept these content types: `image/jpeg`, `image/jpg`, `image/png`, `image/webp`, `image/bmp`, `image/tiff`, `image/gif`, `image/avif`, `image/heic`, `image/heif`, `video/mp4`, `video/quicktime`, `video/webm`, `audio/wav`, `audio/x-wav`, `audio/wave`, `audio/vnd.wave`, `audio/mpeg`, `audio/mp4`. Any other `content_type` returns HTTP `422` (`invalid_parameter`). Each model takes only some of them: check the model's `input_schema` for its format and resolution limits. --- # Unified format > Call supported models with a shared parameter vocabulary while passing model-specific options through unchanged. ## Native vs. unified - **`format: "native"` (default)**: Pass the model maker's own parameter names as documented in `GET /v1/models/{id}` (`input_schema`). - **`format: "unified"`**: Use shared names for high-frequency inputs (`prompt`, `images`, `aspect_ratio`, `resolution`, `duration`, etc.). Any extra native parameter not in the unified map is passed through as-is. If a model has `unified.supported: false`, sending `format: "unified"` returns HTTP `422` (`unified_not_supported`). Not every model takes every unified field. `unified.mapping` in `GET /v1/models/{id}` lists the fields a model accepts and the native parameter each one becomes (the model's page shows the same as a table). A unified field the model does not support returns HTTP `422` (`invalid_parameter`). ## Unified fields | Unified name | Meaning | | --- | --- | | `prompt` / `negative_prompt` | Text prompt / negative prompt | | `images` | Reference image URL or array of URLs | | `videos` / `audios` | Reference video or audio URLs | | `first_frame` / `last_frame` | Video start and end frame URLs | | `aspect_ratio` | `"16:9"`, `"9:16"`, `"1:1"`, `"auto"`, etc. | | `resolution` | `"480p"`, `"720p"`, `"1080p"`, `"2K"`, `"4K"` | | `duration` | Video duration in whole seconds | | `n` | Number of outputs | | `seed` | Random seed | ## Example request In the task response, `task.input` shows the normalized native parameters that were actually executed. ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedream-5.5", "format": "unified", "input": { "prompt": "minimalist studio product photo of a glass kettle on stone", "resolution": "2K", "aspect_ratio": "16:9" } }' ``` ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedream-5.5", "format": "unified", "input": { "prompt": "minimalist studio product photo of a glass kettle on stone", "resolution": "2K", "aspect_ratio": "16:9", }, }, timeout=30, ) print(resp.json()) ``` ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'bytedance/seedream-5.5', format: 'unified', input: { prompt: 'minimalist studio product photo of a glass kettle on stone', resolution: '2K', aspect_ratio: '16:9', }, }), }); console.log(await res.json()); ``` ## Parameter renames & deprecations When a model renames a parameter, Kerox keeps the previous parameter name working for at least **90 days**. During the transition period, responses include a `warnings` entry (`param_renamed`) and a `deprecation` response header. --- # Errors > Standardized HTTP error envelope, complete request error code table, and asynchronous task failure codes. ## Error response shape Every failed HTTP request returns a real HTTP status code together with a unified JSON error object. Always branch on `error.code` rather than `error.message` (messages are English human-readable text and may be refined over time). ```json { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "param": "input.duration", "message": "duration must be -1 or between 4 and 30.", "request_id": "req_01JD8X9C7M8W2N4K6P1Q3R5S7T", "doc_url": "https://kerox.ai/docs/errors#invalid_parameter" } } ``` Every response also carries the `x-request-id` header. Include `request_id` when you contact Support. ## Request error codes Each `doc_url` returned by the API anchors directly to its row below (`#`). | HTTP | `type` | `code` | When it happens | | --- | --- | --- | --- | | 400 | `invalid_request_error` | `invalid_json` | The request body is not valid JSON, or Content-Type is not application/json. | | 400 | `invalid_request_error` | `missing_field` | A required top-level field such as model or input is missing (see param). | | 401 | `authentication_error` | `missing_api_key` | No Authorization: Bearer key header was provided. | | 401 | `authentication_error` | `invalid_api_key` | The API key does not exist or has been revoked. | | 402 | `balance_error` | `insufficient_balance` | Available balance is lower than the estimated cost of this task. | | 402 | `balance_error` | `negative_balance` | The account balance is negative. Top up before submitting new tasks. | | 403 | `permission_error` | `account_disabled` | The account has been disabled. Contact support for help. | | 403 | `permission_error` | `email_not_verified` | Confirm your account email address before submitting generation tasks: sign in to the Console again with an emailed code. | | 404 | `not_found_error` | `route_not_found` | The endpoint path or HTTP method does not exist. | | 404 | `not_found_error` | `model_not_found` | The requested model ID does not exist or is not published. | | 404 | `not_found_error` | `task_not_found` | No task with this ID exists under your account. | | 404 | `not_found_error` | `file_not_found` | No uploaded file with this ID exists under your account. | | 409 | `conflict_error` | `idempotency_conflict` | The same Idempotency-Key was reused with a different request body within 24 hours. | | 409 | `conflict_error` | `task_not_cancelable` | Only queued tasks can be canceled; this task is already running or finished. | | 413 | `invalid_request_error` | `payload_too_large` | Request body exceeds 4 MB, or inline base64 data URIs exceed 3 MB total. Upload via POST /v1/files instead. | | 422 | `invalid_request_error` | `invalid_parameter` | A parameter value failed validation (see param for the field path). | | 422 | `invalid_request_error` | `unknown_parameter` | The model does not recognize this parameter (message suggests the closest valid name). | | 422 | `invalid_request_error` | `unified_not_supported` | This model does not support format: "unified". Use format: "native". | | 422 | `invalid_request_error` | `model_coming_soon` | The model is listed in the catalog as coming soon and is not yet open for submissions. | | 429 | `rate_limit_error` | `rate_limited` | More task submissions or uploads per minute than your account, or your IP address, is allowed. Wait the retry-after seconds before retrying. | | 429 | `rate_limit_error` | `concurrency_limited` | Too many tasks in progress (queued or running). Wait for one to finish, then submit again. | | 500 | `api_error` | `internal_error` | Something went wrong on our side. Retry with an Idempotency-Key, or contact Support with the request_id. | | 503 | `api_error` | `service_unavailable` | The service is temporarily unavailable. Retry after a brief backoff. | ## Task failure codes When a task is accepted (`201`) and later fails during generation, `GET /v1/tasks/{id}` and the `task.failed` webhook return `status: "failed"` with `error: { code, message, retryable }`. Failed tasks are refunded in full (`cost.status: "refunded"`). | `code` | `retryable` | When it happens | | --- | --- | --- | | `content_policy_violation` | `false` | The prompt or an input image/video did not pass content moderation. | | `invalid_input` | `false` | Parameters passed schema checks, but the model rejected the input (for example unsupported dimensions). | | `input_fetch_failed` | `false` | An input media URL could not be downloaded or returned a non-2xx response. | | `generation_failed` | `true` | Generation failed for an unknown reason. Refunded in full. | | `timeout` | `true` | The task exceeded the model maximum timeout without producing a result. | | `model_unavailable` | `true` | The model is temporarily unavailable. Retry after a short wait. | | `internal_error` | `true` | An unexpected error occurred while processing the task. | --- # Idempotency & limits > Safe retries with Idempotency-Key, per-minute rate limits, the cap on tasks in progress, and payload limits. ## Idempotent task creation `POST /v1/tasks` supports an optional `Idempotency-Key` header (up to 255 characters, such as a UUID or your order ID). - **Same key, same body within 24 hours**: Returns the original task object with HTTP `200` (a new task is `201`), without creating a duplicate task or holding balance twice. - **Same key, different body within 24 hours**: Returns HTTP `409` (`idempotency_conflict`). ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-a1001-shot-1" \ -d '{ "model": "bytedance/seedream-5.5", "input": { "prompt": "a quiet coastal lighthouse at dusk", "size": "2K" } }' ``` ```python import os import uuid import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", "Idempotency-Key": str(uuid.uuid4()), }, json={ "model": "bytedance/seedream-5.5", "input": {"prompt": "a quiet coastal lighthouse at dusk", "size": "2K"}, }, timeout=30, ) print(resp.json()) ``` ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID(), }, body: JSON.stringify({ model: 'bytedance/seedream-5.5', input: { prompt: 'a quiet coastal lighthouse at dusk', size: '2K' }, }), }); console.log(await res.json()); ``` ## Rate limits & concurrency `POST /v1/tasks` returns rate-limit headers on every response: | Header | Meaning | | --- | --- | | `x-ratelimit-limit` | Allowed submissions per minute for your account | | `x-ratelimit-remaining` | Remaining submissions in the current window | | `x-ratelimit-reset` | Seconds until the current window resets | | `retry-after` | Seconds to wait, on HTTP `429` `rate_limited` | A second limit caps the tasks you can have in progress at once (`queued` or `running`). Over it, `POST /v1/tasks` returns HTTP `429` `concurrency_limited`: wait for a task to finish, then submit again. Uploads have their own limit: `POST /v1/files` accepts 60 uploads per minute per account. Over it, the response is HTTP `429` `rate_limited` with `retry-after`. A higher per-minute ceiling per IP address also applies to submissions and uploads. `GET /v1/account` shows both task limits (`limits.max_per_minute`, `limits.max_concurrent`) and the number of tasks in progress (`running_tasks`). ## Size limits - **JSON request body**: ≤ 4 MB - **Inline base64 data URIs**: ≤ 3 MB combined per request (use `POST /v1/files` for larger inputs) - **Direct multipart file upload**: ≤ 4 MB - **Presigned file upload (`/v1/files`)**: ≤ 200 MB - **Task `metadata` JSON**: ≤ 4 KB --- # llms.txt > Machine-readable Markdown endpoints for coding agents and LLM context windows. ## Available endpoints Kerox serves every documentation page, model schema, and API definition as plain Markdown or JSON so coding agents can read exact parameters without scraping HTML: | Path | Description | | --- | --- | | `/llms.txt` | Site index linking every guide `.md`, the OpenAPI spec, and every model's `llms.txt` (Chinese: `/zh/llms.txt`) | | `/llms-full.txt` | All guides, error codes, and live model docs concatenated into one file (Chinese: `/zh/llms-full.txt`) | | `/docs/.md` | Plain Markdown version of any documentation page (for example `/docs/quickstart.md`) | | `/zh/docs/.md` | Chinese Markdown version of any documentation page | | `/docs/models.md` | Every model with its current price | | `/models//llms.txt` | Per-model reference with `input_schema`, defaults, live pricing, and code examples (the same text as `/docs/models/.md`) | | `/docs/api.md` | Endpoint list with links to the OpenAPI spec | | `https://api.kerox.ai/openapi.json` | OpenAPI 3.1 machine-readable specification for all `/v1/*` endpoints | ## Using with AI tools - Click **Copy as Markdown** at the top of any documentation page to paste clean Markdown into your prompt. - Use **Open in ChatGPT, Claude…** to start a conversation anchored to the current page's `.md` URL. - Point your coding agent at `https://kerox.ai/llms.txt` (or `https://kerox.ai/llms-full.txt` for single-shot loading). ```bash # Fetch the full site index curl https://kerox.ai/llms.txt # Fetch one model's schema, prices, and examples curl https://kerox.ai/models/bytedance/seedream-5.5/llms.txt ``` --- # MCP server > Connect Claude Code, Cursor, or any MCP client to Kerox over streamable HTTP with your API key. ## Endpoint & authentication Kerox exposes a remote Model Context Protocol (MCP) server over streamable HTTP authenticated with your Bearer API key: - **URL**: `https://api.kerox.ai/mcp` - **Header**: `Authorization: Bearer $KEROX_API_KEY` Tasks created through MCP follow the same pricing and the same hold, settle, and refund rules. They appear in [Console → Tasks](/console/tasks) and in `GET /v1/tasks` with `source: "mcp"`. ## Available tools | Tool | Description | | --- | --- | | `list_models` | List published image and video models with current prices | | `get_model_schema` | Inspect a model's native `input_schema` and unified parameter mapping | | `estimate` | Estimate cost for a candidate task without creating it | | `create_task` | Submit a generation task (pass `idempotency_key` to retry safely) | | `get_task` | Check task status, outputs, cost, or error details | | `list_tasks` | List recent tasks for your account | | `upload_file` | Prepare a reference file upload: returns `upload_url` and `upload_headers` to `PUT` the bytes to, and the `url` to use as input | | `get_balance` | Read your balance, held amount, and limits | ## Client configuration ```json { "mcpServers": { "kerox": { "type": "http", "url": "https://api.kerox.ai/mcp", "headers": { "Authorization": "Bearer ${KEROX_API_KEY}" } } } } ``` --- # Agent Skill > Give coding agents concise, accurate instructions for integrating the Kerox API. ## Install Run this command in the project where you use your coding agent: ```sh npx skills add https://kerox.ai --skill kerox ``` The package includes [SKILL.md](/.well-known/skills/kerox/SKILL.md) and an [MCP configuration template](/.well-known/skills/kerox/mcp.json). For manual installation, save both files under `kerox/` in your client's skills directory. Put your Kerox key in the `KEROX_API_KEY` environment variable. To let your agent call Kerox directly, configure the server using the [MCP setup guide](/docs/mcp). The Skill can also guide REST integration from the documentation. ## What the Kerox Skill includes The Kerox Agent Skill follows the open `SKILL.md` convention so coding agents (Claude Code, Codex, Cursor, and compatible tools) know how to: - Query live model schemas via `GET /v1/models/{id}` or `/models//llms.txt` instead of guessing parameter names. - Estimate costs via `POST /v1/estimate` before submitting tasks. - Submit tasks with `Idempotency-Key`, handle `wait_seconds` vs. polling, and verify Standard Webhooks HMAC-SHA256 signatures. - Map every `error.code` and task failure code cleanly without relying on fragile message matching. ## Working with Markdown docs today You can feed your agent the full Markdown documentation right now: - Index: `https://kerox.ai/llms.txt` - Full reference: `https://kerox.ai/llms-full.txt` - OpenAPI 3.1 schema: `https://api.kerox.ai/openapi.json` --- # Changelog > API releases, model catalog updates, and parameter deprecation notices. ## 2026-11-20 — Public API v0.1 & Docs launch - Launched the Kerox public API (`v0.1`) at `https://api.kerox.ai/v1` with OpenAPI 3.1 (`/openapi.json`). - First models, all by ByteDance. Images: Seedream 5.5 (`bytedance/seedream-5.5`), Seedream 5.0 Pro (`bytedance/seedream-5.0-pro`), Seedream 4.5 (`bytedance/seedream-4.5`), Seedream 4.0 (`bytedance/seedream-4.0`), Seedream 5.0 Lite (`bytedance/seedream-5.0-lite`). Video: Seedance 2.5 (`bytedance/seedance-2.5`), Seedance 2.0 (`bytedance/seedance-2.0`), Seedance 2.0 Fast (`bytedance/seedance-2.0-fast`), Seedance 2.0 Mini (`bytedance/seedance-2.0-mini`). Parameters and prices are on each [model's page](/docs/models). - One task API for every model: `/v1/tasks`, `/v1/estimate`, `/v1/files`, `/v1/models`, `/v1/account`, `/v1/usage`. Native model parameters by default, with an optional unified format. - Wallet billing in USD: the estimate is held when you submit, the actual cost is settled on success, and failed, timed-out, or canceled tasks are refunded in full. - Webhooks for finished tasks, signed with Standard Webhooks (HMAC-SHA256); idempotent task creation with `Idempotency-Key`. - Remote MCP server at `https://api.kerox.ai/mcp` and the Kerox Agent Skill for coding agents. - Published bilingual documentation, interactive API reference, dynamic model pages generated from catalog configuration, `/llms.txt`, `/llms-full.txt`, and per-page `.md` endpoints. - Seedance is billed by tokens and shown as an approx. price per second (converted at 16:9 without a reference video; a lower rate applies to the combined duration with a reference video). --- # API Reference > Kerox public HTTP API (OpenAPI 3.1). One task shape for every image and video model. - **Base URL**: `https://api.kerox.ai/v1` - **OpenAPI 3.1 JSON**: https://api.kerox.ai/openapi.json - **Interactive reference**: https://kerox.ai/docs/api - **Authentication**: `Authorization: Bearer ` ## Endpoints | Method & path | Description | | --- | --- | | `POST /v1/tasks` | Create a generation task (optional wait_seconds up to 60 s) | | `GET /v1/tasks/{id}` | Fetch task status, outputs, cost, and errors | | `GET /v1/tasks` | List tasks with status/model filters and cursor pagination | | `POST /v1/tasks/{id}/cancel` | Cancel a queued task and refund its hold | | `GET /v1/models` | List published models with schemas and live pricing | | `GET /v1/models/{id}` | Fetch a single model config, schema, and pricing | | `POST /v1/estimate` | Estimate task cost without creating a task or holding funds | | `POST /v1/files` | Upload reference files (presigned PUT ≤ 200 MB or multipart ≤ 4 MB) | | `GET /v1/files/{id}` | Check uploaded file status | | `GET /v1/account` | Read wallet balance, holds, rate limits, and concurrency | | `GET /v1/usage` | Query daily and per-model usage and spend | | `GET /openapi.json` | Machine-readable OpenAPI 3.1 specification | | `GET /health` | Health check (no auth required) | --- # Models > All model docs, parameter schemas, and prices are generated live from the model catalog configuration. ## Live pricing overview | Model | ID | Billing | Kerox rate | Notes | | --- | --- | --- | --- | --- | | Seedream 5.5 | `bytedance/seedream-5.5` | Per image | 1K/1.5K: $0.0160, 2K: $0.0280 | Save 20% vs official | | Seedream 5.0 Pro | `bytedance/seedream-5.0-pro` | Per image | 1K/1.5K: $0.0360, 2K: $0.0720 | Save 20% vs official | | Seedream 4.5 | `bytedance/seedream-4.5` | Per image | $0.0320 | Save 20% vs official | | Seedream 4.0 | `bytedance/seedream-4.0` | Per image | $0.0270 | Save 10% vs official | | Seedream 5.0 Lite | `bytedance/seedream-5.0-lite` | Per image | $0.0315 | Save 10% vs official | | Seedance 2.5 | `bytedance/seedance-2.5` | Billed by tokens | Approx. $0.2196 / s (720p) | 16:9 without reference video; lower rate with reference video | | Seedance 2.0 | `bytedance/seedance-2.0` | Billed by tokens | Approx. $0.1436 / s (720p) | 16:9 without reference video; lower rate with reference video | | Seedance 2.0 Fast | `bytedance/seedance-2.0-fast` | Billed by tokens | Approx. $0.0968 / s (720p) | 16:9 without reference video; lower rate with reference video | | Seedance 2.0 Mini | `bytedance/seedance-2.0-mini` | Billed by tokens | Approx. $0.0605 / s (720p) | 16:9 without reference video; lower rate with reference video | ## Model pages - **Seedream 5.5** (`bytedance/seedream-5.5`, ByteDance, image): Seedream 5.5, an image generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedream-5.5.md) | [llms.txt](https://kerox.ai/models/bytedance/seedream-5.5/llms.txt) - **Seedream 5.0 Pro** (`bytedance/seedream-5.0-pro`, ByteDance, image): Seedream 5.0 Pro, an image generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedream-5.0-pro.md) | [llms.txt](https://kerox.ai/models/bytedance/seedream-5.0-pro/llms.txt) - **Seedream 4.5** (`bytedance/seedream-4.5`, ByteDance, image): Seedream 4.5, an image generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedream-4.5.md) | [llms.txt](https://kerox.ai/models/bytedance/seedream-4.5/llms.txt) - **Seedream 4.0** (`bytedance/seedream-4.0`, ByteDance, image): Seedream 4.0, an image generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedream-4.0.md) | [llms.txt](https://kerox.ai/models/bytedance/seedream-4.0/llms.txt) - **Seedream 5.0 Lite** (`bytedance/seedream-5.0-lite`, ByteDance, image): Seedream 5.0 Lite, an image generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedream-5.0-lite.md) | [llms.txt](https://kerox.ai/models/bytedance/seedream-5.0-lite/llms.txt) - **Seedance 2.5** (`bytedance/seedance-2.5`, ByteDance, video): Seedance 2.5, a video generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedance-2.5.md) | [llms.txt](https://kerox.ai/models/bytedance/seedance-2.5/llms.txt) - **Seedance 2.0** (`bytedance/seedance-2.0`, ByteDance, video): Seedance 2.0, a video generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedance-2.0.md) | [llms.txt](https://kerox.ai/models/bytedance/seedance-2.0/llms.txt) - **Seedance 2.0 Fast** (`bytedance/seedance-2.0-fast`, ByteDance, video): Seedance 2.0 Fast, a video generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedance-2.0-fast.md) | [llms.txt](https://kerox.ai/models/bytedance/seedance-2.0-fast/llms.txt) - **Seedance 2.0 Mini** (`bytedance/seedance-2.0-mini`, ByteDance, video): Seedance 2.0 Mini, a video generation model by ByteDance. — [Docs Markdown](https://kerox.ai/docs/models/bytedance/seedance-2.0-mini.md) | [llms.txt](https://kerox.ai/models/bytedance/seedance-2.0-mini/llms.txt) --- # Seedream 5.5 > Seedream 5.5, an image generation model by ByteDance. - **Model ID**: `bytedance/seedream-5.5` - **Maker**: ByteDance - **Type**: image - **Status**: live - **Timeout**: 600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedream-5.5 ## Pricing | Tier | Official / image | Kerox / image | Savings | | --- | --- | --- | --- | | 1K/1.5K | $0.0200 | $0.0160 | 20% | | 2K | $0.0350 | $0.0280 | 20% | - **Tiers**: set by the pixel count (width × height) of each output image: up to 2,601,123 px is `1K/1.5K`; anything larger is `2K`. - **Reference images**: each reference image adds $0.0064 (official $0.0080). ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedream-5.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "wait_seconds": 30 }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedream-5.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K", }, "wait_seconds": 30, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedream-5.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "wait_seconds": 30 }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedream-5.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "wait_seconds": 30 }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `size` | string | `"2K"` | — | Size | | `image` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `watermark` | boolean | `false` | — | Watermark | | `background` | string | `"auto"` | auto, transparent, opaque | Background | | `output_format` | string | `"png"` | png, jpeg | Output format | | `safety_identifier` | string | — | — | End-user ID | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1 | Number of outputs | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `resolution` | string | `"2K"` | 1K, 1.5K, 2K | Resolution | | `aspect_ratio` | string | `"auto"` | — | Aspect ratio | | `watermark` | boolean | `false` | — | Watermark | | `background` | string | `"auto"` | auto, transparent, opaque | Background | | `output_format` | string | `"png"` | png, jpeg | Output format | | `safety_identifier` | string | — | — | End-user ID | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedream-5.5", "status": "succeeded", "output": { "images": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png", "content_type": "image/png", "width": 2048, "height": 2048 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "allOf": [ { "if": { "required": [ "background" ], "properties": { "background": { "const": "transparent" } } }, "then": { "properties": { "output_format": { "const": "png" } } } } ], "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "prompt" ], "properties": { "size": { "type": "string", "x-tier": "common", "default": "2K", "pattern": "^(1K|1\\.5K|2K|[1-9][0-9]*x[1-9][0-9]*)$", "x-label-en": "Size", "x-label-zh": "尺寸", "x-constraints": { "max_aspect": 16, "max_pixels": 4624220, "min_aspect": 0.0625, "min_pixels": 921600 } }, "image": { "oneOf": [ { "type": "string", "pattern": "^(https://|data:image/)" }, { "type": "array", "items": { "type": "string", "pattern": "^(https://|data:image/)" }, "maxItems": 10, "minItems": 1 } ], "x-tier": "common", "x-label-en": "Reference images", "x-label-zh": "参考图" }, "prompt": { "type": "string", "x-tier": "common", "pattern": "\\S", "minLength": 1, "x-label-en": "Prompt", "x-label-zh": "提示词" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "background": { "enum": [ "auto", "transparent", "opaque" ], "type": "string", "x-tier": "common", "default": "auto", "x-label-en": "Background", "x-label-zh": "背景" }, "output_format": { "enum": [ "png", "jpeg" ], "type": "string", "x-tier": "advanced", "default": "png", "x-label-en": "Output format", "x-label-zh": "输出格式" }, "safety_identifier": { "type": "string", "x-tier": "advanced", "pattern": "^[\\x20-\\x7e]+$", "maxLength": 64, "minLength": 1, "x-label-en": "End-user ID", "x-label-zh": "终端用户标识" }, "optimize_prompt_options": { "type": "object", "x-tier": "advanced", "default": { "mode": "standard" }, "properties": { "mode": { "enum": [ "standard" ], "type": "string", "x-tier": "advanced", "default": "standard", "x-label-en": "Mode", "x-label-zh": "模式" } }, "x-label-en": "Prompt optimization", "x-label-zh": "提示词优化", "additionalProperties": false } }, "additionalProperties": false } ``` --- # Seedream 5.0 Pro > Seedream 5.0 Pro, an image generation model by ByteDance. - **Model ID**: `bytedance/seedream-5.0-pro` - **Maker**: ByteDance - **Type**: image - **Status**: live - **Timeout**: 600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedream-5.0-pro ## Pricing | Tier | Official / image | Kerox / image | Savings | | --- | --- | --- | --- | | 1K/1.5K | $0.0450 | $0.0360 | 20% | | 2K | $0.0900 | $0.0720 | 20% | - **Tiers**: set by the pixel count (width × height) of each output image: up to 2,610,000 px is `1K/1.5K`; anything larger is `2K`. - **Reference images**: the first 1 is free; each one after that adds $0.0024 (official $0.0030). ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedream-5.0-pro", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "wait_seconds": 30 }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedream-5.0-pro", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K", }, "wait_seconds": 30, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedream-5.0-pro", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "wait_seconds": 30 }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedream-5.0-pro", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2K" }, "wait_seconds": 30 }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `size` | string | `"2K"` | — | Size | | `image` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `watermark` | boolean | `false` | — | Watermark | | `background` | string | `"opaque"` | transparent, opaque | Background | | `output_format` | string | `"jpeg"` | jpeg, png | Output format | | `safety_identifier` | string | — | — | End-user ID | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1 | Number of outputs | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `resolution` | string | `"2K"` | 1K, 1.5K, 2K | Resolution | | `aspect_ratio` | string | `"auto"` | auto, 1:1, 1:2, 1:3, 2:1, 2:3, 3:1, 3:2, 3:4, 4:3, 4:5, 5:4, 16:9, 21:9, 9:16, 9:21 | Aspect ratio | | `watermark` | boolean | `false` | — | Watermark | | `background` | string | `"opaque"` | transparent, opaque | Background | | `output_format` | string | `"jpeg"` | jpeg, png | Output format | | `safety_identifier` | string | — | — | End-user ID | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedream-5.0-pro", "status": "succeeded", "output": { "images": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png", "content_type": "image/png", "width": 2048, "height": 2048 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "allOf": [ { "if": { "required": [ "background" ], "properties": { "background": { "const": "transparent" } } }, "then": { "required": [ "image" ], "properties": { "image": { "oneOf": [ { "type": "string", "pattern": "^(https://|data:image/)" }, { "type": "array", "maxItems": 1 } ] }, "output_format": { "const": "png" } } } } ], "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "prompt" ], "properties": { "size": { "type": "string", "x-tier": "common", "default": "2K", "pattern": "^(1K|1\\.5K|2K|[1-9][0-9]*x[1-9][0-9]*)$", "x-label-en": "Size", "x-label-zh": "尺寸", "x-constraints": { "max_aspect": 16, "max_pixels": 4624220, "min_aspect": 0.0625, "min_pixels": 921600 } }, "image": { "oneOf": [ { "type": "string", "pattern": "^(https://|data:image/)" }, { "type": "array", "items": { "type": "string", "pattern": "^(https://|data:image/)" }, "maxItems": 10, "minItems": 1 } ], "x-tier": "common", "x-label-en": "Reference images", "x-label-zh": "参考图" }, "prompt": { "type": "string", "x-tier": "common", "pattern": "\\S", "minLength": 1, "x-label-en": "Prompt", "x-label-zh": "提示词" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "background": { "enum": [ "transparent", "opaque" ], "type": "string", "x-tier": "advanced", "default": "opaque", "x-label-en": "Background", "x-label-zh": "背景" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "x-tier": "advanced", "default": "jpeg", "x-label-en": "Output format", "x-label-zh": "输出格式" }, "safety_identifier": { "type": "string", "x-tier": "advanced", "maxLength": 64, "minLength": 1, "x-label-en": "End-user ID", "x-label-zh": "终端用户标识" }, "optimize_prompt_options": { "type": "object", "x-tier": "advanced", "default": { "mode": "standard" }, "properties": { "mode": { "enum": [ "standard", "fast" ], "type": "string", "x-tier": "advanced", "default": "standard", "x-label-en": "Mode", "x-label-zh": "模式" } }, "x-label-en": "Prompt optimization", "x-label-zh": "提示词优化", "additionalProperties": false } }, "additionalProperties": false } ``` --- # Seedream 4.5 > Seedream 4.5, an image generation model by ByteDance. - **Model ID**: `bytedance/seedream-4.5` - **Maker**: ByteDance - **Type**: image - **Status**: live - **Timeout**: 600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedream-4.5 ## Pricing | Tier | Official / image | Kerox / image | Savings | | --- | --- | --- | --- | | Default | $0.0400 | $0.0320 | 20% | - **Image sets**: with image sets on, every generated image is billed at this price, up to 15 per task. The hold covers the most the task may generate; the charge follows the actual count. ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedream-4.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedream-4.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048", }, "wait_seconds": 30, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedream-4.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedream-4.5", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `size` | string | `"2048x2048"` | — | Size | | `image` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `watermark` | boolean | `false` | — | Watermark | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | | `sequential_image_generation` | string | `"disabled"` | auto, disabled | Image set mode | | `sequential_image_generation_options` | object | — | — | Image set options | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1–15 | Number of outputs | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `resolution` | string | `"2K"` | 2K, 4K | Resolution | | `aspect_ratio` | string | `"auto"` | auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 16:9, 21:9, 9:16, 9:21 | Aspect ratio | | `watermark` | boolean | `false` | — | Watermark | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | | `sequential_image_generation_options` | object | — | — | Image set options | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedream-4.5", "status": "succeeded", "output": { "images": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png", "content_type": "image/png", "width": 2048, "height": 2048 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "prompt" ], "properties": { "size": { "type": "string", "x-tier": "common", "default": "2048x2048", "pattern": "^(2K|4K|[1-9][0-9]*x[1-9][0-9]*)$", "x-label-en": "Size", "x-label-zh": "尺寸", "x-constraints": { "max_aspect": 16, "max_pixels": 16777216, "min_aspect": 0.0625, "min_pixels": 3686400 } }, "image": { "oneOf": [ { "type": "string", "pattern": "^(https://|data:image/)" }, { "type": "array", "items": { "type": "string", "pattern": "^(https://|data:image/)" }, "maxItems": 14, "minItems": 1 } ], "x-tier": "common", "x-label-en": "Reference images", "x-label-zh": "参考图" }, "prompt": { "type": "string", "x-tier": "common", "pattern": "\\S", "minLength": 1, "x-label-en": "Prompt", "x-label-zh": "提示词" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "optimize_prompt_options": { "type": "object", "x-tier": "advanced", "default": { "mode": "standard" }, "properties": { "mode": { "enum": [ "standard" ], "type": "string", "x-tier": "advanced", "default": "standard", "x-label-en": "Mode", "x-label-zh": "模式" } }, "x-label-en": "Prompt optimization", "x-label-zh": "提示词优化", "additionalProperties": false }, "sequential_image_generation": { "enum": [ "auto", "disabled" ], "type": "string", "x-tier": "advanced", "default": "disabled", "x-label-en": "Image set mode", "x-label-zh": "顺序组图" }, "sequential_image_generation_options": { "type": "object", "x-tier": "advanced", "properties": { "max_images": { "type": "integer", "x-tier": "advanced", "default": 15, "maximum": 15, "minimum": 1, "x-label-en": "Max images", "x-label-zh": "最多张数" } }, "x-label-en": "Image set options", "x-label-zh": "组图选项", "additionalProperties": false } }, "additionalProperties": false } ``` --- # Seedream 4.0 > Seedream 4.0, an image generation model by ByteDance. - **Model ID**: `bytedance/seedream-4.0` - **Maker**: ByteDance - **Type**: image - **Status**: live - **Timeout**: 600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedream-4.0 ## Pricing | Tier | Official / image | Kerox / image | Savings | | --- | --- | --- | --- | | Default | $0.0300 | $0.0270 | 10% | - **Image sets**: with image sets on, every generated image is billed at this price, up to 15 per task. The hold covers the most the task may generate; the charge follows the actual count. ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedream-4.0", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedream-4.0", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048", }, "wait_seconds": 30, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedream-4.0", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedream-4.0", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `size` | string | `"2048x2048"` | — | Size | | `image` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `watermark` | boolean | `false` | — | Watermark | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | | `sequential_image_generation` | string | `"disabled"` | auto, disabled | Image set mode | | `sequential_image_generation_options` | object | — | — | Image set options | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1–15 | Number of outputs | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `resolution` | string | `"2K"` | 1K, 2K, 4K | Resolution | | `aspect_ratio` | string | `"auto"` | auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 16:9, 21:9, 9:16, 9:21 | Aspect ratio | | `watermark` | boolean | `false` | — | Watermark | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | | `sequential_image_generation_options` | object | — | — | Image set options | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedream-4.0", "status": "succeeded", "output": { "images": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png", "content_type": "image/png", "width": 2048, "height": 2048 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "prompt" ], "properties": { "size": { "type": "string", "x-tier": "common", "default": "2048x2048", "pattern": "^(1K|2K|4K|[1-9][0-9]*x[1-9][0-9]*)$", "x-label-en": "Size", "x-label-zh": "尺寸", "x-constraints": { "max_aspect": 16, "max_pixels": 16777216, "min_aspect": 0.0625, "min_pixels": 921600 } }, "image": { "oneOf": [ { "type": "string", "pattern": "^(https://|data:image/)" }, { "type": "array", "items": { "type": "string", "pattern": "^(https://|data:image/)" }, "maxItems": 14, "minItems": 1 } ], "x-tier": "common", "x-label-en": "Reference images", "x-label-zh": "参考图" }, "prompt": { "type": "string", "x-tier": "common", "pattern": "\\S", "minLength": 1, "x-label-en": "Prompt", "x-label-zh": "提示词" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "optimize_prompt_options": { "type": "object", "x-tier": "advanced", "default": { "mode": "standard" }, "properties": { "mode": { "enum": [ "standard", "fast" ], "type": "string", "x-tier": "advanced", "default": "standard", "x-label-en": "Mode", "x-label-zh": "模式" } }, "x-label-en": "Prompt optimization", "x-label-zh": "提示词优化", "additionalProperties": false }, "sequential_image_generation": { "enum": [ "auto", "disabled" ], "type": "string", "x-tier": "advanced", "default": "disabled", "x-label-en": "Image set mode", "x-label-zh": "顺序组图" }, "sequential_image_generation_options": { "type": "object", "x-tier": "advanced", "properties": { "max_images": { "type": "integer", "x-tier": "advanced", "default": 15, "maximum": 15, "minimum": 1, "x-label-en": "Max images", "x-label-zh": "最多张数" } }, "x-label-en": "Image set options", "x-label-zh": "组图选项", "additionalProperties": false } }, "additionalProperties": false } ``` --- # Seedream 5.0 Lite > Seedream 5.0 Lite, an image generation model by ByteDance. - **Model ID**: `bytedance/seedream-5.0-lite` - **Maker**: ByteDance - **Type**: image - **Status**: live - **Timeout**: 600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedream-5.0-lite ## Pricing | Tier | Official / image | Kerox / image | Savings | | --- | --- | --- | --- | | Default | $0.0350 | $0.0315 | 10% | - **Image sets**: with image sets on, every generated image is billed at this price, up to 15 per task. The hold covers the most the task may generate; the charge follows the actual count. ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedream-5.0-lite", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedream-5.0-lite", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048", }, "wait_seconds": 30, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedream-5.0-lite", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedream-5.0-lite", "input": { "prompt": "editorial portrait of a ceramicist in morning sunlight, 35mm film", "size": "2048x2048" }, "wait_seconds": 30 }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `size` | string | `"2048x2048"` | — | Size | | `image` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `watermark` | boolean | `false` | — | Watermark | | `output_format` | string | `"jpeg"` | jpeg, png | Output format | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | | `sequential_image_generation` | string | `"disabled"` | auto, disabled | Image set mode | | `sequential_image_generation_options` | object | — | — | Image set options | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1–15 | Number of outputs | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `resolution` | string | `"2K"` | 2K, 3K, 4K | Resolution | | `aspect_ratio` | string | `"auto"` | auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 16:9, 21:9, 9:16, 9:21 | Aspect ratio | | `watermark` | boolean | `false` | — | Watermark | | `output_format` | string | `"jpeg"` | jpeg, png | Output format | | `optimize_prompt_options` | object | `{"mode":"standard"}` | — | Prompt optimization | | `sequential_image_generation_options` | object | — | — | Image set options | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedream-5.0-lite", "status": "succeeded", "output": { "images": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.png", "content_type": "image/png", "width": 2048, "height": 2048 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "prompt" ], "properties": { "size": { "type": "string", "x-tier": "common", "default": "2048x2048", "pattern": "^(2K|3K|4K|[1-9][0-9]*x[1-9][0-9]*)$", "x-label-en": "Size", "x-label-zh": "尺寸", "x-constraints": { "max_aspect": 16, "max_pixels": 16777216, "min_aspect": 0.0625, "min_pixels": 3686400 } }, "image": { "oneOf": [ { "type": "string", "pattern": "^(https://|data:image/)" }, { "type": "array", "items": { "type": "string", "pattern": "^(https://|data:image/)" }, "maxItems": 14, "minItems": 1 } ], "x-tier": "common", "x-label-en": "Reference images", "x-label-zh": "参考图" }, "prompt": { "type": "string", "x-tier": "common", "pattern": "\\S", "minLength": 1, "x-label-en": "Prompt", "x-label-zh": "提示词" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "x-tier": "advanced", "default": "jpeg", "x-label-en": "Output format", "x-label-zh": "输出格式" }, "optimize_prompt_options": { "type": "object", "x-tier": "advanced", "default": { "mode": "standard" }, "properties": { "mode": { "enum": [ "standard" ], "type": "string", "x-tier": "advanced", "default": "standard", "x-label-en": "Mode", "x-label-zh": "模式" } }, "x-label-en": "Prompt optimization", "x-label-zh": "提示词优化", "additionalProperties": false }, "sequential_image_generation": { "enum": [ "auto", "disabled" ], "type": "string", "x-tier": "advanced", "default": "disabled", "x-label-en": "Image set mode", "x-label-zh": "顺序组图" }, "sequential_image_generation_options": { "type": "object", "x-tier": "advanced", "properties": { "max_images": { "type": "integer", "x-tier": "advanced", "default": 15, "maximum": 15, "minimum": 1, "x-label-en": "Max images", "x-label-zh": "最多张数" } }, "x-label-en": "Image set options", "x-label-zh": "组图选项", "additionalProperties": false } }, "additionalProperties": false } ``` --- # Seedance 2.5 > Seedance 2.5, a video generation model by ByteDance. - **Model ID**: `bytedance/seedance-2.5` - **Maker**: ByteDance - **Type**: video - **Status**: live - **Timeout**: 3600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedance-2.5 ## Pricing **Billed by tokens.** The approx. per-second prices below are converted at 16:9: 720p without a reference video is approx. $0.2196 / s. | Resolution | Without reference video (approx. / s) | With reference video (approx. / s) | Official / 1M tokens | Kerox / 1M tokens | With reference video: official / 1M tokens | With reference video: Kerox / 1M tokens | | --- | --- | --- | --- | --- | --- | --- | | 480p | $0.0977 | $0.0584 | $10.7000 | $10.1650 | $6.4000 | $6.0800 | | 720p | $0.2196 | $0.1313 | $10.7000 | $10.1650 | $6.4000 | $6.0800 | | 1080p | $0.5402 | $0.3232 | $11.7000 | $11.1150 | $7.0000 | $6.6500 | - **Token formula**: `tokens = (output seconds + reference video seconds) × width × height × 24 / 1024`. With a reference video, the lower rate applies to the combined duration (output plus reference video). - **Aspect ratio and audio**: approx. per-second prices are converted at 16:9 without a reference video. Other aspect ratios at the same resolution differ by under 5%, and audio does not change the price. - **Estimate before you submit**: call `POST /v1/estimate`, or check Studio, for the estimated cost of your exact parameters. ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedance-2.5", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedance-2.5", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting", }, ], "resolution": "720p", "duration": 5, }, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedance-2.5", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedance-2.5", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `content` | array | — | — | Content | | `duration` | integer | `5` | -1, 4–30 | Duration | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `resolution` | string | `"720p"` | 480p, 720p, 1080p | Resolution | | `service_tier` | string | `"default"` | default | Service tier | | `output_format` | string | `"mp4"` | mp4, mov | Container | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | | `omni_reference_task_type` | string | `"auto"` | auto, reference, edit, extend | Reference task | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1 | Number of outputs | | `audios` | string \| string[] | — | — | Reference audio | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `videos` | string \| string[] | — | — | Reference videos | | `duration` | integer | `5` | -1, 4–30 | Duration | | `last_frame` | string | — | — | Last frame | | `resolution` | string | `"720p"` | 480p, 720p, 1080p | Resolution | | `first_frame` | string | — | — | First frame | | `aspect_ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `service_tier` | string | `"default"` | default | Service tier | | `output_format` | string | `"mp4"` | mp4, mov | Container | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | | `omni_reference_task_type` | string | `"auto"` | auto, reference, edit, extend | Reference task | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedance-2.5", "status": "succeeded", "output": { "videos": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.mp4", "content_type": "video/mp4", "width": 1280, "height": 720, "duration": 5 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "allOf": [ { "if": { "required": [ "omni_reference_task_type" ], "properties": { "omni_reference_task_type": { "const": "edit" } } }, "then": { "required": [ "duration" ], "x-message": "duration must be -1 when omni_reference_task_type is edit.", "properties": { "ratio": { "const": "adaptive", "x-message": "ratio must be adaptive when omni_reference_task_type is edit." }, "content": { "contains": { "required": [ "type" ], "properties": { "type": { "const": "video_url" } } }, "x-message": "content must have exactly one reference video when omni_reference_task_type is edit.", "maxContains": 1, "minContains": 1 }, "duration": { "const": -1, "x-message": "duration must be -1 when omni_reference_task_type is edit." } } } }, { "if": { "required": [ "omni_reference_task_type" ], "properties": { "omni_reference_task_type": { "const": "extend" } } }, "then": { "properties": { "ratio": { "const": "adaptive", "x-message": "ratio must be adaptive when omni_reference_task_type is extend." }, "content": { "contains": { "required": [ "type" ], "properties": { "type": { "const": "video_url" } } }, "x-message": "content must have at least one reference video when omni_reference_task_type is extend.", "minContains": 1 } } } }, { "if": { "required": [ "content" ], "properties": { "content": { "contains": { "anyOf": [ { "not": { "required": [ "role" ], "properties": { "role": true } } }, { "required": [ "role" ], "properties": { "role": { "const": "first_frame" } } } ], "required": [ "type" ], "properties": { "type": { "const": "image_url" } } } } } }, "then": { "properties": { "ratio": { "const": "adaptive", "x-message": "ratio must be adaptive for first-frame image-to-video." } } } } ], "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "content" ], "properties": { "ratio": { "enum": [ "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16" ], "type": "string", "x-tier": "common", "default": "adaptive", "x-label-en": "Aspect ratio", "x-label-zh": "画面比例" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Text", "required": [ "type", "text" ], "properties": { "text": { "type": "string", "maxLength": 10000, "minLength": 1 }, "type": { "const": "text" } }, "additionalProperties": false }, { "type": "object", "title": "Image", "required": [ "type", "image_url" ], "properties": { "role": { "enum": [ "first_frame", "last_frame", "reference_image" ], "type": "string" }, "type": { "const": "image_url" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:image/)" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Video", "required": [ "type", "video_url", "role" ], "properties": { "role": { "const": "reference_video" }, "type": { "const": "video_url" }, "video_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^https://" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Audio", "required": [ "type", "audio_url", "role" ], "properties": { "role": { "const": "reference_audio" }, "type": { "const": "audio_url" }, "audio_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:audio/)" } }, "additionalProperties": false } }, "additionalProperties": false } ] }, "x-tier": "common", "minItems": 1, "x-label-en": "Content", "x-label-zh": "输入内容", "x-constraints": { "max_text_items": 1, "audio_only_allowed": true, "max_reference_audios": 10, "max_reference_images": 30, "max_reference_videos": 10, "first_last_frame_exclusive_with_references": true } }, "duration": { "type": "integer", "anyOf": [ { "const": -1 }, { "maximum": 30, "minimum": 4 } ], "x-tier": "common", "default": 5, "x-label-en": "Duration", "x-label-zh": "时长" }, "priority": { "type": "integer", "x-tier": "advanced", "maximum": 9, "minimum": 0, "x-label-en": "Queue priority", "x-label-zh": "排队优先级" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "resolution": { "enum": [ "480p", "720p", "1080p" ], "type": "string", "x-tier": "common", "default": "720p", "x-label-en": "Resolution", "x-label-zh": "分辨率" }, "service_tier": { "enum": [ "default" ], "type": "string", "x-tier": "advanced", "default": "default", "x-label-en": "Service tier", "x-label-zh": "服务档位" }, "output_format": { "enum": [ "mp4", "mov" ], "type": "string", "x-tier": "advanced", "default": "mp4", "x-label-en": "Container", "x-label-zh": "封装格式" }, "generate_audio": { "type": "boolean", "x-tier": "common", "default": true, "x-label-en": "Generate audio", "x-label-zh": "生成声音" }, "return_last_frame": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Return last frame", "x-label-zh": "返回尾帧" }, "safety_identifier": { "type": "string", "x-tier": "advanced", "maxLength": 64, "x-label-en": "End-user ID", "x-label-zh": "终端用户标识" }, "omni_reference_task_type": { "enum": [ "auto", "reference", "edit", "extend" ], "type": "string", "x-tier": "advanced", "default": "auto", "x-label-en": "Reference task", "x-label-zh": "参考任务类型" } }, "additionalProperties": false } ``` --- # Seedance 2.0 > Seedance 2.0, a video generation model by ByteDance. - **Model ID**: `bytedance/seedance-2.0` - **Maker**: ByteDance - **Type**: video - **Status**: live - **Timeout**: 3600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedance-2.0 ## Pricing **Billed by tokens.** The approx. per-second prices below are converted at 16:9: 720p without a reference video is approx. $0.1436 / s. | Resolution | Without reference video (approx. / s) | With reference video (approx. / s) | Official / 1M tokens | Kerox / 1M tokens | With reference video: official / 1M tokens | With reference video: Kerox / 1M tokens | | --- | --- | --- | --- | --- | --- | --- | | 4k | $0.7387 | $0.4432 | $4.0000 | $3.8000 | $2.4000 | $2.2800 | | 480p | $0.0668 | $0.0410 | $7.0000 | $6.6500 | $4.3000 | $4.0850 | | 720p | $0.1436 | $0.0882 | $7.0000 | $6.6500 | $4.3000 | $4.0850 | | 1080p | $0.3555 | $0.2170 | $7.7000 | $7.3150 | $4.7000 | $4.4650 | - **Token formula**: `tokens = (output seconds + reference video seconds) × width × height × 24 / 1024`. With a reference video, the lower rate applies to the combined duration (output plus reference video). - **Aspect ratio and audio**: approx. per-second prices are converted at 16:9 without a reference video. Other aspect ratios at the same resolution differ by under 5%, and audio does not change the price. - **Estimate before you submit**: call `POST /v1/estimate`, or check Studio, for the estimated cost of your exact parameters. ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedance-2.0", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedance-2.0", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting", }, ], "resolution": "720p", "duration": 5, }, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedance-2.0", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedance-2.0", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `content` | array | — | — | Content | | `duration` | integer | `5` | -1, 4–15 | Duration | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `resolution` | string | `"720p"` | 480p, 720p, 1080p, 4k | Resolution | | `service_tier` | string | `"default"` | default | Service tier | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1 | Number of outputs | | `audios` | string \| string[] | — | — | Reference audio | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `videos` | string \| string[] | — | — | Reference videos | | `duration` | integer | `5` | -1, 4–15 | Duration | | `last_frame` | string | — | — | Last frame | | `resolution` | string | `"720p"` | 480p, 720p, 1080p, 4k | Resolution | | `first_frame` | string | — | — | First frame | | `aspect_ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `service_tier` | string | `"default"` | default | Service tier | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedance-2.0", "status": "succeeded", "output": { "videos": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.mp4", "content_type": "video/mp4", "width": 1280, "height": 720, "duration": 5 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "content" ], "properties": { "ratio": { "enum": [ "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16" ], "type": "string", "x-tier": "common", "default": "adaptive", "x-label-en": "Aspect ratio", "x-label-zh": "画面比例" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Text", "required": [ "type", "text" ], "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "const": "text" } }, "additionalProperties": false }, { "type": "object", "title": "Image", "required": [ "type", "image_url" ], "properties": { "role": { "enum": [ "first_frame", "last_frame", "reference_image" ], "type": "string" }, "type": { "const": "image_url" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:image/)" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Video", "required": [ "type", "video_url", "role" ], "properties": { "role": { "const": "reference_video" }, "type": { "const": "video_url" }, "video_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^https://" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Audio", "required": [ "type", "audio_url", "role" ], "properties": { "role": { "const": "reference_audio" }, "type": { "const": "audio_url" }, "audio_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:audio/)" } }, "additionalProperties": false } }, "additionalProperties": false } ] }, "x-tier": "common", "minItems": 1, "x-label-en": "Content", "x-label-zh": "输入内容", "x-constraints": { "max_text_items": 1, "audio_only_allowed": false, "max_reference_audios": 3, "max_reference_images": 9, "max_reference_videos": 3, "first_last_frame_exclusive_with_references": true } }, "duration": { "type": "integer", "anyOf": [ { "const": -1 }, { "maximum": 15, "minimum": 4 } ], "x-tier": "common", "default": 5, "x-label-en": "Duration", "x-label-zh": "时长" }, "priority": { "type": "integer", "x-tier": "advanced", "maximum": 9, "minimum": 0, "x-label-en": "Queue priority", "x-label-zh": "排队优先级" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "resolution": { "enum": [ "480p", "720p", "1080p", "4k" ], "type": "string", "x-tier": "common", "default": "720p", "x-label-en": "Resolution", "x-label-zh": "分辨率" }, "service_tier": { "enum": [ "default" ], "type": "string", "x-tier": "advanced", "default": "default", "x-label-en": "Service tier", "x-label-zh": "服务档位" }, "generate_audio": { "type": "boolean", "x-tier": "common", "default": true, "x-label-en": "Generate audio", "x-label-zh": "生成声音" }, "return_last_frame": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Return last frame", "x-label-zh": "返回尾帧" }, "safety_identifier": { "type": "string", "x-tier": "advanced", "maxLength": 64, "x-label-en": "End-user ID", "x-label-zh": "终端用户标识" } }, "additionalProperties": false } ``` --- # Seedance 2.0 Fast > Seedance 2.0 Fast, a video generation model by ByteDance. - **Model ID**: `bytedance/seedance-2.0-fast` - **Maker**: ByteDance - **Type**: video - **Status**: live - **Timeout**: 3600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedance-2.0-fast ## Pricing **Billed by tokens.** The approx. per-second prices below are converted at 16:9: 720p without a reference video is approx. $0.0968 / s. | Resolution | Without reference video (approx. / s) | With reference video (approx. / s) | Official / 1M tokens | Kerox / 1M tokens | With reference video: official / 1M tokens | With reference video: Kerox / 1M tokens | | --- | --- | --- | --- | --- | --- | --- | | 480p | $0.0450 | $0.0265 | $5.6000 | $4.4800 | $3.3000 | $2.6400 | | 720p | $0.0968 | $0.0570 | $5.6000 | $4.4800 | $3.3000 | $2.6400 | - **Token formula**: `tokens = (output seconds + reference video seconds) × width × height × 24 / 1024`. With a reference video, the lower rate applies to the combined duration (output plus reference video). - **Aspect ratio and audio**: approx. per-second prices are converted at 16:9 without a reference video. Other aspect ratios at the same resolution differ by under 5%, and audio does not change the price. - **Estimate before you submit**: call `POST /v1/estimate`, or check Studio, for the estimated cost of your exact parameters. ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedance-2.0-fast", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedance-2.0-fast", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting", }, ], "resolution": "720p", "duration": 5, }, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedance-2.0-fast", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedance-2.0-fast", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `content` | array | — | — | Content | | `duration` | integer | `5` | -1, 4–15 | Duration | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `resolution` | string | `"720p"` | 480p, 720p | Resolution | | `service_tier` | string | `"default"` | default | Service tier | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1 | Number of outputs | | `audios` | string \| string[] | — | — | Reference audio | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `videos` | string \| string[] | — | — | Reference videos | | `duration` | integer | `5` | -1, 4–15 | Duration | | `last_frame` | string | — | — | Last frame | | `resolution` | string | `"720p"` | 480p, 720p | Resolution | | `first_frame` | string | — | — | First frame | | `aspect_ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `service_tier` | string | `"default"` | default | Service tier | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedance-2.0-fast", "status": "succeeded", "output": { "videos": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.mp4", "content_type": "video/mp4", "width": 1280, "height": 720, "duration": 5 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "content" ], "properties": { "ratio": { "enum": [ "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16" ], "type": "string", "x-tier": "common", "default": "adaptive", "x-label-en": "Aspect ratio", "x-label-zh": "画面比例" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Text", "required": [ "type", "text" ], "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "const": "text" } }, "additionalProperties": false }, { "type": "object", "title": "Image", "required": [ "type", "image_url" ], "properties": { "role": { "enum": [ "first_frame", "last_frame", "reference_image" ], "type": "string" }, "type": { "const": "image_url" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:image/)" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Video", "required": [ "type", "video_url", "role" ], "properties": { "role": { "const": "reference_video" }, "type": { "const": "video_url" }, "video_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^https://" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Audio", "required": [ "type", "audio_url", "role" ], "properties": { "role": { "const": "reference_audio" }, "type": { "const": "audio_url" }, "audio_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:audio/)" } }, "additionalProperties": false } }, "additionalProperties": false } ] }, "x-tier": "common", "minItems": 1, "x-label-en": "Content", "x-label-zh": "输入内容", "x-constraints": { "max_text_items": 1, "audio_only_allowed": false, "max_reference_audios": 3, "max_reference_images": 9, "max_reference_videos": 3, "first_last_frame_exclusive_with_references": true } }, "duration": { "type": "integer", "anyOf": [ { "const": -1 }, { "maximum": 15, "minimum": 4 } ], "x-tier": "common", "default": 5, "x-label-en": "Duration", "x-label-zh": "时长" }, "priority": { "type": "integer", "x-tier": "advanced", "maximum": 9, "minimum": 0, "x-label-en": "Queue priority", "x-label-zh": "排队优先级" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "resolution": { "enum": [ "480p", "720p" ], "type": "string", "x-tier": "common", "default": "720p", "x-label-en": "Resolution", "x-label-zh": "分辨率" }, "service_tier": { "enum": [ "default" ], "type": "string", "x-tier": "advanced", "default": "default", "x-label-en": "Service tier", "x-label-zh": "服务档位" }, "generate_audio": { "type": "boolean", "x-tier": "common", "default": true, "x-label-en": "Generate audio", "x-label-zh": "生成声音" }, "return_last_frame": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Return last frame", "x-label-zh": "返回尾帧" }, "safety_identifier": { "type": "string", "x-tier": "advanced", "maxLength": 64, "x-label-en": "End-user ID", "x-label-zh": "终端用户标识" } }, "additionalProperties": false } ``` --- # Seedance 2.0 Mini > Seedance 2.0 Mini, a video generation model by ByteDance. - **Model ID**: `bytedance/seedance-2.0-mini` - **Maker**: ByteDance - **Type**: video - **Status**: live - **Timeout**: 3600 s - **Unified format**: Supported - **Endpoint**: `POST https://api.kerox.ai/v1/tasks` - **Model page**: https://kerox.ai/models/bytedance/seedance-2.0-mini ## Pricing **Billed by tokens.** The approx. per-second prices below are converted at 16:9: 720p without a reference video is approx. $0.0605 / s. | Resolution | Without reference video (approx. / s) | With reference video (approx. / s) | Official / 1M tokens | Kerox / 1M tokens | With reference video: official / 1M tokens | With reference video: Kerox / 1M tokens | | --- | --- | --- | --- | --- | --- | --- | | 480p | $0.0281 | $0.0169 | $3.5000 | $2.8000 | $2.1000 | $1.6800 | | 720p | $0.0605 | $0.0363 | $3.5000 | $2.8000 | $2.1000 | $1.6800 | - **Token formula**: `tokens = (output seconds + reference video seconds) × width × height × 24 / 1024`. With a reference video, the lower rate applies to the combined duration (output plus reference video). - **Aspect ratio and audio**: approx. per-second prices are converted at 16:9 without a reference video. Other aspect ratios at the same resolution differ by under 5%, and audio does not change the price. - **Estimate before you submit**: call `POST /v1/estimate`, or check Studio, for the estimated cost of your exact parameters. ## Request example Submit a task with the model's native parameters. ### cURL ```bash curl -X POST https://api.kerox.ai/v1/tasks \ -H "Authorization: Bearer $KEROX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bytedance/seedance-2.0-mini", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }' ``` ### Python ```python import os import requests resp = requests.post( "https://api.kerox.ai/v1/tasks", headers={ "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "bytedance/seedance-2.0-mini", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting", }, ], "resolution": "720p", "duration": 5, }, }, timeout=60, ) resp.raise_for_status() task = resp.json() print(task["id"], task["status"], task["output"]) ``` ### Node.js ```javascript const res = await fetch('https://api.kerox.ai/v1/tasks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "model": "bytedance/seedance-2.0-mini", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }), }); const task = await res.json(); console.log(task.id, task.status, task.output); ``` ### Go ```go package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { body := []byte(`{ "model": "bytedance/seedance-2.0-mini", "input": { "content": [ { "type": "text", "text": "a red fox running through fresh snow, cinematic lighting" } ], "resolution": "720p", "duration": 5 } }`) req, _ := http.NewRequest("POST", "https://api.kerox.ai/v1/tasks", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("KEROX_API_KEY")) req.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() out, _ := io.ReadAll(resp.Body) fmt.Println(string(out)) } ``` ## Parameters (native format) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `content` | array | — | — | Content | | `duration` | integer | `5` | -1, 4–15 | Duration | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `resolution` | string | `"720p"` | 480p, 720p | Resolution | | `service_tier` | string | `"default"` | default | Service tier | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | ## Parameters (unified format, `format: "unified"`) | Parameter | Type | Default | Values | Description | | --- | --- | --- | --- | --- | | `n` | integer | `1` | 1 | Number of outputs | | `audios` | string \| string[] | — | — | Reference audio | | `images` | string \| string[] | — | — | Reference images | | `prompt` | string | — | — | Prompt | | `videos` | string \| string[] | — | — | Reference videos | | `duration` | integer | `5` | -1, 4–15 | Duration | | `last_frame` | string | — | — | Last frame | | `resolution` | string | `"720p"` | 480p, 720p | Resolution | | `first_frame` | string | — | — | First frame | | `aspect_ratio` | string | `"adaptive"` | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | Aspect ratio | | `priority` | integer | — | 0–9 | Queue priority | | `watermark` | boolean | `false` | — | Watermark | | `service_tier` | string | `"default"` | default | Service tier | | `generate_audio` | boolean | `true` | — | Generate audio | | `return_last_frame` | boolean | `false` | — | Return last frame | | `safety_identifier` | string | — | — | End-user ID | ## Polling and output Poll `GET /v1/tasks/{id}` or receive a webhook when the task finishes. Output files expire at `expires_at` (7 days after completion), so download anything you want to keep. The other fields of the task object are in the tasks guide and the API reference. ```bash curl https://api.kerox.ai/v1/tasks/task_01JD8X9B4Q2M7T8N3K5P6R1S0V \ -H "Authorization: Bearer $KEROX_API_KEY" ``` ```json { "id": "task_01JD8X9B4Q2M7T8N3K5P6R1S0V", "object": "task", "model": "bytedance/seedance-2.0-mini", "status": "succeeded", "output": { "videos": [ { "url": "https://cdn.kerox.ai/t/task_01JD8X9B4Q2M7T8N3K5P6R1S0V/5f2b8c1e9d3a4f6b8a7c0d1e2f3a4b5c/0.mp4", "content_type": "video/mp4", "width": 1280, "height": 720, "duration": 5 } ] }, "error": null, "expires_at": "2026-11-27T08:01:10Z" } ``` ## Input schema (JSON) ```json { "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "required": [ "content" ], "properties": { "ratio": { "enum": [ "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16" ], "type": "string", "x-tier": "common", "default": "adaptive", "x-label-en": "Aspect ratio", "x-label-zh": "画面比例" }, "content": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Text", "required": [ "type", "text" ], "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "const": "text" } }, "additionalProperties": false }, { "type": "object", "title": "Image", "required": [ "type", "image_url" ], "properties": { "role": { "enum": [ "first_frame", "last_frame", "reference_image" ], "type": "string" }, "type": { "const": "image_url" }, "image_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:image/)" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Video", "required": [ "type", "video_url", "role" ], "properties": { "role": { "const": "reference_video" }, "type": { "const": "video_url" }, "video_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^https://" } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "object", "title": "Audio", "required": [ "type", "audio_url", "role" ], "properties": { "role": { "const": "reference_audio" }, "type": { "const": "audio_url" }, "audio_url": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^(https://|data:audio/)" } }, "additionalProperties": false } }, "additionalProperties": false } ] }, "x-tier": "common", "minItems": 1, "x-label-en": "Content", "x-label-zh": "输入内容", "x-constraints": { "max_text_items": 1, "audio_only_allowed": false, "max_reference_audios": 3, "max_reference_images": 9, "max_reference_videos": 3, "first_last_frame_exclusive_with_references": true } }, "duration": { "type": "integer", "anyOf": [ { "const": -1 }, { "maximum": 15, "minimum": 4 } ], "x-tier": "common", "default": 5, "x-label-en": "Duration", "x-label-zh": "时长" }, "priority": { "type": "integer", "x-tier": "advanced", "maximum": 9, "minimum": 0, "x-label-en": "Queue priority", "x-label-zh": "排队优先级" }, "watermark": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Watermark", "x-label-zh": "水印" }, "resolution": { "enum": [ "480p", "720p" ], "type": "string", "x-tier": "common", "default": "720p", "x-label-en": "Resolution", "x-label-zh": "分辨率" }, "service_tier": { "enum": [ "default" ], "type": "string", "x-tier": "advanced", "default": "default", "x-label-en": "Service tier", "x-label-zh": "服务档位" }, "generate_audio": { "type": "boolean", "x-tier": "common", "default": true, "x-label-en": "Generate audio", "x-label-zh": "生成声音" }, "return_last_frame": { "type": "boolean", "x-tier": "advanced", "default": false, "x-label-en": "Return last frame", "x-label-zh": "返回尾帧" }, "safety_identifier": { "type": "string", "x-tier": "advanced", "maxLength": 64, "x-label-en": "End-user ID", "x-label-zh": "终端用户标识" } }, "additionalProperties": false } ```