Endpoints that are part of BRIA API version 2.
- Generate Structured Instruction
Overview
Bria's Image Editing API equips builders with a comprehensive suite of tools for manipulating and enhancing images, ranging from open-ended textual edits to specialized, task-specific operations.
General Image Editing (FIBO Edit)
Powered by the FIBO models family, our newest endpoints enable open-ended editing using natural language instructions. This allows for:
- Global Edits: Modify the style, lighting, or atmosphere of an entire image via text prompts.
- Localized Edits: Use native masking support to precisely alter specific regions while preserving the rest of the image.
- Structured Control: Convert text instructions into structured JSON for deterministic and auditable results.
Specialized Capabilities
For focused, high-volume tasks, the API provides optimized endpoints for specific editing capabilities:
- Background Operations: Removal, replacement, and blur.
- Content Manipulation: Eraser (object removal) and generative fill.
- Image Transformation: Expansion (outpainting), resolution increase (upscaling), and automatic cropping.
- Object & Person Tools: Person modification and automatic mask generation.
Asynchronous Requests and the Status Service Bria API v2 endpoints process requests asynchronously by default. When you make an asynchronous request, the API immediately returns a request_id and a status_url instead of the final result. Use the Status Service to track the request's progress until it reaches a completed state.
See the full guide at Status Service Documentation for complete details and usage examples.
Request
Description
Powered by the FIBO models family, Bria’s Image Editing by Text API equips builders with the ability to modify existing images using natural language instructions or structured JSON instructions.
FIBO Edit features native masking support for precise, localized editing. You can supply a binary mask to restrict changes to specific regions while preserving the rest of the image.
The masking logic operates as a generative replacement; the model generates entirely new content within the masked area based on your instruction, rather than modifying the existing pixels.
Core Technology: The FIBO Architecture
This endpoint utilizes the FIBO architecture, a unique two-step process ensuring precise and controllable edits:
- Translation: A VLM Bridge (powered by Gemini 2.5 Flash) converts your inputs into a detailed
structured_instruction(JSON). - Generation: The FIBO Edit model performs the final, deterministic edit on the input image, based on that JSON.
Advanced Control & Recreation
- To recreate a specific result: You must provide the exact source images, the mask (if used), the
structured_instructionreturned in the original response, and theseedused to create it. - For advanced, programmatic control, you can pass in your own
structured_instruction(e.g., from the/v2/structured_instruction/generateendpoint) to bypass the internal VLM bridge.
Input Combination Rules
The request body must include images and one of the following combinations:
- Global Edit (natural language):
images+instruction - Global Edit (JSON instruction):
images+structured_instruction - Masked Edit (natural language):
images+mask+instruction - Masked Edit (JSON instruction):
images+mask+structured_instruction
API Access
You can register and access the API Token through Bria's platform by clicking here.
Examples
Use Case 1: Lighting Change
Instruction: "change to golden hour"
| Input Image | Output Image |
|---|---|
![]() | ![]() |
Click to view the Output Structured Instruction (JSON)
{
"short_description": "A vibrant yellow train with multiple carriages stretches across a vast, reflective salt flat under a golden hour sky. The train's reflection is perfectly mirrored in the still, shallow water, creating a symmetrical and surreal scene. Fluffy white clouds are scattered across the sky, also reflected in the water, adding depth and texture to the expansive landscape. The warm, soft light of the golden hour bathes the entire scene, enhancing the colors and creating a serene and magical atmosphere.",
"objects": [
{
"description": "A long, multi-car passenger train, painted in a bright, somewhat weathered yellow. The front locomotive is robust, with visible details like railings, windows, and industrial components. The carriages behind it are also yellow, with numerous windows reflecting the sky.",
"location": "center, extending from mid-left to far right",
"relationship": "The train is the primary subject, dominating the central horizontal axis and creating a strong leading line into the distance. Its reflection is a key compositional element.",
"relative_size": "large within frame",
"shape_and_color": "Elongated, rectangular, bright yellow with some darker accents.",
"texture": "Metallic, slightly weathered, with visible rivets and panels.",
"appearance_details": "The train appears to be a diesel locomotive with several passenger cars, showing signs of use but maintaining its vibrant yellow color.",
"orientation": "Horizontal, moving from left to right into the distance."
},
{
"description": "The perfect, clear reflection of the yellow train in the still, shallow water of the salt flat. The reflection is almost identical to the train above, creating a strong sense of symmetry.",
"location": "below the train, in the lower half of the frame",
"relationship": "This object is the mirror image of the train, completing the symmetrical composition and emphasizing the reflective quality of the salt flat.",
"relative_size": "large within frame",
"shape_and_color": "Elongated, rectangular, bright yellow.",
"texture": "Smooth, watery, with slight distortions from the water's surface.",
"appearance_details": "The reflection includes all details of the train, including windows and structural elements.",
"orientation": "Horizontal, mirroring the train above."
},
{
"description": "Numerous large, fluffy cumulus clouds scattered across the sky. They are bright white with soft, warm undertones from the golden hour light.",
"location": "top half of the frame",
"relationship": "The clouds fill the upper portion of the sky, providing a backdrop for the train and contributing to the overall sense of vastness. Their reflections are also visible in the water.",
"relative_size": "large within frame",
"shape_and_color": "Irregular, billowy, white with golden hues.",
"texture": "Soft, ethereal, cotton-like.",
"appearance_details": "The clouds vary in size and density, creating a dynamic sky.",
"orientation": "Scattered across the sky."
},
{
"description": "The reflections of the fluffy white clouds in the calm, shallow water of the salt flat. These reflections are as clear and defined as the clouds in the sky.",
"location": "bottom half of the frame",
"relationship": "These reflections mirror the clouds in the sky, enhancing the symmetrical composition and the illusion of the train floating on water.",
"relative_size": "large within frame",
"shape_and_color": "Irregular, billowy, white with golden hues.",
"texture": "Smooth, watery, with slight ripples.",
"appearance_details": "The reflections are almost perfect, indicating very still water.",
"orientation": "Mirrored below the clouds in the sky."
}
],
"background_setting": "A vast, flat salt plain covered with a thin layer of incredibly still, reflective water, extending to the horizon. In the far distance, a faint, low-lying landmass or shoreline is visible, blurring into the horizon. The sky is expansive and clear, filled with scattered cumulus clouds, all bathed in the warm glow of golden hour.",
"lighting": {
"conditions": "golden hour",
"direction": "Side-lit, with warm, low-angle light coming from the side, likely from the left or right, casting soft, elongated highlights.",
"shadows": "Soft, elongated shadows are cast by the train and clouds, blending subtly with the reflections in the water, contributing to the overall warm and diffused light."
},
"aesthetics": {
"composition": "Symmetrical composition with the train positioned centrally, creating a strong horizontal line that divides the sky and its reflection. Leading lines are formed by the train and its reflection, drawing the eye towards the vanishing point on the horizon.",
"color_scheme": "Warm complementary colors, dominated by the bright yellow of the train against the soft blues and oranges of the golden hour sky and water. White clouds provide contrast.",
"mood_atmosphere": "Serene, magical, and expansive, with a sense of wonder and tranquility enhanced by the soft, warm light.",
"preference_score": "very high",
"aesthetic_score": "very high"
},
"photographic_characteristics": {
"depth_of_field": "Deep, with both the foreground train and the distant horizon appearing in sharp focus.",
"focus": "Sharp focus on the train and its reflection, extending clearly into the background.",
"camera_angle": "Eye-level, providing a direct and immersive view of the scene.",
"lens_focal_length": "Standard lens (e.g., 35mm-50mm) to capture the expansive landscape while maintaining detail on the train."
},
"style_medium": "photograph",
"context": "This is a fine art landscape photograph, emphasizing the surreal beauty of nature and human engineering, suitable for display in a gallery or as a travel magazine feature.",
"artistic_style": "realistic",
"edit_instruction": "Change the lighting to golden hour."
}Use Case 2: Masked Text Addition
Instruction: "Write FIBO ROCKS on all balloons, use dark creative font, different font for each balloon"
| Input Image | Input Mask | Output Image |
|---|---|---|
![]() | ![]() | ![]() |
Click to view the Output Structured Instruction (JSON)
{
"short_description": "A vibrant cluster of metallic balloons in shades of red, silver, and purple, each adorned with the text \"FIBO ROCKS\" in a unique, dark, creative font. The balloons are tied together with white ribbons and float against a soft, light green background, creating a festive and celebratory atmosphere.",
"objects": [
{
"description": "A large, metallic red balloon, reflecting light with a glossy sheen. It has \"FIBO ROCKS\" written on it in a dark, creative font.",
"location": "top-right",
"relationship": "Part of a cluster of balloons.",
"relative_size": "large within frame",
"shape_and_color": "Round, metallic red",
"texture": "Smooth, glossy",
"appearance_details": "Reflective surface showing subtle highlights.",
"orientation": "Slightly angled upwards"
},
{
"description": "A metallic purple balloon, with a deep, rich hue and a reflective surface. It has \"FIBO ROCKS\" written on it in a dark, creative font.",
"location": "center-right",
"relationship": "Nestled among other balloons in the cluster.",
"relative_size": "medium within frame",
"shape_and_color": "Round, metallic purple",
"texture": "Smooth, glossy",
"appearance_details": "Shows reflections of the surrounding environment.",
"orientation": "Upright"
},
{
"description": "A metallic silver balloon, appearing bright and reflective against the background. It has \"FIBO ROCKS\" written on it in a dark, creative font.",
"location": "mid-left",
"relationship": "Prominently positioned within the balloon cluster.",
"relative_size": "medium within frame",
"shape_and_color": "Round, metallic silver",
"texture": "Smooth, glossy",
"appearance_details": "Highly reflective, catching ambient light.",
"orientation": "Slightly angled downwards"
},
{
"description": "A cluster of several metallic balloons, including shades of red, silver, and purple, all tied together with white ribbons. Each balloon has \"FIBO ROCKS\" written on it in a unique, dark, creative font.",
"location": "center-right",
"relationship": "The main subject of the image, forming a cohesive group.",
"relative_size": "large within frame",
"shape_and_color": "Various round shapes, metallic red, silver, and purple",
"texture": "Smooth, glossy",
"appearance_details": "The balloons are inflated and appear to be floating, with ribbons trailing downwards.",
"number_of_objects": 12,
"orientation": "Clustered together, generally upright"
},
{
"description": "Thin, translucent white ribbons trailing downwards from the cluster of balloons.",
"location": "bottom-center",
"relationship": "Attached to the balloons, providing a sense of upward movement.",
"relative_size": "small",
"shape_and_color": "Thin, white, translucent",
"texture": "Smooth, delicate",
"appearance_details": "Flowing gently, some ribbons are intertwined.",
"orientation": "Vertical, trailing downwards"
}
],
"background_setting": "A plain, light green wall with a smooth texture, providing a clean and uncluttered backdrop for the balloons.",
"lighting": {
"conditions": "Bright, soft ambient light",
"direction": "Front-lit with some light from the right",
"shadows": "Subtle, soft shadows cast by the balloons on the wall, indicating depth."
},
"aesthetics": {
"composition": "Centered, with the balloon cluster occupying the majority of the right side of the frame, creating a balanced yet dynamic visual.",
"color_scheme": "Complementary colors of metallic reds, purples, and silvers against a soft green background, creating a festive and appealing palette.",
"mood_atmosphere": "Joyful, celebratory, and festive.",
"preference_score": "very high",
"aesthetic_score": "very high"
},
"photographic_characteristics": {
"depth_of_field": "Shallow, with the balloons in sharp focus and the background softly blurred.",
"focus": "Sharp focus on the balloon cluster.",
"camera_angle": "Eye-level",
"lens_focal_length": "Standard lens (e.g., 35mm-50mm)"
},
"style_medium": "photograph",
"text_render": [
{
"text": "FIBO ROCKS",
"location": "on each balloon",
"size": "medium",
"color": "dark",
"font": "creative, different for each balloon",
"appearance_details": "Each instance of the text uses a unique, dark, creative font style."
}
],
"context": "This is a celebratory photograph, possibly for an event or a brand promotion, featuring balloons with custom text.",
"artistic_style": "realistic",
"edit_instruction": "Add the text \"FIBO ROCKS\" to each balloon, using a dark, creative font, with a different font for each balloon."
}Use Case 3: Sketch to Realistic Photo
Instruction: "create a detailed realistic photo, with contemporary color scheme, and balanced exposure photo roughly based on this sketch"
| Input Image | Output Image |
|---|---|
![]() | ![]() |
Click to view the Output Structured Instruction (JSON)
{
"short_description": "A realistic photograph of a brown rabbit sitting on a natural ground surface, looking towards the left. The rabbit has soft fur, long ears, and a small fluffy tail. The scene is captured with a contemporary color scheme and balanced exposure, highlighting the natural textures and details of the animal.",
"objects": [
{
"description": "A realistic brown rabbit with soft, detailed fur, long ears, and a small, fluffy white tail. Its eyes are dark and observant, and its whiskers are delicate.",
"location": "center",
"relationship": "The main subject of the image, positioned centrally on the ground.",
"relative_size": "large within frame",
"shape_and_color": "Oval-shaped body, brown and white fur.",
"texture": "Soft, dense fur.",
"appearance_details": "Prominent whiskers, alert eyes, and a twitching nose.",
"pose": "Sitting with its front paws tucked under its chest and hind legs slightly extended, body slightly turned to the left.",
"expression": "Alert and curious.",
"action": "Sitting still, observing its surroundings.",
"orientation": "Facing left, slightly angled towards the viewer."
}
],
"background_setting": "A softly blurred natural ground surface, possibly grass or dirt, providing a subtle and unobtrusive backdrop that keeps the focus on the rabbit.",
"lighting": {
"conditions": "Bright, natural daylight with balanced exposure.",
"direction": "Evenly lit from above and slightly to the front.",
"shadows": "Soft, subtle shadows beneath the rabbit, indicating natural light."
},
"aesthetics": {
"composition": "Centered composition with the rabbit as the main focal point, creating a portrait-like feel.",
"color_scheme": "Contemporary natural color scheme with earthy tones and subtle greens/browns.",
"mood_atmosphere": "Calm, natural, and serene.",
"preference_score": "very high",
"aesthetic_score": "very high"
},
"photographic_characteristics": {
"depth_of_field": "Shallow depth of field, with the rabbit in sharp focus and the background softly blurred.",
"focus": "Sharp focus on the rabbit's face and fur.",
"camera_angle": "Eye-level, capturing the rabbit from its perspective.",
"lens_focal_length": "Portrait lens (e.g., 50mm-85mm)"
},
"style_medium": "photograph",
"context": "This is a realistic wildlife photograph, suitable for nature magazines, educational materials, or as a decorative print.",
"artistic_style": "realistic",
"edit_instruction": "Render a detailed realistic photograph of a brown rabbit sitting on a natural ground surface, looking towards the left, with a contemporary color scheme and balanced exposure."
}Use Case 4: Object Modification (Add Print)
Instruction: "add a bold modern print to the shirt"
| Input Image | Output Image |
|---|---|
![]() | ![]() |
Click to view the Output Structured Instruction (JSON)
{
"short_description": "A young woman with long, wavy brown hair stands against a solid pink background, making peace signs with both hands. She is wearing a white t-shirt with a bold modern print and dark pants, looking directly at the viewer with a calm expression and red lipstick.",
"objects": [
{
"description": "A young woman with long, wavy brown hair, styled with a middle part and some strands pulled back from her face. She has fair skin, full red lips, and a calm, direct gaze.",
"location": "center",
"relationship": "main subject of the image",
"relative_size": "large within frame",
"shape_and_color": "human form, fair skin, brown hair",
"texture": "smooth skin, wavy hair",
"appearance_details": "wearing red lipstick",
"pose": "standing with arms bent at the elbows, hands raised to shoulder height, making peace signs with both hands",
"expression": "calm, direct, slightly smiling",
"clothing": "a white t-shirt with a bold modern print and dark pants",
"action": "making peace signs",
"gender": "female",
"skin_tone_and_texture": "fair, smooth",
"orientation": "facing forward"
},
{
"description": "A white t-shirt with short sleeves and a crew neck, featuring a bold modern print on the front.",
"location": "center, on the woman's torso",
"relationship": "worn by the woman",
"relative_size": "medium",
"shape_and_color": "rectangular, white with a multi-colored print",
"texture": "cotton fabric",
"appearance_details": "The print is abstract and geometric, in contrasting colors.",
"orientation": "worn on the body"
}
],
"background_setting": "A plain, solid pink wall with no discernible features or textures.",
"lighting": {
"conditions": "bright studio lighting",
"direction": "front-lit",
"shadows": "minimal shadows, soft and diffused behind the subject"
},
"aesthetics": {
"composition": "centered, medium shot, portrait composition",
"color_scheme": "monochromatic pink background with a contrasting white shirt and red lips",
"mood_atmosphere": "casual, friendly, confident",
"preference_score": "very high",
"aesthetic_score": "very high"
},
"photographic_characteristics": {
"depth_of_field": "shallow",
"focus": "sharp focus on subject",
"camera_angle": "eye-level",
"lens_focal_length": "portrait lens (e.g., 50mm-85mm)"
},
"style_medium": "photograph",
"context": "This is a studio portrait photograph, likely for a fashion or lifestyle campaign, emphasizing a casual and confident style.",
"artistic_style": "realistic",
"edit_instruction": "Add a bold modern print to the white t-shirt worn by the subject."
}Use Case 5: Text Modification (Replace Text)
Instruction: "replace the text to Great Work FIBO!"
| Input Image | Output Image |
|---|---|
![]() | ![]() |
Click to view the Output Structured Instruction (JSON)
{
"short_description": "A small, round white cake with a red heart decoration is nestled in a light brown paper liner inside an open, off-white takeout container. The container rests on a stack of papers and a wooden surface, with the cake prominently featuring the text \"Great Work FIBO!\" in a mix of brown and black lettering.",
"objects": [
{
"description": "A small, round cake with smooth white frosting, decorated with a small red heart and text.",
"location": "center",
"relationship": "The cake is the main subject, sitting inside the takeout container.",
"relative_size": "large within frame",
"shape_and_color": "round, white",
"texture": "smooth frosting",
"appearance_details": "The cake has a clean, minimalist design with a small red heart at the bottom center of the text.",
"orientation": "flat, facing upwards"
},
{
"description": "An open, off-white, square-shaped takeout container made of a fibrous material, holding the cake.",
"location": "center-right",
"relationship": "The container holds and frames the cake.",
"relative_size": "large within frame",
"shape_and_color": "square, off-white",
"texture": "slightly rough, fibrous",
"appearance_details": "The container is open, with its lid folded back, revealing the cake inside.",
"orientation": "open, with the base angled slightly towards the bottom left"
},
{
"description": "A light brown, crinkled paper liner that cradles the cake within the takeout container.",
"location": "inside the takeout container, surrounding the cake",
"relationship": "The liner supports the cake within the container.",
"relative_size": "medium",
"shape_and_color": "irregular, light brown",
"texture": "crinkled paper",
"appearance_details": "The paper is slightly crumpled, conforming to the shape of the cake and container.",
"orientation": "wrapped around the cake"
},
{
"description": "A stack of various papers, including what appears to be newspaper or old documents, providing a textured surface beneath the container.",
"location": "bottom-left to top-left background",
"relationship": "The papers form part of the surface on which the container rests.",
"relative_size": "medium",
"shape_and_color": "rectangular, white and grey with black text",
"texture": "paper, some crinkled",
"appearance_details": "The papers show printed text and images, suggesting old documents or newsprint.",
"orientation": "stacked and spread out"
},
{
"description": "A wooden surface, possibly a table, visible in the background and beneath some of the papers.",
"location": "top-left and bottom-right background",
"relationship": "The wooden surface serves as the primary base for all other objects.",
"relative_size": "large",
"shape_and_color": "irregular, brown",
"texture": "wood grain",
"appearance_details": "The wood has visible grain patterns and a warm, natural tone.",
"orientation": "horizontal"
}
],
"background_setting": "The scene is set on a rustic wooden table, partially covered by a stack of old papers and a folded white and grey checkered cloth, creating a casual and slightly vintage backdrop for the cake.",
"lighting": {
"conditions": "bright, natural daylight",
"direction": "top-down, slightly from the left",
"shadows": "soft, subtle shadows cast by the container and cake, indicating gentle overhead lighting"
},
"aesthetics": {
"composition": "centered, with the cake as the focal point, using a slightly elevated perspective",
"color_scheme": "neutral tones of white, brown, and grey with a pop of red from the heart",
"mood_atmosphere": "simple, celebratory, and warm",
"preference_score": "very high",
"aesthetic_score": "very high"
},
"photographic_characteristics": {
"depth_of_field": "shallow, with the cake in sharp focus and the background gently blurred",
"focus": "sharp focus on subject",
"camera_angle": "high angle, looking down onto the cake",
"lens_focal_length": "standard lens (e.g., 35mm-50mm)"
},
"style_medium": "photograph",
"text_render": [
{
"text": "Great Work",
"location": "top of the cake, slightly left of center",
"size": "medium",
"color": "brown",
"font": "serif typeface",
"appearance_details": "Neatly piped, uppercase letters"
},
{
"text": "FIBO!",
"location": "bottom of the cake, below 'Great Work'",
"size": "large",
"color": "black",
"font": "script typeface",
"appearance_details": "Elegantly handwritten style, with an exclamation mark"
}
],
"context": "This is a concept for a celebratory photograph, possibly for a social media post or a personal gift, emphasizing achievement.",
"artistic_style": "realistic",
"edit_instruction": "Change the text on the cake to \"Great Work FIBO!\"."
}Use Case 6: Object Replacement
Instruction: "replace the garlic with slices of lemon, and chilli rings"
| Input Image | Output Image |
|---|---|
![]() | ![]() |
Click to view the Output Structured Instruction (JSON)
{
"short_description": "A close-up, high-angle shot of a light wooden cutting board featuring two metal spoons filled with a mixture of seeds and spices. To the left of the spoons are several bright yellow lemon slices and vibrant red chili rings, replacing the garlic. A delicate green dill sprig extends from the top-right, and a fresh mint leaf is visible in the bottom-right corner, adding a touch of freshness to the composition. The scene is brightly lit, highlighting the textures and colors of the ingredients.",
"objects": [
{
"description": "Two polished metal spoons, each filled with a textured mixture of seeds and spices, likely for cooking or seasoning. The mixture is a blend of light and dark brown, with visible flecks of various ingredients.",
"location": "center-right",
"relationship": "The spoons are positioned side-by-side, slightly angled, and are the central focus alongside the lemon and chili.",
"relative_size": "medium",
"shape_and_color": "Elongated oval spoons, metallic silver; contents are granular and multi-colored brown.",
"texture": "Smooth, reflective metal for the spoons; granular and slightly coarse for the spice mixture.",
"appearance_details": "Some of the spice mixture has spilled onto the wooden board around the spoons.",
"number_of_objects": 2,
"orientation": "Angled diagonally towards the top-right."
},
{
"description": "Several thin, bright yellow slices of lemon, freshly cut and arranged on the wooden board. They have a translucent quality, showing the pulp and seeds.",
"location": "top-left",
"relationship": "The lemon slices are placed to the left of the spoons, providing a fresh, contrasting element.",
"relative_size": "small",
"shape_and_color": "Circular slices, bright yellow with white pith.",
"texture": "Smooth, slightly moist, and glossy.",
"appearance_details": "Some slices show visible seeds and juicy pulp.",
"number_of_objects": 3,
"orientation": "Flat on the surface, slightly overlapping."
},
{
"description": "Several vibrant red chili rings, thinly sliced, adding a pop of color and a hint of spice to the arrangement.",
"location": "mid-left",
"relationship": "The chili rings are interspersed with the lemon slices, creating a visually appealing combination.",
"relative_size": "small",
"shape_and_color": "Circular rings, bright red.",
"texture": "Smooth and slightly glossy.",
"appearance_details": "The inner white membrane and tiny seeds are visible in some rings.",
"number_of_objects": 4,
"orientation": "Flat on the surface, scattered."
},
{
"description": "A delicate sprig of fresh dill, characterized by its feathery green leaves and small, intricate flower heads.",
"location": "top-right",
"relationship": "The dill sprig extends into the frame from the top-right, adding a natural, aromatic touch.",
"relative_size": "medium",
"shape_and_color": "Thin, green stem with feathery green foliage.",
"texture": "Fine, delicate, and slightly wispy.",
"appearance_details": "Small, star-like flower clusters are visible.",
"number_of_objects": 1,
"orientation": "Extending diagonally from top-right to center."
},
{
"description": "A fresh, vibrant green mint leaf, partially visible, adding a contrasting color and fresh element to the bottom of the composition.",
"location": "bottom-right",
"relationship": "The mint leaf is positioned at the bottom-right, framing the scene and adding a fresh accent.",
"relative_size": "small",
"shape_and_color": "Oval-shaped leaf, bright green.",
"texture": "Smooth with visible veins.",
"appearance_details": "Partially cropped, showing only a portion of the leaf.",
"number_of_objects": 1,
"orientation": "Flat on the surface."
}
],
"background_setting": "A light-colored wooden cutting board with a visible grain, providing a clean and natural surface for the ingredients. The edge of the board has a natural, rough bark-like texture on the right side. The background behind the board is a soft, out-of-focus white surface.",
"lighting": {
"conditions": "bright daylight",
"direction": "top-down",
"shadows": "soft, subtle shadows cast by the objects, indicating a gentle overhead light source."
},
"aesthetics": {
"composition": "diagonal composition, with elements arranged along a diagonal line from top-left to bottom-right, creating visual flow. Close-up shot.",
"color_scheme": "natural and fresh, with dominant greens, yellows, reds, and browns against a light wooden background.",
"mood_atmosphere": "fresh, natural, culinary, and inviting.",
"preference_score": "very high",
"aesthetic_score": "very high"
},
"photographic_characteristics": {
"depth_of_field": "shallow",
"focus": "sharp focus on the spoons, lemon, and chili, with a soft blur in the background.",
"camera_angle": "high angle",
"lens_focal_length": "standard lens (e.g., 35mm-50mm)"
},
"style_medium": "photograph",
"context": "This is a food photography shot, likely for a recipe blog, cookbook, or culinary magazine, showcasing fresh ingredients for a dish.",
"artistic_style": "realistic",
"edit_instruction": "Replace the garlic with slices of lemon and chili rings."
}Use Case 7: Color Palette Change
Instruction: "change color pallet of the image to: #014040, #02735E, #03A678, #F27405, #731702"
| Input Image | Output Image |
|---|---|
![]() | ![]() |
Click to view the Output Structured Instruction (JSON)
{
"short_description": "A flat lay composition featuring four silver number candles spelling out \"2020\" arranged horizontally across the center of the frame. The candles are surrounded by a scattering of small, irregularly shaped confetti in shades of dark teal, vibrant green, and deep orange, with some larger, more reflective pieces in a rich gold hue. The background is a solid, muted teal color, providing a striking contrast to the warm tones of the confetti and the metallic candles. The overall scene is festive and celebratory.",
"objects": [
{
"description": "Four metallic silver number candles, each with a small white wick at the top and a thin white plastic stick at the bottom for insertion. They are shaped to form the numbers '2', '0', '2', and '0'.",
"location": "center",
"relationship": "The candles are the primary subjects, arranged sequentially to form the year \"2020\" and are surrounded by confetti.",
"relative_size": "medium",
"shape_and_color": "Numeric shapes, silver.",
"texture": "Smooth, metallic, slightly reflective.",
"appearance_details": "Each candle has a small, unlit white wick and a white plastic base.",
"number_of_objects": 4,
"orientation": "Upright, aligned horizontally."
},
{
"description": "A scattering of small, irregularly shaped confetti pieces. The confetti consists of tiny, dark teal and deep orange dots, mixed with slightly larger, more reflective gold and vibrant green pieces. The distribution is denser around the candles and sparser towards the edges of the frame.",
"location": "spread across the entire frame, denser around the center",
"relationship": "The confetti is scattered around the number candles, enhancing the festive theme.",
"relative_size": "small",
"shape_and_color": "Irregular dots and flakes, dark teal, vibrant green, deep orange, and gold.",
"texture": "Varied; some pieces appear smooth and reflective (gold), others matte (teal, green, orange).",
"appearance_details": "The confetti creates a dynamic, textured surface on the background.",
"orientation": "Randomly scattered."
}
],
"background_setting": "A flat, solid surface in a muted teal color, serving as a clean and contrasting backdrop for the candles and confetti.",
"lighting": {
"conditions": "Soft, even ambient lighting, suggesting an indoor setting without direct harsh light.",
"direction": "Evenly lit from above, with no discernible strong directional light source.",
"shadows": "Minimal shadows, indicating soft, diffused lighting. Very slight, soft shadows are visible directly beneath the candles."
},
"aesthetics": {
"composition": "Centered composition, with the candles forming a horizontal line across the middle of the frame. The confetti is distributed to fill the remaining space, creating visual interest.",
"color_scheme": "A complementary color scheme dominated by muted teal, vibrant green, deep orange, and gold, with accents of silver from the candles.",
"mood_atmosphere": "Festive, celebratory, and clean.",
"preference_score": "very high",
"aesthetic_score": "very high"
},
"photographic_characteristics": {
"depth_of_field": "Shallow, with the candles in sharp focus and a slight softening of the confetti further from the lens.",
"focus": "Sharp focus on the number candles, with the confetti appearing slightly less defined.",
"camera_angle": "High angle, looking directly down onto the flat surface.",
"lens_focal_length": "Standard lens (e.g., 35mm-50mm)."
},
"style_medium": "photograph",
"context": "This is a concept for a celebratory image, possibly for a New Year's greeting, a birthday, or an anniversary, intended for social media or a greeting card.",
"artistic_style": "realistic",
"edit_instruction": "Change the color palette of the image to include #014040, #02735E, #03A678, #F27405, #731702 for the background and confetti, while keeping the silver candles."
}The source image to be edited. Publicly available URL or Base64-encoded. Accepted formats: JPEG, JPG, PNG, WEBP. Must contain exactly one item.
Text-based edit instruction (e.g., "make the sky blue", "add a cat"). This parameter serves as the text prompt.
Publicly available URL or Base64-encoded mask image (black and white). Black areas will be preserved, white areas will be edited. If omitted, the edit applies to the entire image. The input image and the input mask must be of the same size. This parameter is optional.
A string containing the structured edit instruction in JSON format. Use this instead of instruction for precise, programmatic control.
A text prompt specifying concepts, styles, or objects to exclude from the edited image. This parameter is optional.
Determines how closely the generated image should adhere to the content in the instruction or structured_instruction. This parameter is optional.
The version of the model to use. This parameter is optional. If omitted (Default): Your request will automatically use Bria's current default model version (currently FIBO-edit). If specified: Your request will be pinned to this exact version.
Number of diffusion steps. Uses model default if omitted. This parameter is optional.
Seed for deterministic generation. Uses a random seed if omitted. This parameter is optional.
Specifies the response mode. This parameter is optional.
- When
false(default), the request is processed asynchronously: the API immediately returns a status URL to track progress. - When
true, the request is processed synchronously: the API hold the connection open until the proccess is complete and then returns the final image URL in the response.
If true, returns a warning for potential IP content in the instruction. This parameter is optional.
If true, returns 422 on instruction moderation failure. This parameter is optional.
If true, returns 422 on images or mask moderation failure. This parameter is optional.
- https://engine.prod.bria-api.com/v2/image/edit
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://engine.prod.bria-api.com/v2/image/edit \
-H 'Content-Type: application/json' \
-H 'api_token: string' \
-d '{
"instruction": "change color pallet of the image to: #014040, #02735E, #03A678, #F27405, #731702",
"images": [
"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-cottonbro-3401900.jpg"
]
}'{ "result": { "image_url": "string", "seed": 0, "structured_instruction": "string" }, "request_id": "string", "warning": "string" }
Request
Description
Translates a user's text-based edit instruction and source image/mask into a detailed, machine-readable structured edit instruction in JSON format.
This endpoint uses the state-of-the-art Gemini 2.5 Flash VLM bridge to understand the edit context. It only returns the JSON string and does not generate an image.
Context-Aware Masking
When a mask is provided, the VLM analyzes the specific region of interest in relation to the rest of the image. It generates a structured_instruction tailored specifically for that area (e.g., ensuring lighting and perspective match the unmasked background), ensuring seamless integration when the edit is applied.
Why use this endpoint?
- Decoupling: Decouples the "intent translation" step from the "image editing" step, giving you maximum flexibility.
- Control & Auditability: Allows for a "human-in-the-loop" to inspect, programmatically edit, or version the JSON before generating an image (e.g., for a custom UI).
- Consistency & Automation: Generate one
structured_instructionand pass it to/v2/image/editmultiple times to create consistent, auditable variations. - Hybrid Deployment: Use Bria's state-of-the-art VLM bridge via API while self-hosting the open-source FIBO image model on your own private cloud.
The resulting structured_instruction can be used as input for the /v2/image/edit endpoint.
Input Combination Rules The request body must use exactly one of the following combinations:
- Global Instruction:
images+instruction - Masked Instruction:
images+mask+instruction
API Access
You can register and access the API Token through Bria's platform by clicking here.
Required. Text-based edit instruction (e.g., "make the sky blue", "add a cat"). This parameter serves as the text prompt.
Required. The source image to be edited. Publicly available URL or Base64-encoded. Must contain exactly one item.
Optional. Publicly available URL or Base64-encoded mask image (black and white). Black areas will be preserved, white areas will be edited. If omitted, the edit applies to the entire image.
Optional. Seed for deterministic generation. If omitted, a random seed is generated and used.
Specifies the response mode. Optional.
- When
false(default), the request is processed asynchronously: the API immediately returns a status URL to track progress. - When
true, the request is processed synchronously: the API hold the connection open until the proccess is complete and then returns the final result in the response.
If true, returns a warning for potential IP content in the instruction. Optional.
If true, returns 422 on instruction moderation failure. Optional.
- https://engine.prod.bria-api.com/structured_instruction/generate
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://engine.prod.bria-api.com/structured_instruction/generate \
-H 'Content-Type: application/json' \
-H 'api_token: string' \
-d '{
"images": [
"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/42082.jpg"
],
"instruction": "create a detailed realistic photo, with contemporary color scheme, and balanced exposure photo roughly based on this sketch"
}'{ "result": { "seed": 0, "structured_instruction": "string" }, "request_id": "string", "warning": "string" }
The source image to be handled by the API.
Supported input types:
- Base64-encoded string - URL pointing to an image file that is publicly accessible and available at the time of processing.
Accepted formats: JPEG, JPG, PNG, WEBP.
- https://engine.prod.bria-api.com/v2/image/edit/add_object_by_text
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://engine.prod.bria-api.com/v2/image/edit/add_object_by_text \
-H 'Content-Type: application/json' \
-H 'api_token: string' \
-d '{
"image": "string",
"instruction": "string"
}'{ "result": { "image_url": "string", "seed": 0, "structured_instruction": "string" }, "request_id": "string", "warning": "string" }
.png)















.png)