# Image Editing Best Practices

Image Editing is best when you already have an image and want to change, clean, extend, relight, restyle, or repurpose it without starting from scratch. Bria’s stack combines a structured edit-planning step with endpoint-specific tools for removal, fill, background work, cropping, expansion, and upscale.

## The Big Picture

Before diving into specific endpoints, it helps to understand the core mental model of Bria's editing pipeline.

details
summary
strong
Q: What’s the best mental model for getting clean edits?
p
Think like a designer in three layers: 
strong
what changes
, 
strong
what must stay unchanged
, and 
strong
what must match visually
. The strongest results come from prompts that are clear and descriptive, written in full sentences, structured around subject/context/style, and refined through small iterative changes rather than giant rewrites. For editing specifically, repeatedly restating the invariants—camera angle, identity, label details, lighting, background—helps prevent drift.
details
summary
strong
Q: What should users pay the most attention to for precision?
p
Four things matter most:
ul
li
strong
Masks:
 Use them whenever the edit should stay local.
li
strong
Invariants:
 Always state what must not change.
li
strong
Physical integration:
 Ask for matching shadows, perspective, scale, and texture.
li
strong
Iteration discipline:
 Lock the seed while refining wording or masks, then vary the seed only after the edit spec is correct.
details
summary
strong
Q: How should I write a strong image-edit prompt?
p
Use this formula: 
code
Target + change + invariants + integration cues
.
p
em
Example:
 "Replace the bottle cap with brushed aluminum. Keep the bottle shape, label text, camera angle, and background unchanged. Match reflections and contact shadows to the original studio lighting."
details
summary
strong
Q: How should I use masks professionally?
p
Keep masks slightly larger than the object edge so the model has room to blend. Bria says masked areas are regenerated; in practice, paint just beyond the contour—especially around hair, glass, fabric edges, and object contact points.
> **ℹ️ HOW MASKS WORK IN BRIA:** > Masks in `/image/edit` trigger **generative replacement**, not pixel retouching. The masked area should be treated as “regenerate this region” rather than “touch up this region.” Keep masks slightly larger than the object edge (especially around hair, glass, fabric, and contact points) so the model has room to blend.


> **ℹ️ ASYNCHRONOUS ENDPOINTS:** > By default, all Bria v2 endpoints are asynchronous - the API returns a `request_id` and a `status_url` immediately, and you poll that URL until the result is ready. Pass `sync: true` only if you need a synchronous response for simple integrations.


## Endpoint-by-Endpoint Guides

### POST `/v2/image/edit`

The master endpoint for full-image edits, masked local edits, or structured JSON-driven edits.

details
summary
strong
Q: How do I get the best results?
p
Treat it like your master editing endpoint. Use a mask whenever you care about local precision. In the instruction, state: what changes, what stays fixed, and what must match. Good prompts are explicit and constraint-heavy (e.g., "Replace only the chair upholstery with deep green velvet. Preserve chair shape, room lighting, floor shadows, and camera angle...").
> **💡 DESIGNER TIP:** > Use this route when your request is multi-constraint (e.g., "change material, but keep label and lighting"). Specialized routes are faster when the task is narrow, but `/image/edit` is better when art direction matters more than convenience.


### POST `/v2/image/edit/add_object_by_text`

Adds a new object with natural language.

details
summary
strong
Q: How do I get the best results?
p
Prompt for object + material + approximate size + location + physical integration. A good instruction is not just "add a lamp"; it is "Add a small brushed-steel desk lamp on the far-right edge of the wooden desk, angled toward the center, with a soft contact shadow..."
### POST `/v2/image/edit/replace_object_by_text`

Swaps an object that is visually obvious.

details
summary
strong
Q: How do I get the best results?
p
Make the target object unambiguous: left/right, front/back, color, size. Then add invariants like "preserve camera angle, surrounding objects..." If there are many similar objects, use a mask-based route instead.
### POST `/v2/image/edit/erase` vs. `/erase_by_text`

Endpoints dedicated to removing elements from a scene.

