Seedream 5.0 Pro Image Edit API

bytedance/seedream-v5.0-pro/edit

Up to 10 images · 1K/2K · JPEG/PNG

Seedream 5.0 Pro Image Edit API accepts a natural-language prompt and one to ten ordered image URLs. Use the prompt to name each image's role and the requested changes to subjects, product details, text, layout, background, materials, composition, or visual style; output is 1K/2K JPEG or PNG.

Input

Prompt665/10000

Reference images1/10

Replace

Add images

Required for Image Edit. Upload 1–10 JPEG, PNG, or WebP files, up to 30 MB each. Order is preserved in the API request.

Size

Resolution

Output format

Safety checker

The Playground sends enable_safety_checker explicitly with a default of true.

Ready

Continue with

Seedream 5.0 Pro Text-to-Image

Examples

Edit only the environment and lighting of this still-life image. Preserve exactly the same clear glass vase, celadon bowl, folded linen cloth, object count, object shapes, surface textures, relative positions, camera angle, crop, and focal length. Change the north-window daylight into a quiet blue-hour scene after rain: cool ambient light from the window, a subtle warm reflection from outside the frame, faint raindrop bokeh beyond the window, and physically believable reflections on the glass and glaze. Keep the oak table and museum-study mood. Do not add or remove objects. No people, no brand, no logo, no packaging, no text, no advertisement, no watermark.

REST API

Quick Start

Authenticate, submit one minimal image edit with your own public reference URL, then use task_id to retrieve every result.

Authenticate the request

Create an API key, keep it on your server, and send Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one edit task

Replace the example.com URL, preserve array order, and send the edit model at the top level. The response returns task_id immediately.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "seedream-v5.0-pro/edit",
  "input": {
    "prompt": "Keep the product shape and replace the background with a warm studio set.",
    "image_urls": ["https://example.com/product.jpg"],
    "size": "1:1",
    "resolution": "1K",
    "output_format": "jpeg"
  }
}'

Wait for the result

Poll while status is not_started or running. On finished, read data.files[].file_url; on failed, stop and inspect the error.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every 2–5 seconds while status is not_started or running. Stop on finished or failed. On success, read every data.files[].file_url; callback_url can receive the terminal result instead.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "not_started",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/edited-image.jpg",
        "file_type": "image"
      }
    ],
    "progress": 100,
    "error_message": null
  }
}

Complete runnable example

