Seedream 5.0 Flash

Use doubao-seedream-5.0-flash for text-to-image generation, image-to-image generation with up to 10 reference images, and decomposition of one reference image into layers. Ordinary generation returns one image; layer decomposition returns a base image and separate foreground layers.

Pricing

Reference images are free. All supported output resolutions use the same price.

4.68 credits per successful output, including the background in layer mode. Generation pre-charges 4.68 credits. Layer decomposition reserves up to 17 outputs, or 79.56 credits, and returns only the unused difference after verified successful completion. For example, a verified result containing a background and two foreground layers costs 14.04 credits, with 65.52 returned from the reservation. Account multipliers apply to the total; credits are rounded to two decimal places. Missing or inconsistent results retain the reservation for reconciliation, without retrying the generation or issuing a failure refund after success.

Request parameters

Endpoint: POST /v1/images/generations. Authenticate with Authorization: Bearer sk-your-api-key.

Field	Type	Required	Description
`model`	string	Yes	Always `doubao-seedream-5.0-flash`.
`input`	object	Yes	Generation parameters listed below.
`callback_url`	string	No	URL to receive completion or failure notifications.

Input parameters

Input	Type	Description
`prompt`	string	Required, non-empty in both modes.
`layer_decomposition`	boolean	Default `false`. Set `true` to split one reference image into layers.
`image_urls`	string[]	Public HTTP(S) URLs only; up to 10 for generation, exactly one for layer decomposition. No Base64.
`size`	string	Generation: default `2K`; `1K`, `1.5K`, `2K`, or exact `WIDTHxHEIGHT`. Layer decomposition: default `auto`; only `auto`, `1K`, `1.5K`, or `2K`.
`output_format`	string	`jpeg` (default) or `png`.
`watermark`	boolean	Default `false`; set `true` to add a watermark.

Exact generation sizes must have 921,600–4,624,220 pixels and an aspect ratio from 1/16 to 16. auto is only available for layer decomposition; exact pixel sizes are only available for generation. Flash does not support sequential image sets, web search, prompt optimization options, or streaming output. Results are URLs, not Base64 or PSD files. Do not pass a requested output count; the service derives it from the mode.

Async tasks and callbacks

Creating a task returns a taskId, for example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "00000000-0000-4000-8000-000000000002"
  }
}

Query the result using that task ID:

curl https://api.aivideoapi.ai/v1/tasks/00000000-0000-4000-8000-000000000002 \
  -H "Authorization: Bearer sk-your-api-key"

Tasks may be pending, processing, completed, or failed. When completed, read output.urls and output.metadata. After a timeout, continue querying the existing task to avoid duplicate generation requests.

Alternatively, provide callback_url when creating a task to receive the final result. The completed callback body has the same structure as the completed query results below. See Callback Notifications for signature verification and retries.

Image generation

Create request

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-flash",
    "input": {
      "prompt": "An orange cat watching the sunset beside a window",
      "size": "2K"
    }
  }'

Completed result (sanitized example)

Query GET /v1/tasks/{taskId} to retrieve a single JPEG result like the following. The returned images[0].size gives the actual output dimensions. This example consumes 4.68 credits with an account multiplier of 1. The task ID, image URL, and timestamps are placeholders; the URL cannot be used to download an image. Token counts in usage are informational; Flash is billed by successful output count.

{
  "id": "00000000-0000-4000-8000-000000000002",
  "status": "completed",
  "model": "doubao-seedream-5.0-flash",
  "credits_consumed": 4.68,
  "created_at": 1700000000,
  "completed_at": 1700000028,
  "output": {
    "urls": [
      "https://example.com/seedream/generated.jpg"
    ],
    "metadata": {
      "model": "doubao-seedream-5.0-flash",
      "usage": {
        "input_images": 0,
        "total_tokens": 16820,
        "output_tokens": 16820,
        "generated_images": 1
      },
      "images": [
        {
          "size": "1856x2320",
          "output_index": 0,
          "output_format": "jpeg"
        }
      ],
      "image_sizes": [
        "1856x2320"
      ],
      "output_format": "jpeg",
      "generated_images": 1,
      "settlement_reason": null,
      "settlement_status": "settled",
      "layer_decomposition": false,
      "requested_image_count": 1,
      "result_url_expires_in": 86400,
      "source_url_expires_in": 86400
    }
  }
}

Layer decomposition

Create request

curl -X POST https://api.aivideoapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-flash",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "Separate the foreground subjects from the background",
      "image_urls": ["https://example.com/scene.png"],
      "layer_decomposition": true,
      "size": "auto",
      "output_format": "png"
    }
  }'

A completed task keeps the usual output.urls array. output.metadata.images describes each output: output_index is its zero-based index in output.urls; z_index is the layer order. Optional name, description, size, and output_format describe that image. Foreground bounding_box.absolute and bounding_box.normalized both use [left, top, right, bottom], not width/height. Normalized coordinates are integers from 0 to 1000. The background has no bounding box. Preserve each URL entry and use output_index to associate metadata; do not infer layer order from URL names or deduplicate layers.

Completed layer decomposition result (sanitized example)

Query GET /v1/tasks/{taskId} to retrieve the completed result below. It contains a base image and seven foreground layers, for eight outputs in total. The task ID, image URLs, timestamps, layer names, and descriptions have been replaced with example values. The URLs are placeholders and cannot be used to download images.

