Seedream 5.5 API Guide: Generate, Edit, and Layer Images

YYunus Emre Özdiyar 11 min
Developer reviewing generated image variations in a multi-monitor image production workspace

Use the Seedream 5.5 API for 1K and 2K image generation, reference-guided edits, multiple outputs, and transparent image layers with imageat.

On this page
  1. Seedream 5.5 API at a Glance
  2. What Seedream 5.5 Is Best For
  3. Before You Send a Request
  4. Minimal Text-to-Image Request
  5. Reference-Guided Generation and Editing
  6. Generate Multiple Variations Without Creating Noise
  7. A Node.js Request Pattern
  8. How to Write Better Seedream 5.5 Prompts
  9. 1. Deliverable
  10. 2. Subject
  11. 3. Environment
  12. 4. Camera and composition
  13. 5. Light and finish
  14. 6. Constraints
  15. Turn an Image Into Transparent Layers
  16. Common Failure Modes and Fixes
  17. The product changes too much
  18. The references fight each other
  19. Text is misspelled
  20. The output is expensive at scale
  21. A reference URL fails
  22. The final asset needs cleanup
  23. Production Checklist
  24. Frequently Asked Questions
  25. What is the Seedream 5.5 model ID on imageat?
  26. Can Seedream 5.5 edit an existing image?
  27. Does the API support 2K images?
  28. How much does Seedream 5.5 cost on imageat?
  29. Can Seedream 5.5 return transparent layers?
  30. Is the Seedream 5.5 API free?
  31. Should I use all 10 reference slots?
  32. Start Building With Seedream 5.5

The Seedream 5.5 API is a practical choice when an application needs both image generation and reference-guided editing. On imageat, the model supports 1K or 2K output, up to 10 reference images, common aspect ratios, and multiple images per request. A separate layerization feature can split a finished image into a base plus transparent PNG layers for design and editing workflows.

This guide shows how to call the model, structure prompts, use references without losing control, process the response, and decide when layerization is worth the extra step. The examples follow the current imageat API documentation, where the model ID is seedream-5.5 and image requests use POST /v1/images.

Seedream 5.5 API at a Glance

The current imageat implementation exposes these core controls:

  • Model ID: seedream-5.5
  • Endpoint: POST https://api.imageat.com/v1/images
  • Modes: text-to-image and reference-guided generation or editing
  • Resolution: 1K or 2K
  • Reference images: up to 10 public image URLs
  • Output count: controlled with numImages
  • Starting API price: $0.06 for one 1K image
  • Layer decomposition: the separate layerize feature on POST /v1/edit

Pricing and supported parameters can change. Confirm the live model entry on the API pricing page before estimating a production batch. API use consumes prepaid API balance; it is not a free local workflow.

What Seedream 5.5 Is Best For

Seedream 5.5 is especially useful when the brief depends on visual references rather than text alone. Ten reference slots allow an application to provide separate evidence for a product, character, wardrobe, environment, palette, or composition. That does not mean every request should use all ten. It means the model can support a more structured visual brief when the project genuinely needs it.

Good fits include:

  • Product scenes built from approved pack shots
  • Character variations that need recognizable clothing and styling
  • Campaign concepts that combine a subject with a separate art-direction reference
  • E-commerce or social variations in several aspect ratios
  • Iterative image editing where the source image should remain the foundation
  • Design handoff workflows that need transparent layers after generation

For a one-off image without integration work, the browser-based image generator is usually faster to start. Use the API when the request must come from an app, queue, backend service, agent, or repeatable content pipeline.

Before You Send a Request

Create an API key in imageat and keep it on the server. Never place a permanent key in browser JavaScript, a mobile application bundle, a public repository, or a screenshot. Load it through an environment variable such as IMAGEAT_API_KEY.

Your reference images must be reachable through public URLs when you pass them in images. A URL that works only inside a private dashboard, depends on a login cookie, or expires before the generation worker reads it can fail. For user uploads, copy the file to controlled object storage, set an appropriate expiry, and remove it according to your retention policy after the job finishes.

Also decide these four things before coding:

  1. Is this a new image or an edit of an existing one?
  2. Which visual facts are fixed, and which may change?
  3. Is 1K enough for the current review stage, or is 2K required?
  4. Does the user need one answer or several variations?

Those decisions should determine the request fields. Do not default every call to the largest resolution and highest output count.

Minimal Text-to-Image Request

A basic request needs authorization, the model ID, and a prompt. This example asks for a square 1K image:

curl -X POST "https://api.imageat.com/v1/images" \
-H "Authorization: Bearer $IMAGEAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5.5",
"prompt": "Editorial product photograph of a brushed-steel travel bottle on pale limestone, soft window light from the left, restrained sage and cream palette, realistic condensation, clean background, no people, no extra text",
"aspectRatio": "1:1",
"resolution": "1K",
"outputFormat": "png",
"numImages": 1
}'

The prompt describes the deliverable rather than the model. It names the subject, material, surface, light, palette, realism level, and exclusions. That is more reliable than filling the request with praise words such as “stunning,” “epic,” or “award-winning.”

Use 1K while testing composition and art direction. Move an approved direction to 2K when the larger output is necessary. If the final asset only needs a small card or thumbnail, generating at 2K by default adds cost and transfer weight without solving a real problem.

Reference-Guided Generation and Editing

Add public URLs to images when the model needs visual evidence. The same field can support editing and reference-guided generation, so the prompt must explain the role of each image.

curl -X POST "https://api.imageat.com/v1/images" \
-H "Authorization: Bearer $IMAGEAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5.5",
"prompt": "Use image 1 for the exact bottle shape, cap, material, and label placement. Use image 2 only for the warm window-light direction and limestone color palette. Create a new horizontal product scene with the bottle centered slightly right. Preserve all product proportions. Do not copy objects or text from image 2.",
"images": [
"https://assets.example.com/approved-bottle.png",
"https://assets.example.com/lighting-reference.jpg"
],
"aspectRatio": "16:9",
"resolution": "2K",
"outputFormat": "png",
"numImages": 1
}'

Number the references in the same order as the array. Give each one a single job. “Use these images as references” is too vague when one file contains the product and another contains the mood. The model has to guess whether it should copy composition, color, identity, typography, or all of them.

A stronger reference brief separates three categories:

  • Preserve: identity, product geometry, logo placement, wardrobe, or camera angle
  • Borrow: lighting, palette, texture, or photographic treatment
  • Change: background, crop, pose, season, prop arrangement, or aspect ratio

If one source image already contains the composition you want, edit that image directly instead of rebuilding it from several references. For tightly masked changes to a specific area, the dedicated inpainting workflow may be more appropriate than asking a general generation request to infer the edit boundary.

Generate Multiple Variations Without Creating Noise

numImages is useful when a user needs alternatives, but multiple outputs are only valuable if they answer a defined question. Generate three compositions from one stable brief, for example, rather than changing the prompt, references, ratio, and resolution at the same time.

A disciplined variation loop looks like this:

  1. Generate several 1K options with the same references.
  2. Reject results that violate fixed product or identity details.
  3. Select one composition.
  4. Revise one variable, such as camera height or background color.
  5. Produce the approved direction at 2K.
  6. Run any cleanup or layerization only on the selected image.

This reduces unnecessary paid calls and makes feedback interpretable. If the team says version three is better, you should know which creative decision made it better.

A Node.js Request Pattern

The following server-side example validates the input, sends one request, and throws a useful error instead of silently accepting a failed response:

const API_URL = "https://api.imageat.com/v1/images";

async function generateWithSeedream({ prompt, images = [] }) {
if (!prompt || prompt.trim().length < 20) {
throw new Error("A specific prompt is required");
}
if (images.length > 10) {
throw new Error("Seedream 5.5 supports up to 10 reference images");
}

const response = await fetch(API_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEAT_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "seedream-5.5",
prompt,
images,
aspectRatio: "4:5",
resolution: "1K",
outputFormat: "png",
numImages: 1
})
});

const payload = await response.json();
if (!response.ok) {
throw new Error(payload.error || `Image request failed: ${response.status}`);
}
return payload;
}

In production, also set a request timeout, log a request ID rather than the API key, and store the generation record with the user, prompt version, reference IDs, and intended use. Do not log private image URLs or personal prompts into a broadly accessible analytics tool.

Read the live response example in the API docs before binding your code to a field. Treat generated URLs as outputs to ingest into your own storage policy, not as permanent database guarantees unless the documentation explicitly says they are permanent.

How to Write Better Seedream 5.5 Prompts

A useful production prompt can be assembled in six parts:

1. Deliverable

State what you are making: a marketplace hero image, portrait, packaging concept, poster background, social ad, or editorial illustration.

2. Subject

Describe the visible subject with concrete properties. For products, include material, color, shape, orientation, and approved details. For people, include pose, expression, wardrobe, and framing without inventing sensitive attributes.

3. Environment

Name the surface, background, location, weather, and supporting objects. Keep props limited when the product must remain dominant.

4. Camera and composition

Specify shot distance, camera height, lens character, negative space, and placement. “Wide horizontal composition with clean space on the left” is more actionable than “make it cinematic.”

5. Light and finish

Describe direction, softness, contrast, palette, texture, and realism. Avoid combining incompatible instructions such as hard noon sun and soft shadowless studio light.

6. Constraints

List only important exclusions: no extra products, no invented labels, no hands, no watermark, or no text. A long negative-prompt dump can conflict with the positive brief.

For repeated campaigns, store these parts as structured fields and render the final prompt from a template. That makes revisions auditable and prevents a brand rule from disappearing when another field changes.

Turn an Image Into Transparent Layers

The standard Seedream 5.5 request generates or edits a flat image. If your next step requires movable design elements, imageat exposes a separate layerize edit feature through POST /v1/edit.

The current feature can return a base image plus transparent PNG layers. options.maxLayers controls the maximum number of returned images, including the base, from 2 to 12; the default is 6. Setting options.textRecognition to true adds OCR text information to detected text layers.

curl -X POST "https://api.imageat.com/v1/edit" \
-H "Authorization: Bearer $IMAGEAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"feature": "layerize",
"imageUrl": "https://assets.example.com/approved-campaign-image.png",
"prompt": "Separate the product, foreground leaves, headline area, and background",
"options": {
"maxLayers": 6,
"textRecognition": true
}
}'

The response includes urls, with the base first and transparent layers after it, plus layer position and stacking information. Preserve that order in your application. A pile of transparent PNG files without coordinates and stack order is not a reusable composition.

Layerization is billed separately from image generation. The current documentation describes a cost of about $0.07 per returned image plus $0.03 for the input, with the feature listed from $0.15. Check the live pricing before making it an automatic step for every generation.

Use layerization selectively. It is valuable when a designer needs to reposition elements, localize text, animate foreground and background separately, or build a reusable template. It is unnecessary when the final image will be downloaded and published as a single flat asset.

Common Failure Modes and Fixes

The product changes too much

Use one clean product reference as the primary source. State which shape, proportions, colors, and label positions must remain fixed. Remove mood references that contain competing products.

The references fight each other

Assign a role to every URL. If two references define different lighting or camera angles, choose one. More references do not automatically mean more control.

Text is misspelled

Treat generated typography as a draft. Keep important copy short, verify every character, or add final text in a design tool after generation. Layerization can help separate editable regions, but OCR metadata does not guarantee perfect generated lettering.

The output is expensive at scale

Prototype at 1K with one image. Increase numImages only for deliberate testing, and send the chosen result to 2K or layerization. Review the current API pricing instead of hard-coding an old estimate.

A reference URL fails

Fetch the URL from the same environment that runs the integration. Confirm it returns the actual image bytes, not an HTML login page, redirect loop, or expired signed-URL message.

The final asset needs cleanup

Use the broader AI photo editor for finishing tasks, or the image upscaler when the approved image needs a larger delivery size. Do not regenerate a successful composition merely to remove a small defect if a targeted edit can preserve more of the original.

Production Checklist

Before releasing a Seedream 5.5 integration, verify:

  • The API key is stored only on the server
  • Prompts and references are authorized for the intended use
  • Every reference URL returns valid image bytes
  • The request rejects more than 10 references
  • 1K and 2K are selected intentionally
  • Output count has a product-level limit
  • Errors are shown to the user without exposing credentials
  • Generated images are checked for text, identity, product, and brand errors
  • Layer order and coordinates are retained when using layerize
  • Cost is logged from real requests rather than estimated forever from a launch price
  • Private uploads and generated outputs follow a clear retention policy

The imageat model catalog is useful when a project needs a different image model or control set. Switching models should be a product decision based on the deliverable, not an assumption that one model wins every prompt.

Frequently Asked Questions

What is the Seedream 5.5 model ID on imageat?

Use seedream-5.5 in requests to POST /v1/images.

Can Seedream 5.5 edit an existing image?

Yes. Pass one or more public image URLs in the images array and explain what should be preserved and changed. The current imageat implementation supports up to 10 references.

Does the API support 2K images?

Yes. The current implementation supports 1K and 2K resolution. Use 1K for inexpensive iteration and 2K when the approved output needs the larger size.

How much does Seedream 5.5 cost on imageat?

The current starting price is $0.06 for one 1K image. Resolution, output count, separate editing features, and future pricing changes can affect the total. Layerization has its own billing.

Can Seedream 5.5 return transparent layers?

The image generation endpoint returns a finished image. Use the separate layerize feature on POST /v1/edit to split an image into a base plus transparent PNG layers.

Is the Seedream 5.5 API free?

No. API requests use prepaid balance and are billed according to the selected operation. You can write and test request code locally for free, but an actual model generation is a paid API call.

Should I use all 10 reference slots?

Only when each reference has a clear role. One strong source plus one art-direction reference often provides a cleaner brief than ten overlapping images.

Start Building With Seedream 5.5

Begin with one 1K output and a narrow brief. Add references only when they communicate a specific visual fact, move to 2K after the direction works, and reserve layerization for assets that genuinely need editable components.

Use the imageat API documentation for the current request and response schema, model list, authentication details, and live examples before shipping your integration.

Developer reviewing generated image variations in a multi-monitor image production workspacePin it for laterSave this guide to your Pinterest board

Share

Try it yourself
on imageat

Everything in this guide runs in the browser. Start with a free account and pay per generation.

Discover more

View all