Expand this example for submission, polling, terminal-state checks, error handling, and extraction of all returned file URLs.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "seedream-v5.0-pro/edit",
  "input": {
    "prompt": "Keep the product shape and replace the background with a warm studio set.",
    "image_urls": ["https://example.com/product.jpg"],
    "size": "1:1",
    "resolution": "1K",
    "output_format": "jpeg"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

The input object supports the following image-editing parameters.

Field	Type	Required	Default	Description
input.prompt	string	Yes	—	Non-empty after trimming; maximum 10,000 characters.
input.image_urls	string[]	Yes	—	One to ten public HTTP(S) image URLs, kept in the supplied order. Replace example.com URLs with your own.
input.size	string	No	1:1	One of 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, or 21:9.
input.resolution	string	No	1K	1K or 2K.
input.output_format	string	No	jpeg	jpeg or png.
input.enable_safety_checker	boolean	No	— (Playground: true)	The playground sends true by default.

Response Fields

Submission returns task identity. Status responses add progress, files, or an error message.

Field	Type	Description
code	integer	Application result code; successful responses use 0 or 200.
message	string	Human-readable message when present.
data.task_id	string	Identifier used in the status endpoint.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation time.
data.progress	integer	Completion percentage when reported.
data.files[]	array	All generated files after a successful task.
data.files[].file_url	string	Public URL of a generated image.
data.files[].file_type	string	Media type, expected to be image for Seedream 5.0 Pro Image Edit API.
data.files[].watermark_url	string \| null	Watermarked file URL when available.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Continue polling only in non-terminal states. finished and failed both stop the lifecycle.

not_started
Accepted and waiting to begin; continue polling.
running
The edit is in progress; continue polling.
finished
Successful terminal state; read every data.files[].file_url.
failed
Failed terminal state; read data.error_message and stop.

Polling and Errors

AuthenticationA 401 response means the Bearer API key is missing or invalid.
ValidationA 400 response identifies an invalid model, prompt, enum value, URL, or image count.
Upload boundaryUpload local files first and submit their public HTTP(S) URLs; replace the example.com URL in samples.
Polling intervalStart around 2–5 seconds and back off on 429 or 5xx responses.
Terminal statesContinue only for not_started or running; stop immediately for finished or failed.
Callback optionAdd callback_url at the top level to receive a flat terminal task object by POST.

Model Specifications

Specification	Value	Details
Input mode	Image edit	A prompt and 1–10 ordered image URLs are required.
Output	Image	The asynchronous task can return one or more image files.
References	1–10 images	input.image_urls accepts ordered public HTTP(S) image URLs.
Resolution	1K / 2K	1K is the backend default.
Aspect and format	8 ratios · JPEG/PNG	1:1 is the default ratio and JPEG is the default format.
Frontend estimate	15 credits / request	The current frontend estimator returns the same value for every supported source-image count and output configuration.

View Seedream 5.0 Pro Image Edit API documentation

Seedream 5.0 Pro Image Edit API

Seedream 5.0 Pro Image Edit API requires a prompt and one to ten ordered public HTTP(S) image URLs. The prompt can identify each source image by array order and describe the requested edit; successful submission returns an asynchronous image task.

Why Choose Seedream 5.0 Pro Image Edit API?

Translate intent into precise edits.Describe the target result in natural language, including the region, object, text, material, or layout that should change.
Name details that should remain recognizable.List the identity, product geometry, branding, palette, typography, or composition that the edit prompt should retain.
Give up to ten images distinct roles.Use ordered sources for the main subject, product, wardrobe, setting, composition, lighting, or style direction.
Describe how edited elements should relate.Specify perspective, scale, reflections, materials, and lighting for the requested composite.
Adapt finished creative for delivery.Update copy, layout, background, and art direction, then export in eight ratios at 1K or 2K as JPEG or PNG.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe each source image's role, the details to preserve, and the intended edit in up to 10,000 characters.
image_urls	Required	Provide an ordered array of 1–10 public HTTP(S) image URLs and refer to them in the same order in the prompt.
size	Optional	Choose the output aspect ratio for the intended placement. Default`1:14:33:416:99:162:33:221:9`
resolution	Optional	Choose the output resolution tier. Default`1K2K`
output_format	Optional	Choose JPEG or PNG for the edited file. Default`jpegpng`
enable_safety_checker	Optional	Set the boolean content-safety check for the request. `truefalse`

How to Use

Assign the source rolesPlace the main asset first, then order references for product details, setting, composition, lighting, or style.
Write the preserve listName the identity, geometry, branding, text, palette, and layout details that define the original asset.
Describe one target stateSpecify the new background, material, copy, arrangement, or art direction and connect each change to its source.
Choose the outputMatch the aspect ratio to the placement, then select 1K or 2K and JPEG or PNG.
Submit and inspectRun the request and review every returned image for consistency, text accuracy, edges, reflections, and small details.

Pricing

The current frontend estimate is 15 credits per edit request. At $0.005 per credit, the estimated cost is $0.075 for every supported resolution, ratio, format, and source-image count.

Usage	Rate	Details
Frontend request estimate	15 credits	The estimate is unchanged across one to ten source images and every supported output setting.

Best Use Cases

Product Background ReplacementKeep the product geometry and branding while replacing the environment and studio treatment.
Campaign Variant ProductionPreserve a hero asset while changing palette, copy treatment, crop, or seasonal art direction.
Multi-Image Visual FusionAssign subject, wardrobe, environment, and style roles to ordered source images.
Localized Creative AdaptationRetain core imagery while changing specified text and layout for another language or placement.

Pro Tips

Start the prompt with a precise preserve list before describing any change.
Refer to images by their array order, such as the first image for the product and the second for lighting.
Use concrete spatial language to identify the background, foreground, left, right, or central subject.
Quote exact replacement text and identify the text block that should change.
Describe one coherent target state instead of stacking conflicting edit directions.
Review the final image for small text and identity details before production use.

Notes

image_urls accepts 1–10 ordered public HTTP(S) image URLs.
Place the primary asset first, then refer to supporting images by their array order in the prompt.
size supports eight aspect ratios; resolution supports 1K or 2K; output_format supports jpeg or png.
The request returns an asynchronous task ID; finished results provide image URLs in data.files[].file_url.

Related Models

Seedream 5.0 LiteUse the faster Seedream companion for text generation and reference-guided editing.

Seedream 4.5Create or edit images with the established Seedream 4.5 workflow.

GPT Image 2Compare image generation and editing across flexible quality tiers.

Nano Banana ProUse a Google image workflow for text rendering, blending, and image editing.

FLUX.2Explore text-to-image and multi-reference editing across Pro and Flex variants.

Seedream 4Use the earlier Seedream generation and editing family for compatible workflows.

Frequently Asked Questions about Seedream 5.0 Pro Image Edit API

What is the Seedream 5.0 Pro Image Edit API?

Seedream 5.0 Pro Image Edit API accepts a prompt and one to ten ordered public HTTP(S) image URLs. Use the prompt to identify each image's role and describe what to retain or change; the API returns an asynchronous image task.

How do I call the Seedream 5.0 Pro Image Edit API?

POST to /api/generate/submit with Authorization: Bearer VIDGO_API_KEY, model set to seedream-v5.0-pro/edit, and prompt plus image_urls inside input. Replace the example.com URL with your own public image URL.

How much does Seedream 5.0 Pro Image Edit cost?

The current frontend estimate is 15 credits per request. At $0.005 per credit, the estimated cost is $0.075 whether you supply one or ten source images and regardless of supported output settings.

What inputs does Seedream 5.0 Pro Image Edit accept?

The input object supports prompt, image_urls with one to ten ordered public HTTP(S) URLs, size, resolution, output_format, and optional enable_safety_checker. Use prompt to assign each image a role and describe the details to preserve and change.

How do I get the edited images?

Poll GET /api/generate/status/{task_id} until finished or failed. On success, read every data.files[].file_url, or supply callback_url at submission time.

Which Seedream 5.0 Pro API mode should I choose?

Choose Image Edit when the request contains one to ten ordered source-image URLs. Choose Text-to-Image when the request contains a prompt but no source images.