details
summary
strong
Q: When should I use `/erase` and when `/edit/erase_by_text`?
p
Use 
strong
`/erase`
 when you can provide a mask and need maximum control. This endpoint regenerates only the masked region and keeps everything outside the mask pixel-perfect.
p
Use 
strong
`/edit/erase_by_text`
 when you prefer natural language (e.g., 
code
object_name: "table"
). This is easier but may introduce minor global adjustments, since the model interprets the scene holistically.
### POST `/v2/image/edit/blend`

Merges visual elements, applies graphics, or rearranges elements.

details
summary
strong
Q: How do I get the best results?
p
Tell the model both what to transfer and how it should behave physically. For example: "Apply the graphic to the fabric so it follows the shirt folds, preserve the artwork exactly, match shirt wrinkles and lighting..."
### POST `/v2/image/edit/gen_fill`

Generates content inside a specific masked region (optimized for blob-shaped masks).

details
summary
strong
Q: How do I get the best results?
p
Prompt the masked region as if you were art-directing a cropped micro-scene: name the object, describe its material and size, specify how it interacts with the surface, and ask for a contact shadow. Keep prompts around 90–110 words and leave 
code
refine_prompt
 enabled.
### Background Workflows

Endpoints for manipulating, blurring, or replacing backgrounds.

details
summary
strong
Q: Which background generation mode should users pick for `/replace_background`?
p
Use 
strong
high_control
 (~90-110 words) because it adheres more closely to the prompt and produces creative, polished marketing-style results.
p
Use 
strong
fast
 or 
strong
base
 (~50-60 words) when speed, stability, and strict product preservation are more important than creativity.
details
summary
strong
Q: How do I get the best results with `/remove_background`?
p
Feed it the highest-resolution source available, especially for hair, glass, or fur. Keep 
code
preserve_alpha=true
 if the image already contains useful transparency.
### POST `/v2/image/edit/expand`

Outpaints an image for a new aspect ratio or canvas size.

details
summary
strong
Q: Are there any size limits when using manual placement?
p
Yes. The maximum allowed canvas area is 25 million pixels (width × height must not exceed 5,000 × 5,000). Exceeding this returns a 400 error or forces a resize.
details
summary
strong
Q: How do I get the best results?
p
Use 
code
aspect_ratio
 (e.g., "9:16", "4:5") when the goal is channel-fit. Use manual placement when art direction matters, like creating copy space on one side. Keep the visible subject above 15% of the total canvas area.
### Upscaling: `/enhance` vs. `/increase_resolution`

Endpoints to increase the pixel dimensions of your output.

details
summary
strong
Q: What is the difference between `/enhance` and `/increase_resolution`?
p
Use 
strong
`/enhance`
 when you want a creative upscaling effect. It fixes artifacts, improves textures, and adds visual richness (great for low-quality sources).
p
Use 
strong
`/increase_resolution`
 for authentic upscaling that preserves the original image exactly while increasing its size (2x or 4x). Ideal for product imagery where strict fidelity is critical.
## Fast Style & Mood Transformations

For single-purpose creative adjustments, choose the specialized route over the master `/image/edit` endpoint.

details
summary
strong
Q: Is there a good rule for choosing among these “single-purpose” endpoints?
ul
li
strong
Relight:
 When the scene is right but the lighting is wrong.
li
strong
Restyle:
 When the composition is right but the artistic language is wrong.
li
strong
Reseason:
 When the scene should feel like a different time of year or weather.
li
strong
Colorize:
 When the tonal treatment is wrong or the photo is black and white.
li
strong
Restore:
 When the image is damaged.
li
strong
Sketch to Image:
 When the input is a drawing rather than a photo.
## Final Designer Rules

details
summary
strong
Q: What are the most important non-obvious rules for professional-looking edits?
ul
li
strong
Do layout prep first:
 Crop, isolate, or expand before heavy edits.
li
strong
Keep prompts surgical:
 Name the change and the invariants.
li
strong
Think physically:
 Always ask for matching scale, light, texture, reflection, and shadow.
li
strong
Use masks for trust:
 If an area must not move, protect it.
li
strong
Do creative changes before upscale:
 Upscale only after content is approved.