Seedream 4 Edit API

bytedance/seedream/v4/edit

1–10 images · 1K/2K/4K · n 1–15

Seedream 4 Edit combines 1–10 reference images with natural language prompts for mask-free editing and multi-image fusion. It executes targeted modifications while preserving source facial identity, composition, and realistic lighting.

Get API Key

Input

PromptRequired0/5000

Image UrlsRequired0/10

Add images

SizeOptional

ResolutionOptional

NOptional

OutputIdle

Generated images will appear here

Estimated cost: —

Continue using

Seedream 4 Text to Image Seedream 4.5 Edit Seedance 2.5 Image to Video

Examples

Combine the three reference images into one natural documentary photograph. Use the elderly bookbinder from image 1 with exactly the same face, wrinkles, eyes, grey beard, navy galabeya, brown leather apron and silver cross. Use only the goatskin cover, gold-and-red interlaced cross, brass bosses and leather ties from image 2; do not copy the white table or the isolated still-life setup. Set the scene in the Cairo workshop from image 3 with its mashrabiya window, wooden press, shelves of quires and the ochre street beyond. The man stands in three-quarter view at the table, pressing the finished cover onto a text block in the wooden press. Relight him and the book with the same warm low afternoon sun from the left and matching lattice shadows, consistent scale and perspective, no text, no watermark.

Extend image 1 into a wide 16:9 photograph. Keep the clove basket, the crate, the slatted shutter and the stripe of sun exactly as they are, with the same size, angle and relative position. Naturally expand the scene on both sides and upward: to the left reveal more of the loft with stacked jute sacks of cinnamon bark and a hanging brass scale; to the right open a doorway onto a bright stone stair and a glimpse of a turquoise harbor; above, show the timber rafters and a few swallows on a beam. Seamless continuation of the same late-afternoon light, dust motes and wood grain with no visible seams or borders, no text, no watermark.

Redraw image 1 in the exact visual style of image 2. Image 1 defines all content: keep the same high terrace viewpoint and framing, the honeycomb vats, the tanners in the same positions, the drying skins and the surrounding stone walls. Image 2 defines only the style: a cyanotype on textured watercolor paper with a Prussian-blue ground, white or pale-blue highlights, slightly uneven chemical wash and visible paper fibers. Do not copy any ferns, plants or botanical shapes from image 2. No text, no signature, no watermark.

REST API

Quick Start

This flow submits one valid Seedream 4 Edit request, captures its task_id, and reads image URLs after the asynchronous task ends.

Connect to the Vidgo API

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

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

Submit one image task

Send the current model ID, prompt, and ordered image URLs to the unified submit endpoint. The example keeps only first-call fields.

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": "bytedance/seedream/v4/edit",
  "input": {
    "prompt": "Combine the three reference images into one natural documentary photograph. Use the elderly bookbinder from image 1 with exactly the same face, wrinkles, eyes, grey beard, navy galabeya, brown leather apron and silver cross. Use only the goatskin cover, gold-and-red interlaced cross, brass bosses and leather ties from image 2; do not copy the white table or the isolated still-life setup. Set the scene in the Cairo workshop from image 3 with its mashrabiya window, wooden press, shelves of quires and the ochre street beyond. The man stands in three-quarter view at the table, pressing the finished cover onto a text block in the wooden press. Relight him and the book with the same warm low afternoon sun from the left and matching lattice shadows, consistent scale and perspective, no text, no watermark.",
    "size": "4:3",
    "resolution": "2K",
    "n": 1,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedream/v4/edit/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/bytedance/seedream/v4/edit/v1/01/input-02.png",
      "https://cdn.vidgo.ai/apis/models/bytedance/seedream/v4/edit/v1/01/input-03.png"
    ]
  }
}'

Wait for the image result

Read data.task_id and poll only while status is not_started or running. Stop on both finished and failed.

Track status

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

Poll every 2–5 seconds and back off on 429/5xx. Or provide top-level callback_url to receive a terminal-state callback.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "MJH8FQO824KBO4VG",
    "status": "running",
    "created_time": "2026-09-26T10:59:58"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "MJH8FQO824KBO4VG",
    "status": "finished",
    "files": [
      {
        "file_url": "https://cdn.vidgo.ai/apis/models/bytedance/seedream/v4/edit/v1/01/output.jpg",
        "file_type": "image"
      }
    ],
    "created_time": "2026-09-26T10:59:58",
    "error_message": null,
    "progress": 100
  }
}

