Bytedance Seedream V5.5 Edit API Documentation

Bytedance Seedream V5.5 Edit API Documentation

Playground

Seedream 5.5 Edit by ByteDance edits and generates images from single-image or multi-reference inputs, supporting up to 10 reference images, consistent multi-turn edits, native transparent-background output, and 1K, 1.5K and 2K output tiers. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Seedream 5.5 Edit edits and composes images from one or several reference images. It is designed to preserve unedited areas across repeated edits, supports output up to 2K, and can return a result with a transparent background.

Why Choose This?

• Consistent edits
  Built to preserve unedited areas, so you can refine an image over several rounds.

• Multi-image reference editing
  Use up to 10 reference images for complex edits, compositions, and visual guidance.

• Natural language editing
  Describe the desired edit in plain text and let the model transform the input images accordingly.

• Native transparent background
  Set background to transparent to extract a subject onto a transparent PNG. The inputs do not need an alpha channel.

• Flexible resolution tiers up to 2K
  Choose 1k or 1.5k for lower-cost edits, or 2k for higher-resolution output.

• PNG by default
  Output is PNG unless you ask for jpeg.

Parameters

How to Use

1. Upload reference images — Provide one or more images to guide the edit.
2. Write your prompt — Describe what should change and what should stay the same.
3. Choose aspect ratio — Select an aspect ratio, or leave it empty to keep the first input image’s shape.
4. Choose resolution — Use 1k or 1.5k for lower-cost edits, or 2k for higher-resolution output.
5. Choose background — Use transparent to extract a subject or make a cut-out.
6. Submit — Generate the final edited image.

Pricing

Pricing is the output price of the selected resolution plus $0.008 for each input image.

Example Costs

Best Use Cases

• Single-image editing — Edit one source image with natural-language instructions.
• Multi-round refinement — Refine an image through repeated edits while aiming to preserve unedited areas.
• Subject extraction — Cut a person, product, or object out onto a transparent background.
• Multi-reference composition — Use multiple images to guide complex edits and visual combinations.
• Product image editing — Refine product visuals, backgrounds, styles, and presentation.

Pro Tips

• Describe both what should change and what should remain unchanged.
• Use multiple reference images when identity, product details, or style consistency matters.
• For a cut-out, describe the subject to keep and set background to transparent.
• Choose 1k or 1.5k for iteration and 2k for the final render.

Related Models

• Seedream 5.5 — Generate images from text prompts.
• Seedream 5.5 Layer Decomposition — Split an image into a base image and transparent layers.
• Seedream V5.0 Pro Edit — The previous Pro edit model.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ],
  "aspect_ratio": "1:1",
  "resolution": "1k",
  "output_format": "png",
  "background": "auto"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/bytedance/seedream-v5.5/edit" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters