Seedream 5.0 Pro API

Generate images, edit references, or decompose an image into layers with your Seevio API key. Tasks run asynchronously; save taskId and poll the task endpoint or receive a callback.

POST https://api.seevio.ai/v1/images/generations

Capabilities

Feature	Supported values
Generation modes	`text-to-image, image-to-image, layer-decomposition`
Output resolution	`1K, 1.5K, 2K`
Aspect ratio	`1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9`
Reference images	Public HTTPS PNG / JPEG / WebP URLs, each up to 30 MB. Use no images for text-to-image, 1–10 for image-to-image, and exactly one for layer-decomposition.
Prompt	Use 4–5000 characters after trimming. For layer-decomposition only, prompt may be omitted or empty.
Output format	`png, jpg`

Pricing & credits

Prices below are per returned image. Ordinary generation reserves one image. Layer decomposition reserves 17 images, settles the actual returned count (including the base image) and returns the unused credits to their original balance. Failed tasks are fully refunded.

Output resolution	Pricing & credits
1K	4 credits
1.5K	4 credits
2K	8 credits

At the default 2K resolution, layer decomposition reserves 136 credits. If four images are returned, the final charge is 32 credits and 104 credits are returned.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

Authentication

Create an API key in the dashboard. The complete key is shown only once. Keep it on your server and send it as a Bearer token on every request.

Create API key API dashboard

Base URL

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Set the SEEVIO_API_KEY environment variable before running these examples. JavaScript examples run on your server with Node.js; Python examples use the requests package.

Request body

Field	Type	Required	Description & constraints
`model`	string	Yes	Model ID. To use Seedream 5.0 Pro, set this field to seedream-5-0-pro.
`callback_url`	string	No	Public HTTPS endpoint for completion and failure POST callbacks. Private networks and localhost are not allowed. Example: `https://example.com/webhooks/seevio`
`input`	object	Yes	Generation settings. A prompt is required for text-to-image and image-to-image; it is optional for layer decomposition.

Input parameters

Field	Type	Required	Default	Description & constraints
`input.prompt`	string	Conditional	`—`	Use 4–5000 characters after trimming. For layer-decomposition only, prompt may be omitted or empty. Example: `A minimalist ceramic teapot on a stone pedestal, soft studio lighting`
`input.generation_type`	string	No	`text-to-image`	Use text-to-image for a new image, image-to-image to edit references, or layer-decomposition to separate a single image into reusable elements. Supported values `text-to-image \| image-to-image \| layer-decomposition`
`input.image_urls`	string[]	Conditional	`[]`	Public HTTPS PNG / JPEG / WebP URLs, each up to 30 MB. Use no images for text-to-image, 1–10 for image-to-image, and exactly one for layer-decomposition. Example: `["https://example.com/teapot.png"]`
`input.aspect_ratio`	string	No	`1:1`	Aspect ratio Supported values `1:1 \| 4:3 \| 3:4 \| 16:9 \| 9:16 \| 2:3 \| 3:2 \| 21:9` Example: `1:1`
`input.resolution`	string	No	`2K`	Text-to-image and image-to-image support 1K (basic quality) and 2K (high quality). Layer-decomposition supports 1K, 1.5K and 2K. Default: 2K. Supported values `1K \| 1.5K \| 2K` Example: `2K`
`input.output_format`	string	No	`png`	Requested output format. For layer decomposition, png returns a PNG base image and jpg returns a JPEG base image. All separated layers are returned as PNG with transparency preserved. Supported values `png \| jpg` Example: `png`

Each request creates one task. Text-to-image and image-to-image return one image; layer-decomposition returns 1–17 images, including the base image. Do not send aspect_ratio for layer-decomposition.

Quickstart

Submit this minimal request, save the returned taskId, then use the task query example below. The credits value in the create response is the reserved amount.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Create task response example

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 8
}

Text to image

Generate images, edit references, or decompose an image into layers with your Seevio API key. Tasks run asynchronously; save taskId and poll the task endpoint or receive a callback.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Image to image

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

Replace example.com media URLs with your own publicly accessible HTTPS files. The sample URLs illustrate the request shape and are not downloadable sample assets.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Layer decomposition

Set generation_type to layer-decomposition and provide exactly one image URL. Omit aspect_ratio. output_format controls only the base image format. Separated layers are always returned as PNG with transparency preserved. Save every URL in data.results.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

