Seedream 5.5

Use doubao-seedream-5.5 for text-to-image generation, reference-image editing, fusion of up to 10 reference images, transparent backgrounds, and layer decomposition with optional text recognition. Ordinary generation returns one image. Layer decomposition returns a base image and separate layers.

Pricing

Every reference image is charged, including the first. Each output, including the base image and every layer, is priced by its actual returned dimensions.

Request parameters

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

Input parameters

Exact generation dimensions must contain 921,600–4,624,220 pixels, with an aspect ratio from 1/16 to 16. auto is only valid for layers. Layer mode rejects exact pixel dimensions, background, and more or fewer than one input image. Generation rejects layer_decomposition_options. transparent with jpeg is invalid. Transparent generation also works without references and does not require transparent input images.

Input files must be publicly accessible and no larger than 30 MB each. Generation accepts JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, and HEIF, with both dimensions greater than 14 pixels and 196–36,000,000 total pixels. Layers accept PNG or JPEG with 262,144–36,000,000 pixels. Both modes require input aspect ratios from 1/16 to 16.

Use image_urls and URL results. Raw image, Base64 inputs, response_format, stream, sequential_image_generation, sequential_image_generation_options, and tools are not supported. Do not send a separate output count; ordinary generation produces one output and layers use max_images.

Generation, editing, and fusion

Create a text-to-image task using the default 2K PNG output:

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.5",
    "input": {
      "prompt": "A quiet seaside library at sunrise"
    }
  }'

For reference-image editing, add one image to image_urls. For fusion, provide up to 10 images and describe how to combine them. This example combines two references with a transparent background:

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.5",
    "input": {
      "prompt": "Combine the product from the first image with the ribbon from the second, isolated on a transparent background",
      "image_urls": ["https://example.com/product.png", "https://example.com/ribbon.png"],
      "background": "transparent",
      "output_format": "png",
      "size": "2K",
      "watermark": false
    }
  }'

Layer decomposition and text recognition

This request omits the prompt and size, uses the default maximum of 30 outputs, and enables text recognition:

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.5",
    "input": {
      "image_urls": ["https://example.com/poster.png"],
      "layer_decomposition": true,
      "layer_decomposition_options": {"text_recognition": true}
    }
  }'

Set max_images between 2 and 100 to control the maximum decomposition count. It includes the base image and is not the final billed count. Higher limits can produce finer decomposition; exceeding the limit in your prompt can omit some layer information.

Async tasks and results

Accepted requests use direct background execution: the API returns a taskId immediately and performs one generation call in the background. Continue using the task query or callback protocol to receive the result.

Creation returns the usual task ID:

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

Query the same task until it completes:

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

Tasks use pending, processing, completed, failed, or cancelled. A task can be cancelled with its reservation returned before submission starts; cancellation is unavailable after submission. Tasks awaiting reconciliation may remain pending or processing. After a timeout, query the existing task instead of submitting it again. You can also set callback_url; see Callback Notifications for signature verification and retries.

The top-level settlement_status reports billing progress: pending means results or settlement are pending; reconciliation_required means review is needed and the reservation remains held; settled means actual usage has been settled; not_charged means a failed or cancelled task's reservation has been returned. Keep querying the original task during review; this field updates after reconciliation.

Completed results retain output.urls. Match each output.metadata.images entry to its URL by output_index; preserve every entry even if URLs repeat. Metadata includes actual size, output_format, and background, plus optional layer z_index, name, description, bounding_box, and text_recognition.

The following layer result contains one base image and one text layer. URLs are placeholders.

{
  "id": "00000000-0000-4000-8000-000000000055",
  "status": "completed",
  "model": "doubao-seedream-5.5",
  "credits_consumed": 15.98,
  "settlement_status": "settled",
  "output": {
    "urls": ["https://example.com/base.png", "https://example.com/title.png"],
    "metadata": {
      "model": "doubao-seedream-5.5",
      "usage": {"input_images": 1, "generated_images": 2},
      "layer_decomposition": true,
      "requested_image_count": 30,
      "generated_images": 2,
      "settlement_status": "settled",
      "images": [
        {"output_index": 0, "size": "2048x2048", "output_format": "png", "background": "opaque", "z_index": 0},
        {
          "output_index": 1,
          "size": "1600x1000",
          "output_format": "png",
          "background": "transparent",
          "z_index": 1,
          "name": "Title",
          "description": "The poster title",
          "bounding_box": {"absolute": [224, 200, 1824, 1200], "normalized": [109, 98, 891, 586]},
          "text_recognition": {
            "text": "SUMMER",
            "lines": [{
              "bounding_box": {"absolute": [400, 400, 1648, 700], "normalized": [195, 195, 805, 342]},
              "runs": [{"text": "SUMMER", "style": {"similar_font_family": "Arial", "foreground_color": "#FFFFFF", "bold": true, "italic": false, "underline": false, "strikethrough": false, "shadow": false, "translucent": false}}]
            }]
          }
        }
      ]
    }
  }
}

The base image has z_index: 0 and no bounding box. Stack layers in increasing z_index. bounding_box.absolute and .normalized use [left, top, right, bottom] in base-image coordinates; normalized values range from 0 to 1000. The image dimensions and bounding-box dimensions can differ.

OCR text contains the full text, with lines separated by \n. Each lines[].runs[] entry holds a text fragment and approximate style. Non-text layers, handwriting, and artistic lettering may omit text_recognition; an unrecognized font can use similar_font_family: "unknown".

By default, results use the original generated image URLs. Accounts that explicitly enable R2 copying receive the copied image URLs. The Playground supports layer previews, downloads, copying recognized text, and viewing metadata. Download results promptly; original image URLs are valid for approximately 24 hours.

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

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.