Complete runnable polling example

Expand for the same payload end to end, including business-code, missing-task-ID, failed-state, unexpected-state, and network-error handling.

Complete runnable polling example

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

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "bytedance/seedream/v4/edit",
  "input": {
    "prompt": "Combine the three reference images into one natural documentary photograph. Use the elderly bookbinder from image 1 with exactly the same face, wrinkles, eyes, grey beard, navy galabeya, brown leather apron and silver cross. Use only the goatskin cover, gold-and-red interlaced cross, brass bosses and leather ties from image 2; do not copy the white table or the isolated still-life setup. Set the scene in the Cairo workshop from image 3 with its mashrabiya window, wooden press, shelves of quires and the ochre street beyond. The man stands in three-quarter view at the table, pressing the finished cover onto a text block in the wooden press. Relight him and the book with the same warm low afternoon sun from the left and matching lattice shadows, consistent scale and perspective, no text, no watermark.",
    "size": "4:3",
    "resolution": "2K",
    "n": 1,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/bytedance/seedream/v4/edit/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/bytedance/seedream/v4/edit/v1/01/input-02.png",
      "https://cdn.vidgo.ai/apis/models/bytedance/seedream/v4/edit/v1/01/input-03.png"
    ]
  }
}
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

This table lists only public fields inside input. See Quick Start for top-level model and optional callback_url usage.

Field	Type	Required	Default	Description
input.prompt	string	Yes	–	Describe the requested changes in 1–5,000 characters. Leading and trailing whitespace is not counted.
input.image_urls	string[]	Yes	–	1–10 ordered HTTP(S) reference image URLs. The number of image_urls plus n totals 15 or fewer.
input.size	string	No	1:1	Output aspect ratio. Defaults to 1:1.
input.resolution	string	No	2K	Output resolution preset: 1K, 2K, or 4K. Defaults to 2K.
input.n	integer	No	1	Number of images to generate: integer 1–15. Defaults to 1. The number of image_urls plus n totals 15 or fewer.

Response Fields

The submit response identifies the task. The status response supplies image files or failure details at a terminal state.

Field	Type	Description
code	integer	Business response code; 0 or 200 indicates success.
message	string	Optional human-readable response message.
data.task_id	string	Unique task ID used for status queries after submission.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation timestamp.
data.progress	integer	Progress from 0–100 in status responses.
data.files[]	array	Generated files in returned order when finished.
data.files[].file_url	string	Direct generated-image URL.
data.files[].file_type	string	Image results are identified as image.
data.files[].watermark_url	string \| null	Optional watermarked-file URL when present.
data.error_message	string \| null	Readable failure reason for failed tasks.

Task Lifecycle

Only the first two states may be polled again. finished and failed are terminal.

not_started
Accepted and queued; wait before checking again.
running
Image generation is in progress; continue polling.
finished
Successful terminal state; validate files and read image URLs.
failed
Failure terminal state; read error_message and stop.

Polling and Errors

AuthenticationKeep a valid VIDGO_API_KEY on the server and send requests with Bearer authentication.
Validation400 indicates an invalid model ID, field, enum, length, or image count.
Polling intervalStart at 2–5 seconds, use exponential backoff for 429/5xx, and enforce an overall timeout.
Terminal statesRead image URLs from files after finished, or error_message after failed. Both states end polling.
Callback optionProvide a public top-level callback_url to receive a flat task object after finished or failed.
Network errorsDistinguish request timeout, network failure, and task failure. Retry the same query only when safe.

Model Specifications

Specification	Value	Details
Model	bytedance/seedream/v4/edit	Edit 1–10 reference images using text instructions.
size	1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 3:2 / 2:3 / 21:9	Default: 1:1.
resolution	1K / 2K / 4K	Default: 2K.
n	1–15	Default: 1. The number of image_urls plus n totals 15 or fewer.

Seedream 4 Edit API documentation

Seedream 4 Edit