This example uses an account multiplier of 1: 79.56 credits reserved, 4.68 × 8 = 37.44 credits consumed, and 42.12 credits returned. The returned credits_consumed is the actual charge for your task. Token counts in usage are informational; Flash is billed by successful output count.

The base image has z_index: 0 and may omit name, description, and bounding_box; clients should accept missing fields. size describes the output image dimensions, while bounding_box locates the layer in the original image, so their widths and heights may differ. requested_image_count: 17 is the maximum reserved output count; generated_images: 8 is the successful count for this result.

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "completed",
  "model": "doubao-seedream-5.0-flash",
  "credits_consumed": 37.44,
  "created_at": 1700000000,
  "completed_at": 1700000075,
  "output": {
    "urls": [
      "https://example.com/seedream/base.png",
      "https://example.com/seedream/layer-1.png",
      "https://example.com/seedream/layer-2.png",
      "https://example.com/seedream/layer-3.png",
      "https://example.com/seedream/layer-4.png",
      "https://example.com/seedream/layer-5.png",
      "https://example.com/seedream/layer-6.png",
      "https://example.com/seedream/layer-7.png"
    ],
    "metadata": {
      "model": "doubao-seedream-5.0-flash",
      "usage": {
        "input_images": 1,
        "total_tokens": 41704,
        "output_tokens": 41704,
        "generated_images": 8
      },
      "images": [
        {
          "size": "1152x2048",
          "z_index": 0,
          "output_index": 0,
          "output_format": "png"
        },
        {
          "size": "698x752",
          "z_index": 1,
          "output_index": 1,
          "output_format": "png",
          "name": "Background pedestrians",
          "description": "Pedestrians in the left background.",
          "bounding_box": {
            "absolute": [0, 1009, 327, 1363],
            "normalized": [0, 493, 283, 665]
          }
        },
        {
          "size": "504x955",
          "z_index": 2,
          "output_index": 2,
          "output_format": "png",
          "name": "Vertical signs",
          "description": "Vertical illuminated signs on both sides of the street.",
          "bounding_box": {
            "absolute": [111, 0, 615, 955],
            "normalized": [96, 0, 533, 466]
          }
        },
        {
          "size": "750x935",
          "z_index": 3,
          "output_index": 3,
          "output_format": "png",
          "name": "Central display",
          "description": "The electronic display in the center of the scene.",
          "bounding_box": {
            "absolute": [206, 617, 436, 904],
            "normalized": [179, 301, 378, 441]
          }
        },
        {
          "size": "590x1329",
          "z_index": 4,
          "output_index": 4,
          "output_format": "png",
          "name": "Right storefront sign",
          "description": "The sign and decorations on the right storefront.",
          "bounding_box": {
            "absolute": [884, 483, 1152, 1086],
            "normalized": [767, 236, 999, 530]
          }
        },
        {
          "size": "1130x608",
          "z_index": 5,
          "output_index": 5,
          "output_format": "png",
          "name": "Upper archway",
          "description": "The archway and lighting at the top of the scene.",
          "bounding_box": {
            "absolute": [0, 429, 619, 762],
            "normalized": [0, 209, 536, 372]
          }
        },
        {
          "size": "480x1245",
          "z_index": 6,
          "output_index": 6,
          "output_format": "png",
          "name": "Right-side person",
          "description": "A person holding an umbrella in the right background.",
          "bounding_box": {
            "absolute": [764, 995, 1023, 1667],
            "normalized": [663, 486, 887, 813]
          }
        },
        {
          "size": "983x1366",
          "z_index": 7,
          "output_index": 7,
          "output_format": "png",
          "name": "Foreground person",
          "description": "The main foreground person and their clothing.",
          "bounding_box": {
            "absolute": [106, 682, 1089, 2048],
            "normalized": [92, 333, 944, 1000]
          }
        }
      ],
      "image_sizes": [
        "1152x2048",
        "698x752",
        "504x955",
        "750x935",
        "590x1329",
        "1130x608",
        "480x1245",
        "983x1366"
      ],
      "output_format": "png",
      "generated_images": 8,
      "settlement_reason": null,
      "settlement_status": "settled",
      "layer_decomposition": true,
      "requested_image_count": 17,
      "result_url_expires_in": 86400,
      "source_url_expires_in": 86400
    }
  }
}

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

HTTP Status	Code	Type	Description
400	`invalid_request`	invalid_request_error	Missing or invalid parameters
401	`invalid_api_key`	authentication_error	API key is invalid, disabled, or deleted
402	`insufficient_credits`	billing_error	Credit balance too low, please top up
403	`ip_not_allowed`	permission_error	Request IP not in the key's allowlist
404	`model_not_found`	invalid_request_error	Model does not exist or is inactive
404	`task_not_found`	invalid_request_error	Task ID does not exist
429	`rate_limit_exceeded`	rate_limit_error	Too many requests, please slow down
429	`spend_limit_exceeded`	billing_error	Key spend limit reached (hourly/daily/total)
500	`internal_error`	api_error	Unexpected server error
503	`upstream_error`	upstream_error	Upstream AI provider returned an error

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

The key does not start with sk-
The key has been disabled or deleted
The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

The input contains sensitive or prohibited content
The provider is temporarily unavailable
The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.