Layer decomposition can return multiple image URLs in data.results: the base image and the separated layers. Each URL points to a separate image. The number of results varies by task (1–17 images in total); process the entire array rather than only data.results[0]. Both the completed task query and the completion webhook contain this array. The initial create response contains taskId and reserved credits, not image URLs.

Create task response example

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 136
}

Completed layer decomposition: multiple image URLs

This illustrative response shows four output images: one base image and three layers. Your task may return a different number. At the requested 2K resolution, credits is the final charge for all four images; the unused portion of the initial 17-image reservation has been returned.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Process every returned image

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

Query a task

GET https://api.seevio.ai/v1/tasks/{taskId}

Replace the example ID with the taskId returned by creation. Queries only return tasks owned by the API key's user; inaccessible or unknown IDs return HTTP 404.

Poll every 10–20 seconds as a starting point, back off on HTTP 429 and stop when the status is completed or failed. Prefer webhooks for production. Each code example below performs one query.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

Status	Allowed values and requirements
queued	Accepted and waiting for submission.
generating	Generation is in progress.
completed	Terminal success. Download data.results before expiry.
failed	Terminal failure. Inspect failed_reason and billing_status.

Field	Type	Allowed values and requirements
id	string	Task identifier. This is taskId from the create response.
created_at	number	Task creation time as Unix seconds.
model	string	The public model ID used for this task.
billing_status	string	reserved, charged, refunded or refund_failed.
credits	number	The create response and pending task show reserved credits. On completion, credits is the actual charge; unused reserved credits have already been returned. Failed tasks retain the original reserved amount.
failed_reason	string \| null	Failure reason on failed tasks; null otherwise. Failed query responses omit data.
failed_code	string \| null	Error code. See failed_reason for details.
data	object	Present on non-failed task queries. Contains output and processing details.
data.results	string[]	All output image URLs, including the base image for layer decomposition. Empty before completion and after expiry.
data.image_expires_at	string \| null	Image expiry time in ISO 8601 format, or null until available.
data.processing_time	number \| null	Task processing duration in seconds when available, otherwise null.

Queued

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Completed

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Failed

When the query returns status=failed, generation has ended unsuccessfully. Read failed_reason for the cause and billing_status for the refund outcome. In this example, refunded means the credits were returned. credits retains the original reserved amount, and the response does not include data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

Webhooks

Set callback_url in the create request to receive a JSON POST when the task completes or fails. Return a 2xx response within 15 seconds. Failed deliveries are retried; process repeated deliveries idempotently by task ID.

Your callback endpoint must accept POST requests with a JSON request body (Content-Type: application/json).

Create a task with a callback

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

Task completed: successful callback payload

created_at is the event creation time; task_created_at is the task creation time in Unix seconds. Examples show the recommended fields; responses may contain additional fields.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

Task failed: failure callback payload

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

Receiver example

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

This Next.js example reads the JSON callback body and handles completed and failed tasks directly. Add persistence and task-ID deduplication for your application; queue slow work before acknowledging the callback.

Errors

HTTP errors have an error object with code and message. A successfully accepted task can still fail later; query the task or handle its failure callback.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

HTTP	Field	What to do
400	`invalid_request`	Fix the JSON, missing prompt, parameter range or media URL before retrying.
401	`invalid_api_key`	Check the Bearer token and whether the API key is active.
402	`insufficient_credits`	Add credits or reduce the task cost. The response may include required and available amounts.
403	`forbidden`	Check the account-level restriction described in the error message.
404	`not_found`	Check the task ID and that the key belongs to the task's user.
429	`rate_limited`	Wait for the Retry-After interval before retrying.
500	`internal_error`	Inspect the error message and API logs. Retry cautiously; resubmitting a create request can create another billable task.

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. A 402 insufficient_credits error means your available credits are insufficient for this request.

Rate limits

Create tasks: each API key allows up to 100 requests per minute by default. Custom rate limits are not currently available.

Query tasks: each API key allows up to 120 requests per minute by default. Query requests and task creation requests are counted separately.

Image and video creation requests share the same API key rate limit.

HTTP 429 includes Retry-After: 60 for creation and Retry-After: 5 for queries. Use backoff and avoid polling more frequently than necessary.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}