Seedream 4 Edit is a high-fidelity image editing model developed by the ByteDance Seed team. Built on a unified DiT architecture, it natively supports 1 to 10 reference images for mask-free localized modifications, texture replacement, and cross-scene fusion. The model strictly maintains subject identity and outputs up to 4K resolution at 5 credits ($0.025) per image.

Why Choose Seedream 4 Edit API?

1–10 Reference Image Fusion & Semantic Role AssignmentNatively accepts 1 to 10 ordered reference images, allowing intuitive prompts like "use Image 1 for the subject and Image 2 for the background" to blend multi-source assets into a cohesive visual.
Mask-Free Natural Language Editing & Texture ReplacementEliminates cumbersome manual masking; describe edits in conversational language to achieve localized color correction, background changes, atmospheric transitions, and realistic material swaps.
Subject Identity & Environmental Lighting PreservationUtilizes deep feature decoupling and spatial reasoning to maintain facial identity, hair texture, and natural environmental illumination while modifying attire, background, or pose.
1–15 Batch Variations & Flexible Multi-Aspect RatiosGenerates multiple compositional or stylistic variations in a single run across eight standard aspect ratios and up to 4K resolution, accelerating design exploration and asset turnaround.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe the requested changes in 1–5,000 characters. Leading and trailing whitespace is not counted.
image_urls	Required	1–10 ordered HTTP(S) reference image URLs. The number of image_urls plus n totals 15 or fewer.
size	Optional	Output aspect ratio. Defaults to 1:1. Default`1:13:44:316:99:163:22:321:9`
resolution	Optional	Output resolution preset: 1K, 2K, or 4K. Defaults to 2K. Default`2K1K4K`
n	Optional	Number of images to generate: integer 1–15. Defaults to 1. The number of image_urls plus n totals 15 or fewer. Default`123456789101112131415`

How to Use

Prepare and Supply Reference ImagesGather 1 to 10 accessible HTTP(S) image URLs or upload local images in the console, noting the order and key elements of each asset (such as character, background, or prop).
Draft Clear Editing Prompts with Asset ReferencesExplicitly reference images in your prompt, e.g., "Place the character from Image 1 into the beach setting of Image 2, retaining the face and attire from Image 1 under warm sunset lighting."
Configure Ratios, Batch Count, and Retrieve AssetsChoose the aspect ratio, resolution (1K, 2K, or 4K), and image count n (ensuring reference images plus n totals 15 or fewer), then submit the task asynchronously to retrieve your output URLs.

Pricing

Each image costs 5 credits ($0.025). The total is 5 × n credits, where n is the number of generated images.

Usage	Rate	Details
Standard generation	5 credits/image · $0.025/image	5 × n credits · $0.025 × n
n = 1 / 5 / 10 / 14	5 / 25 / 50 / 70 credits	$0.025 / $0.125 / $0.250 / $0.350

Best Use Cases

E-Commerce Merchandising & Background ReplacementSeamlessly composite studio product or model photography into diverse lifestyle environments, automatically harmonizing perspective and contact lighting while keeping product geometry intact.
Multi-Asset Feature Extraction & Visual FusionCombine character designs, specific garments, and environment concepts across multiple input images into unified marketing collateral and brand visuals.
Mask-Free Portrait Refinement & Detail SwappingModify hair styles, clothing colors, accessories, or background ambiance without manual masks, ensuring complete facial identity preservation and natural skin textures.
Multi-Angle Concept Exploration & Batch IterationUse reference assets with batch generation (n > 1) to explore multiple lighting conditions, camera angles, and framing layouts in parallel for rapid pre-production sign-off.

Pro Tips

Explicitly Assign Asset Roles: Clearly designate the purpose of each reference in the prompt (e.g., "Image 1 is the main subject, Image 2 is the background, and Image 3 is the clothing style") to prevent semantic confusion.
Use Structured Preservation Commands: Frame instructions affirmatively specifying what to freeze and what to change (e.g., "Retain the facial identity and hair from Image 1 while changing the background to a modern architectural loft").
Harmonize Lighting Across Sources: Specify a dominant light direction and color temperature (such as "unified warm golden-hour sidelight") so composited elements seamlessly blend with the new environment.
Plan Around Total Image Limits: Ensure that the number of reference images plus generated images n does not exceed 15 (for example, if uploading 5 references, n can be at most 10).

Notes

Image Edit Endpoint Input Scope: This endpoint requires 1 to 10 publicly accessible HTTP(S) image URLs (PNG, JPEG, or WEBP). To generate images purely from natural language text, use the Seedream 4 Text to Image endpoint.
Total Asset and Output Ceiling: The total count of reference images in image_urls plus the output count n cannot exceed 15, and the prompt must be between 1 and 5,000 characters.
Zero Surcharge for Inputs & Full Refund Guarantee: Inputting reference images is completely free of charge; you are billed strictly for generated images at 5 credits each. Any failed task triggers an immediate and automated credit refund.

Related Models

Grok Imagine Image 2.0 Text to Image preview

Grok Imagine Image 2.0 Text to ImageGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Grok Imagine Image 2.0 EditGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Qwen Image 3.0 Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Text-to-Image preview

Qwen Image 3.0 Pro Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Seedream 5.0 Pro Text-to-ImageThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

Seedream 5.0 Pro Image EditThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

Nano Banana 2 Lite Text to Image preview

Nano Banana 2 Lite Text to ImageGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Nano Banana 2 Lite EditGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Grok Imagine Image Quality Text to Image preview

Grok Imagine Image Quality Text to ImageGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

Grok Imagine Image Quality EditGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

GPT Image 2 Text-to-ImageOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

GPT Image 2 Image EditOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

Wan 2.7 Image Standard Text to Image preview

Wan 2.7 Image Standard Text to ImageCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

Wan 2.7 Image Standard EditCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

Seedream 4 Edit API frequently asked questions

What is the Seedream 4 Edit API?

Seedream 4 Edit is a ByteDance Seed model for multi-image fusion and high-fidelity image editing. It natively accepts 1–10 reference images, provides mask-free localized adjustments, semantic role assignment, and cross-scene asset composition, with batch generation of 1–15 variations. Built on an efficient Diffusion Transformer (DiT) and high-compression VAE unified architecture, it utilizes deep feature decoupling and spatial reasoning to follow instructions closely while preserving facial identity, fine textures, and realistic environmental lighting. You can call it programmatically or try it from the playground above.

How many reference images does Seedream 4 Edit support?

Seedream 4 Edit natively supports 1 to 10 ordered reference images via publicly accessible HTTP(S) URLs (PNG, JPEG, or WEBP). In your prompt, you can use clear designations such as "Image 1" and "Image 2" to assign semantic roles (such as main subject, replacement background, or clothing reference) for high-fidelity multi-source composition.

Is manual masking required to use Seedream 4 Edit?

No. Seedream 4 Edit employs an advanced mask-free editing paradigm without requiring manual selection painting or mask uploads. Guided by deep natural language understanding, the model automatically pinpoints the target regions described in your prompt and executes seamless replacements with harmonious lighting boundaries.

How does Seedream 4 Edit maintain subject identity consistency?

The model incorporates deep facial feature decoupling and identity-locking representations. When modifying environments, clothing, or poses according to your prompt, it maintains facial bone structure, skin texture, and expressive characteristics to prevent identity drift or distortion.

What is the total image limit for Seedream 4 Edit?

In any single request, the sum of reference images in image_urls (1–10) plus the generated images n (1–15) cannot exceed 15. For instance, if you submit 3 reference images, n can be up to 12; if you supply 10 reference images, n can be up to 5.

Can Seedream 4 Edit change the image aspect ratio or resolution?

Yes. When submitting an edit request, you can freely specify the size parameter across eight aspect ratios (such as 16:9, 9:16, or 1:1) and configure the resolution parameter to 1K, 2K, or 4K. The model intelligently extends boundaries and recomposes spatial elements to fit the desired aspect ratio.

Does providing multiple reference images increase the cost for Seedream 4 Edit?

No. Seedream 4 Edit is billed strictly based on the number of generated images, at 5 credits ($0.025) per image. Supplying anywhere from 1 to 10 reference images incurs no additional fees. If a task fails, all pre-deducted credits are automatically refunded.