{
"openapi": "3.0.0",
"info": {
"title": "Image Editing API Reference",
"version": "",
"description": "Below you will find the technical specifications, request schemas, and response models for our endpoints. \n\nChoose an endpoint from the sidebar to view code samples and run test requests.\n"
},
"tags": [
{
"name": "v2 endpoints",
"description": "Endpoints that are part of BRIA API version 2.\n"
}
],
"externalDocs": {
"description": "Register and get API Access",
"url": "https://platform.bria.ai/organization-management/api-keys"
},
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
},
{
"url": "https://engine.prod.bria-api.com/v1"
}
],
"paths": {
"/image/edit": {
"post": {
"summary": "Image Edit by Text",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/fibo-image-edit)\n\n\n**Description**\n\nPowered 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.\n\nFIBO 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. \n\nThe 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.\n\n**Core Technology: The FIBO Architecture**\n\nThis endpoint utilizes the **FIBO** architecture, a unique two-step process ensuring precise and controllable edits:\n1. **Translation:** A VLM Bridge (powered by **Gemini 2.5 Flash**) converts your inputs into a detailed `structured_instruction` (JSON).\n2. **Generation:** The FIBO Edit model performs the final, deterministic edit on the input image, based on that JSON.\n\n**Advanced Control & Recreation**\n\n* To recreate a specific result: You must provide the exact source images, the mask (if used), the `structured_instruction` returned in the original response, and the `seed` used to create it.\n* For advanced, programmatic control, you can pass in your own `structured_instruction` (e.g., from the `/v2/structured_instruction/generate` endpoint) to bypass the internal VLM bridge.\n\n---\n\n**Input Combination Rules**\n\nThe request body must include `images` and one of the following combinations:\n\n* **Global Edit (natural language):** `images` + `instruction`\n* **Global Edit (JSON instruction):** `images` + `structured_instruction`\n* **Masked Edit (natural language):** `images` + `mask` + `instruction`\n* **Masked Edit (JSON instruction):** `images` + `mask` + `structured_instruction`\n\n---\n**API Access**\n\nYou can register and access the API Token through Bria's platform by clicking here.\n\n---\n**Examples**\n\n**Use Case 1: Lighting Change**\n\n**Instruction:** *\"change to golden hour\"*\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/magnifics_upscale-z3xYDU0K4AZzosFtvWvb-A_surreal_landscape_featuring_a_bright_yellow_train_standing_alone_on_a_reflecti+(1).png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/train_fc496bfa_seed096.png\") \n | \n
\n
\n\n\nClick to view the Output Structured Instruction (JSON)
\n\n```json\n{\n \"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.\",\n \"objects\": [\n {\n \"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.\",\n \"location\": \"center, extending from mid-left to far right\",\n \"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.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"Elongated, rectangular, bright yellow with some darker accents.\",\n \"texture\": \"Metallic, slightly weathered, with visible rivets and panels.\",\n \"appearance_details\": \"The train appears to be a diesel locomotive with several passenger cars, showing signs of use but maintaining its vibrant yellow color.\",\n \"orientation\": \"Horizontal, moving from left to right into the distance.\"\n },\n {\n \"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.\",\n \"location\": \"below the train, in the lower half of the frame\",\n \"relationship\": \"This object is the mirror image of the train, completing the symmetrical composition and emphasizing the reflective quality of the salt flat.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"Elongated, rectangular, bright yellow.\",\n \"texture\": \"Smooth, watery, with slight distortions from the water's surface.\",\n \"appearance_details\": \"The reflection includes all details of the train, including windows and structural elements.\",\n \"orientation\": \"Horizontal, mirroring the train above.\"\n },\n {\n \"description\": \"Numerous large, fluffy cumulus clouds scattered across the sky. They are bright white with soft, warm undertones from the golden hour light.\",\n \"location\": \"top half of the frame\",\n \"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.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"Irregular, billowy, white with golden hues.\",\n \"texture\": \"Soft, ethereal, cotton-like.\",\n \"appearance_details\": \"The clouds vary in size and density, creating a dynamic sky.\",\n \"orientation\": \"Scattered across the sky.\"\n },\n {\n \"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.\",\n \"location\": \"bottom half of the frame\",\n \"relationship\": \"These reflections mirror the clouds in the sky, enhancing the symmetrical composition and the illusion of the train floating on water.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"Irregular, billowy, white with golden hues.\",\n \"texture\": \"Smooth, watery, with slight ripples.\",\n \"appearance_details\": \"The reflections are almost perfect, indicating very still water.\",\n \"orientation\": \"Mirrored below the clouds in the sky.\"\n }\n ],\n \"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.\",\n \"lighting\": {\n \"conditions\": \"golden hour\",\n \"direction\": \"Side-lit, with warm, low-angle light coming from the side, likely from the left or right, casting soft, elongated highlights.\",\n \"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.\"\n },\n \"aesthetics\": {\n \"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.\",\n \"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.\",\n \"mood_atmosphere\": \"Serene, magical, and expansive, with a sense of wonder and tranquility enhanced by the soft, warm light.\",\n \"preference_score\": \"very high\",\n \"aesthetic_score\": \"very high\"\n },\n \"photographic_characteristics\": {\n \"depth_of_field\": \"Deep, with both the foreground train and the distant horizon appearing in sharp focus.\",\n \"focus\": \"Sharp focus on the train and its reflection, extending clearly into the background.\",\n \"camera_angle\": \"Eye-level, providing a direct and immersive view of the scene.\",\n \"lens_focal_length\": \"Standard lens (e.g., 35mm-50mm) to capture the expansive landscape while maintaining detail on the train.\"\n },\n \"style_medium\": \"photograph\",\n \"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.\",\n \"artistic_style\": \"realistic\",\n \"edit_instruction\": \"Change the lighting to golden hour.\"\n}\n```\n \n\n
\n\n**Use Case 2: Masked Text Addition**\n\n**Instruction:** *\"Write FIBO ROCKS on all balloons, use dark creative font, different font for each balloon\"*\n\n\n \n | Input Image | \n Input Mask | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-natalie-bond-320378-3371094.jpg\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-natalie-bond-320378-3371094_mask.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-natalie-bond-320378-3371094_bria_result.png\") \n | \n
\n
\n\n\nClick to view the Output Structured Instruction (JSON)
\n\n```json\n{\n \"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.\",\n \"objects\": [\n {\n \"description\": \"A large, metallic red balloon, reflecting light with a glossy sheen. It has \\\"FIBO ROCKS\\\" written on it in a dark, creative font.\",\n \"location\": \"top-right\",\n \"relationship\": \"Part of a cluster of balloons.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"Round, metallic red\",\n \"texture\": \"Smooth, glossy\",\n \"appearance_details\": \"Reflective surface showing subtle highlights.\",\n \"orientation\": \"Slightly angled upwards\"\n },\n {\n \"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.\",\n \"location\": \"center-right\",\n \"relationship\": \"Nestled among other balloons in the cluster.\",\n \"relative_size\": \"medium within frame\",\n \"shape_and_color\": \"Round, metallic purple\",\n \"texture\": \"Smooth, glossy\",\n \"appearance_details\": \"Shows reflections of the surrounding environment.\",\n \"orientation\": \"Upright\"\n },\n {\n \"description\": \"A metallic silver balloon, appearing bright and reflective against the background. It has \\\"FIBO ROCKS\\\" written on it in a dark, creative font.\",\n \"location\": \"mid-left\",\n \"relationship\": \"Prominently positioned within the balloon cluster.\",\n \"relative_size\": \"medium within frame\",\n \"shape_and_color\": \"Round, metallic silver\",\n \"texture\": \"Smooth, glossy\",\n \"appearance_details\": \"Highly reflective, catching ambient light.\",\n \"orientation\": \"Slightly angled downwards\"\n },\n {\n \"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.\",\n \"location\": \"center-right\",\n \"relationship\": \"The main subject of the image, forming a cohesive group.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"Various round shapes, metallic red, silver, and purple\",\n \"texture\": \"Smooth, glossy\",\n \"appearance_details\": \"The balloons are inflated and appear to be floating, with ribbons trailing downwards.\",\n \"number_of_objects\": 12,\n \"orientation\": \"Clustered together, generally upright\"\n },\n {\n \"description\": \"Thin, translucent white ribbons trailing downwards from the cluster of balloons.\",\n \"location\": \"bottom-center\",\n \"relationship\": \"Attached to the balloons, providing a sense of upward movement.\",\n \"relative_size\": \"small\",\n \"shape_and_color\": \"Thin, white, translucent\",\n \"texture\": \"Smooth, delicate\",\n \"appearance_details\": \"Flowing gently, some ribbons are intertwined.\",\n \"orientation\": \"Vertical, trailing downwards\"\n }\n ],\n \"background_setting\": \"A plain, light green wall with a smooth texture, providing a clean and uncluttered backdrop for the balloons.\",\n \"lighting\": {\n \"conditions\": \"Bright, soft ambient light\",\n \"direction\": \"Front-lit with some light from the right\",\n \"shadows\": \"Subtle, soft shadows cast by the balloons on the wall, indicating depth.\"\n },\n \"aesthetics\": {\n \"composition\": \"Centered, with the balloon cluster occupying the majority of the right side of the frame, creating a balanced yet dynamic visual.\",\n \"color_scheme\": \"Complementary colors of metallic reds, purples, and silvers against a soft green background, creating a festive and appealing palette.\",\n \"mood_atmosphere\": \"Joyful, celebratory, and festive.\",\n \"preference_score\": \"very high\",\n \"aesthetic_score\": \"very high\"\n },\n \"photographic_characteristics\": {\n \"depth_of_field\": \"Shallow, with the balloons in sharp focus and the background softly blurred.\",\n \"focus\": \"Sharp focus on the balloon cluster.\",\n \"camera_angle\": \"Eye-level\",\n \"lens_focal_length\": \"Standard lens (e.g., 35mm-50mm)\"\n },\n \"style_medium\": \"photograph\",\n \"text_render\": [\n {\n \"text\": \"FIBO ROCKS\",\n \"location\": \"on each balloon\",\n \"size\": \"medium\",\n \"color\": \"dark\",\n \"font\": \"creative, different for each balloon\",\n \"appearance_details\": \"Each instance of the text uses a unique, dark, creative font style.\"\n }\n ],\n \"context\": \"This is a celebratory photograph, possibly for an event or a brand promotion, featuring balloons with custom text.\",\n \"artistic_style\": \"realistic\",\n \"edit_instruction\": \"Add the text \\\"FIBO ROCKS\\\" to each balloon, using a dark, creative font, with a different font for each balloon.\"\n}\n```\n \n\n
\n\n**Use Case 3: Sketch to Realistic Photo**\n\n**Instruction:** *\"create a detailed realistic photo, with contemporary color scheme, and balanced exposure photo roughly based on this sketch\"*\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/42082.jpg\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/42082_bria_result.png\") \n | \n
\n
\n\n\nClick to view the Output Structured Instruction (JSON)
\n\n```json\n{\n \"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.\",\n \"objects\": [\n {\n \"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.\",\n \"location\": \"center\",\n \"relationship\": \"The main subject of the image, positioned centrally on the ground.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"Oval-shaped body, brown and white fur.\",\n \"texture\": \"Soft, dense fur.\",\n \"appearance_details\": \"Prominent whiskers, alert eyes, and a twitching nose.\",\n \"pose\": \"Sitting with its front paws tucked under its chest and hind legs slightly extended, body slightly turned to the left.\",\n \"expression\": \"Alert and curious.\",\n \"action\": \"Sitting still, observing its surroundings.\",\n \"orientation\": \"Facing left, slightly angled towards the viewer.\"\n }\n ],\n \"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.\",\n \"lighting\": {\n \"conditions\": \"Bright, natural daylight with balanced exposure.\",\n \"direction\": \"Evenly lit from above and slightly to the front.\",\n \"shadows\": \"Soft, subtle shadows beneath the rabbit, indicating natural light.\"\n },\n \"aesthetics\": {\n \"composition\": \"Centered composition with the rabbit as the main focal point, creating a portrait-like feel.\",\n \"color_scheme\": \"Contemporary natural color scheme with earthy tones and subtle greens/browns.\",\n \"mood_atmosphere\": \"Calm, natural, and serene.\",\n \"preference_score\": \"very high\",\n \"aesthetic_score\": \"very high\"\n },\n \"photographic_characteristics\": {\n \"depth_of_field\": \"Shallow depth of field, with the rabbit in sharp focus and the background softly blurred.\",\n \"focus\": \"Sharp focus on the rabbit's face and fur.\",\n \"camera_angle\": \"Eye-level, capturing the rabbit from its perspective.\",\n \"lens_focal_length\": \"Portrait lens (e.g., 50mm-85mm)\"\n },\n \"style_medium\": \"photograph\",\n \"context\": \"This is a realistic wildlife photograph, suitable for nature magazines, educational materials, or as a decorative print.\",\n \"artistic_style\": \"realistic\",\n \"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.\"\n}\n```\n \n\n
\n\n**Use Case 4: Object Modification (Add Print)**\n\n**Instruction:** *\"add a bold modern print to the shirt\"*\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/front-view-young-attractive-female-white-t-shirt-posing-showing-victory-sign-pink-wall-model-female-pose-color-photo-female-young.jpg\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/front-view-young-attractive-female-white-t-shirt-posing-showing-victory-sign-pink-wall-model-female-pose-color-photo-female-young_bria_result.png\") \n | \n
\n
\n\n\nClick to view the Output Structured Instruction (JSON)
\n\n```json\n{\n \"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.\",\n \"objects\": [\n {\n \"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.\",\n \"location\": \"center\",\n \"relationship\": \"main subject of the image\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"human form, fair skin, brown hair\",\n \"texture\": \"smooth skin, wavy hair\",\n \"appearance_details\": \"wearing red lipstick\",\n \"pose\": \"standing with arms bent at the elbows, hands raised to shoulder height, making peace signs with both hands\",\n \"expression\": \"calm, direct, slightly smiling\",\n \"clothing\": \"a white t-shirt with a bold modern print and dark pants\",\n \"action\": \"making peace signs\",\n \"gender\": \"female\",\n \"skin_tone_and_texture\": \"fair, smooth\",\n \"orientation\": \"facing forward\"\n },\n {\n \"description\": \"A white t-shirt with short sleeves and a crew neck, featuring a bold modern print on the front.\",\n \"location\": \"center, on the woman's torso\",\n \"relationship\": \"worn by the woman\",\n \"relative_size\": \"medium\",\n \"shape_and_color\": \"rectangular, white with a multi-colored print\",\n \"texture\": \"cotton fabric\",\n \"appearance_details\": \"The print is abstract and geometric, in contrasting colors.\",\n \"orientation\": \"worn on the body\"\n }\n ],\n \"background_setting\": \"A plain, solid pink wall with no discernible features or textures.\",\n \"lighting\": {\n \"conditions\": \"bright studio lighting\",\n \"direction\": \"front-lit\",\n \"shadows\": \"minimal shadows, soft and diffused behind the subject\"\n },\n \"aesthetics\": {\n \"composition\": \"centered, medium shot, portrait composition\",\n \"color_scheme\": \"monochromatic pink background with a contrasting white shirt and red lips\",\n \"mood_atmosphere\": \"casual, friendly, confident\",\n \"preference_score\": \"very high\",\n \"aesthetic_score\": \"very high\"\n },\n \"photographic_characteristics\": {\n \"depth_of_field\": \"shallow\",\n \"focus\": \"sharp focus on subject\",\n \"camera_angle\": \"eye-level\",\n \"lens_focal_length\": \"portrait lens (e.g., 50mm-85mm)\"\n },\n \"style_medium\": \"photograph\",\n \"context\": \"This is a studio portrait photograph, likely for a fashion or lifestyle campaign, emphasizing a casual and confident style.\",\n \"artistic_style\": \"realistic\",\n \"edit_instruction\": \"Add a bold modern print to the white t-shirt worn by the subject.\"\n}\n```\n \n\n
\n\n**Use Case 5: Text Modification (Replace Text)**\n\n**Instruction:** *\"replace the text to Great Work FIBO!\"*\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-matvalina-27310484.jpg\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-matvalina-27310484_bria_result.png\") \n | \n
\n
\n\n\nClick to view the Output Structured Instruction (JSON)
\n\n```json\n{\n \"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.\",\n \"objects\": [\n {\n \"description\": \"A small, round cake with smooth white frosting, decorated with a small red heart and text.\",\n \"location\": \"center\",\n \"relationship\": \"The cake is the main subject, sitting inside the takeout container.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"round, white\",\n \"texture\": \"smooth frosting\",\n \"appearance_details\": \"The cake has a clean, minimalist design with a small red heart at the bottom center of the text.\",\n \"orientation\": \"flat, facing upwards\"\n },\n {\n \"description\": \"An open, off-white, square-shaped takeout container made of a fibrous material, holding the cake.\",\n \"location\": \"center-right\",\n \"relationship\": \"The container holds and frames the cake.\",\n \"relative_size\": \"large within frame\",\n \"shape_and_color\": \"square, off-white\",\n \"texture\": \"slightly rough, fibrous\",\n \"appearance_details\": \"The container is open, with its lid folded back, revealing the cake inside.\",\n \"orientation\": \"open, with the base angled slightly towards the bottom left\"\n },\n {\n \"description\": \"A light brown, crinkled paper liner that cradles the cake within the takeout container.\",\n \"location\": \"inside the takeout container, surrounding the cake\",\n \"relationship\": \"The liner supports the cake within the container.\",\n \"relative_size\": \"medium\",\n \"shape_and_color\": \"irregular, light brown\",\n \"texture\": \"crinkled paper\",\n \"appearance_details\": \"The paper is slightly crumpled, conforming to the shape of the cake and container.\",\n \"orientation\": \"wrapped around the cake\"\n },\n {\n \"description\": \"A stack of various papers, including what appears to be newspaper or old documents, providing a textured surface beneath the container.\",\n \"location\": \"bottom-left to top-left background\",\n \"relationship\": \"The papers form part of the surface on which the container rests.\",\n \"relative_size\": \"medium\",\n \"shape_and_color\": \"rectangular, white and grey with black text\",\n \"texture\": \"paper, some crinkled\",\n \"appearance_details\": \"The papers show printed text and images, suggesting old documents or newsprint.\",\n \"orientation\": \"stacked and spread out\"\n },\n {\n \"description\": \"A wooden surface, possibly a table, visible in the background and beneath some of the papers.\",\n \"location\": \"top-left and bottom-right background\",\n \"relationship\": \"The wooden surface serves as the primary base for all other objects.\",\n \"relative_size\": \"large\",\n \"shape_and_color\": \"irregular, brown\",\n \"texture\": \"wood grain\",\n \"appearance_details\": \"The wood has visible grain patterns and a warm, natural tone.\",\n \"orientation\": \"horizontal\"\n }\n ],\n \"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.\",\n \"lighting\": {\n \"conditions\": \"bright, natural daylight\",\n \"direction\": \"top-down, slightly from the left\",\n \"shadows\": \"soft, subtle shadows cast by the container and cake, indicating gentle overhead lighting\"\n },\n \"aesthetics\": {\n \"composition\": \"centered, with the cake as the focal point, using a slightly elevated perspective\",\n \"color_scheme\": \"neutral tones of white, brown, and grey with a pop of red from the heart\",\n \"mood_atmosphere\": \"simple, celebratory, and warm\",\n \"preference_score\": \"very high\",\n \"aesthetic_score\": \"very high\"\n },\n \"photographic_characteristics\": {\n \"depth_of_field\": \"shallow, with the cake in sharp focus and the background gently blurred\",\n \"focus\": \"sharp focus on subject\",\n \"camera_angle\": \"high angle, looking down onto the cake\",\n \"lens_focal_length\": \"standard lens (e.g., 35mm-50mm)\"\n },\n \"style_medium\": \"photograph\",\n \"text_render\": [\n {\n \"text\": \"Great Work\",\n \"location\": \"top of the cake, slightly left of center\",\n \"size\": \"medium\",\n \"color\": \"brown\",\n \"font\": \"serif typeface\",\n \"appearance_details\": \"Neatly piped, uppercase letters\"\n },\n {\n \"text\": \"FIBO!\",\n \"location\": \"bottom of the cake, below 'Great Work'\",\n \"size\": \"large\",\n \"color\": \"black\",\n \"font\": \"script typeface\",\n \"appearance_details\": \"Elegantly handwritten style, with an exclamation mark\"\n }\n ],\n \"context\": \"This is a concept for a celebratory photograph, possibly for a social media post or a personal gift, emphasizing achievement.\",\n \"artistic_style\": \"realistic\",\n \"edit_instruction\": \"Change the text on the cake to \\\"Great Work FIBO!\\\".\"\n}\n```\n \n\n
\n\n**Use Case 6: Object Replacement**\n\n**Instruction:** *\"replace the garlic with slices of lemon, and chilli rings\"*\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-karola-g-4871148.jpg\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-karola-g-4871148_bria_result.png\") \n | \n
\n
\n\n\nClick to view the Output Structured Instruction (JSON)
\n\n```json\n{\n \"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.\",\n \"objects\": [\n {\n \"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.\",\n \"location\": \"center-right\",\n \"relationship\": \"The spoons are positioned side-by-side, slightly angled, and are the central focus alongside the lemon and chili.\",\n \"relative_size\": \"medium\",\n \"shape_and_color\": \"Elongated oval spoons, metallic silver; contents are granular and multi-colored brown.\",\n \"texture\": \"Smooth, reflective metal for the spoons; granular and slightly coarse for the spice mixture.\",\n \"appearance_details\": \"Some of the spice mixture has spilled onto the wooden board around the spoons.\",\n \"number_of_objects\": 2,\n \"orientation\": \"Angled diagonally towards the top-right.\"\n },\n {\n \"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.\",\n \"location\": \"top-left\",\n \"relationship\": \"The lemon slices are placed to the left of the spoons, providing a fresh, contrasting element.\",\n \"relative_size\": \"small\",\n \"shape_and_color\": \"Circular slices, bright yellow with white pith.\",\n \"texture\": \"Smooth, slightly moist, and glossy.\",\n \"appearance_details\": \"Some slices show visible seeds and juicy pulp.\",\n \"number_of_objects\": 3,\n \"orientation\": \"Flat on the surface, slightly overlapping.\"\n },\n {\n \"description\": \"Several vibrant red chili rings, thinly sliced, adding a pop of color and a hint of spice to the arrangement.\",\n \"location\": \"mid-left\",\n \"relationship\": \"The chili rings are interspersed with the lemon slices, creating a visually appealing combination.\",\n \"relative_size\": \"small\",\n \"shape_and_color\": \"Circular rings, bright red.\",\n \"texture\": \"Smooth and slightly glossy.\",\n \"appearance_details\": \"The inner white membrane and tiny seeds are visible in some rings.\",\n \"number_of_objects\": 4,\n \"orientation\": \"Flat on the surface, scattered.\"\n },\n {\n \"description\": \"A delicate sprig of fresh dill, characterized by its feathery green leaves and small, intricate flower heads.\",\n \"location\": \"top-right\",\n \"relationship\": \"The dill sprig extends into the frame from the top-right, adding a natural, aromatic touch.\",\n \"relative_size\": \"medium\",\n \"shape_and_color\": \"Thin, green stem with feathery green foliage.\",\n \"texture\": \"Fine, delicate, and slightly wispy.\",\n \"appearance_details\": \"Small, star-like flower clusters are visible.\",\n \"number_of_objects\": 1,\n \"orientation\": \"Extending diagonally from top-right to center.\"\n },\n {\n \"description\": \"A fresh, vibrant green mint leaf, partially visible, adding a contrasting color and fresh element to the bottom of the composition.\",\n \"location\": \"bottom-right\",\n \"relationship\": \"The mint leaf is positioned at the bottom-right, framing the scene and adding a fresh accent.\",\n \"relative_size\": \"small\",\n \"shape_and_color\": \"Oval-shaped leaf, bright green.\",\n \"texture\": \"Smooth with visible veins.\",\n \"appearance_details\": \"Partially cropped, showing only a portion of the leaf.\",\n \"number_of_objects\": 1,\n \"orientation\": \"Flat on the surface.\"\n }\n ],\n \"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.\",\n \"lighting\": {\n \"conditions\": \"bright daylight\",\n \"direction\": \"top-down\",\n \"shadows\": \"soft, subtle shadows cast by the objects, indicating a gentle overhead light source.\"\n },\n \"aesthetics\": {\n \"composition\": \"diagonal composition, with elements arranged along a diagonal line from top-left to bottom-right, creating visual flow. Close-up shot.\",\n \"color_scheme\": \"natural and fresh, with dominant greens, yellows, reds, and browns against a light wooden background.\",\n \"mood_atmosphere\": \"fresh, natural, culinary, and inviting.\",\n \"preference_score\": \"very high\",\n \"aesthetic_score\": \"very high\"\n },\n \"photographic_characteristics\": {\n \"depth_of_field\": \"shallow\",\n \"focus\": \"sharp focus on the spoons, lemon, and chili, with a soft blur in the background.\",\n \"camera_angle\": \"high angle\",\n \"lens_focal_length\": \"standard lens (e.g., 35mm-50mm)\"\n },\n \"style_medium\": \"photograph\",\n \"context\": \"This is a food photography shot, likely for a recipe blog, cookbook, or culinary magazine, showcasing fresh ingredients for a dish.\",\n \"artistic_style\": \"realistic\",\n \"edit_instruction\": \"Replace the garlic with slices of lemon and chili rings.\"\n}\n```\n \n\n
\n\n\n**Use Case 7: Color Palette Change**\n\n**Instruction:** *\"change color pallet of the image to: #014040, #02735E, #03A678, #F27405, #731702\"*\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-cottonbro-3401900.jpg\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-cottonbro-3401900_bria_result.png\") \n | \n
\n
\n\n\nClick to view the Output Structured Instruction (JSON)
\n\n```json\n{\n \"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.\",\n \"objects\": [\n {\n \"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'.\",\n \"location\": \"center\",\n \"relationship\": \"The candles are the primary subjects, arranged sequentially to form the year \\\"2020\\\" and are surrounded by confetti.\",\n \"relative_size\": \"medium\",\n \"shape_and_color\": \"Numeric shapes, silver.\",\n \"texture\": \"Smooth, metallic, slightly reflective.\",\n \"appearance_details\": \"Each candle has a small, unlit white wick and a white plastic base.\",\n \"number_of_objects\": 4,\n \"orientation\": \"Upright, aligned horizontally.\"\n },\n {\n \"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.\",\n \"location\": \"spread across the entire frame, denser around the center\",\n \"relationship\": \"The confetti is scattered around the number candles, enhancing the festive theme.\",\n \"relative_size\": \"small\",\n \"shape_and_color\": \"Irregular dots and flakes, dark teal, vibrant green, deep orange, and gold.\",\n \"texture\": \"Varied; some pieces appear smooth and reflective (gold), others matte (teal, green, orange).\",\n \"appearance_details\": \"The confetti creates a dynamic, textured surface on the background.\",\n \"orientation\": \"Randomly scattered.\"\n }\n ],\n \"background_setting\": \"A flat, solid surface in a muted teal color, serving as a clean and contrasting backdrop for the candles and confetti.\",\n \"lighting\": {\n \"conditions\": \"Soft, even ambient lighting, suggesting an indoor setting without direct harsh light.\",\n \"direction\": \"Evenly lit from above, with no discernible strong directional light source.\",\n \"shadows\": \"Minimal shadows, indicating soft, diffused lighting. Very slight, soft shadows are visible directly beneath the candles.\"\n },\n \"aesthetics\": {\n \"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.\",\n \"color_scheme\": \"A complementary color scheme dominated by muted teal, vibrant green, deep orange, and gold, with accents of silver from the candles.\",\n \"mood_atmosphere\": \"Festive, celebratory, and clean.\",\n \"preference_score\": \"very high\",\n \"aesthetic_score\": \"very high\"\n },\n \"photographic_characteristics\": {\n \"depth_of_field\": \"Shallow, with the candles in sharp focus and a slight softening of the confetti further from the lens.\",\n \"focus\": \"Sharp focus on the number candles, with the confetti appearing slightly less defined.\",\n \"camera_angle\": \"High angle, looking directly down onto the flat surface.\",\n \"lens_focal_length\": \"Standard lens (e.g., 35mm-50mm).\"\n },\n \"style_medium\": \"photograph\",\n \"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.\",\n \"artistic_style\": \"realistic\",\n \"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.\"\n}\n```\n \n\n
",
"operationId": "edit-image",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"images"
],
"properties": {
"images": {
"type": "array",
"items": {
"type": "string"
},
"description": "The source image to be edited. Publicly available URL or Base64-encoded. \nAccepted formats: JPEG, JPG, PNG, WEBP. \n**Must contain exactly one item.**\n"
},
"instruction": {
"type": "string",
"description": "Text-based edit instruction (e.g., \"make the sky blue\", \"add a cat\"). This parameter serves as the text prompt."
},
"mask": {
"type": "string",
"description": "Publicly available URL or Base64-encoded mask image (black and white). \nBlack areas will be preserved, white areas will be edited. If omitted, the edit applies to the entire image. \nThe input image and the input mask must be of the same size.\nThis parameter is optional.\n"
},
"structured_instruction": {
"type": "string",
"description": "A string containing the structured edit instruction in JSON format. Use this instead of `instruction` for precise, programmatic control."
},
"negative_prompt": {
"type": "string",
"description": "A text prompt specifying concepts, styles, or objects to exclude from the edited image. This parameter is optional."
},
"guidance_scale": {
"type": "integer",
"default": 5,
"minimum": 3,
"maximum": 5,
"description": "Determines how closely the generated image should adhere to the content in the instruction or structured_instruction. This parameter is optional."
},
"model_version": {
"type": "string",
"default": "FIBO-edit",
"enum": [
"FIBO-edit"
],
"description": "The version of the model to use. This parameter is optional.\nIf omitted (Default): Your request will automatically use Bria's current default model version (currently FIBO-edit).\nIf specified: Your request will be pinned to this exact version.\n"
},
"steps_num": {
"type": "integer",
"default": 30,
"minimum": 20,
"maximum": 50,
"description": "Number of diffusion steps. Uses model default if omitted. This parameter is optional."
},
"seed": {
"type": "integer",
"description": "Seed for deterministic generation. Uses a random seed if omitted. This parameter is optional."
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode. This parameter is optional.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"output_type": {
"type": "string",
"default": "png",
"enum": [
"png",
"jpeg"
],
"description": "The desired output format"
},
"ip_signal": {
"type": "boolean",
"default": false,
"description": "If true, returns a warning for potential IP content in the instruction. This parameter is optional."
},
"prompt_content_moderation": {
"type": "boolean",
"default": true,
"description": "If true, returns 422 on instruction moderation failure. This parameter is optional."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": true,
"description": "If true, returns 422 on images or mask moderation failure. This parameter is optional."
},
"visual_output_content_moderation": {
"type": "boolean",
"default": true,
"description": "If true, returns 422 on visual output moderation failure. This parameter is optional."
}
}
},
"examples": {
"text_instruction": {
"summary": "Global Edit by Text Instruction",
"value": {
"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"
]
}
},
"json_instruction": {
"summary": "Edit by Structured Instruction",
"value": {
"images": [
"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/42082.jpg"
],
"structured_instruction": "{\"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.\"}"
}
},
"masked_text_instruction": {
"summary": "Edit Masked Area",
"value": {
"instruction": "Write FIBO ROCKS on all balloons, use dark creative font, different font for each balloon",
"images": [
"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-natalie-bond-320378-3371094.jpg"
],
"mask": "https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-natalie-bond-320378-3371094_mask.png"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/structured_instruction/generate": {
"post": {
"summary": "Generate Structured Instruction",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2"
}
],
"description": "**Description**\n\nTranslates a user's text-based edit instruction and source image/mask into a detailed, machine-readable structured edit instruction in JSON format.\n\nThis 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.**\n\n**Context-Aware Masking**\n\nWhen 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.\n\n**Why use this endpoint?**\n- **Decoupling:** Decouples the \"intent translation\" step from the \"image editing\" step, giving you maximum flexibility.\n- **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).\n- **Consistency & Automation:** Generate one `structured_instruction` and pass it to `/v2/image/edit` multiple times to create consistent, auditable variations.\n- **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.\n\nThe resulting `structured_instruction` can be used as input for the `/v2/image/edit` endpoint.\n\n---\n\n**Input Combination Rules**\nThe request body must use exactly one of the following combinations:\n* **Global Instruction:** `images` + `instruction`\n* **Masked Instruction:** `images` + `mask` + `instruction`\n\n---\n\n**API Access**\n\nYou can register and access the API Token through Bria's platform by clicking here.",
"operationId": "generate-structured-instruction",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"images",
"instruction"
],
"properties": {
"instruction": {
"type": "string",
"description": "Required. Text-based edit instruction (e.g., \"make the sky blue\", \"add a cat\"). This parameter serves as the text prompt."
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"description": "Required. The source image to be edited. Publicly available URL or Base64-encoded. Must contain exactly one item."
},
"mask": {
"type": "string",
"description": "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."
},
"seed": {
"type": "integer",
"description": "Optional. Seed for deterministic generation. If omitted, a random seed is generated and used."
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode. Optional.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"ip_signal": {
"type": "boolean",
"default": false,
"description": "If true, returns a warning for potential IP content in the instruction. Optional."
},
"prompt_content_moderation": {
"type": "boolean",
"default": true,
"description": "If true, returns 422 on instruction moderation failure. Optional."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": true,
"description": "If true, returns 422 on images or mask moderation failure. Optional."
}
}
},
"examples": {
"generate_instruction": {
"summary": "Generate Instruction from Image & Text",
"value": {
"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"
}
},
"generate_masked_instruction": {
"summary": "Generate Instruction from Masked Image & Text",
"value": {
"images": [
"https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-natalie-bond-320378-3371094.jpg"
],
"mask": "https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo-edit/pexels-natalie-bond-320378-3371094_mask.png",
"instruction": "Write FIBO ROCKS on all balloons, use dark creative font, different font for each balloon"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncStructuredInstructionResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/add_object_by_text": {
"post": {
"summary": "Add Object by Text",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "add-object-by-text",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/add-object-by-text)\n\n**Description**\n\nInsert new objects into an image using natural language to describe the object and its position.\n\n**Example:** Instruction: \"Place a red vase with flowers on the table\"\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/an_empty_table_in_living_room.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+(1).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"instruction"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"instruction": {
"type": "string",
"description": "Natural language command."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/replace_object_by_text": {
"post": {
"summary": "Replace Object by Text",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "replace-object-by-text",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/replace-object-by-text)\n**Description**\n\nSwap an existing object in an image with a new one using a natural language command.\n\n**Example:** Instruction: \"Replace the red apple with a green pear\"\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/a_bowl_of_fruits__should_have_a_red_apple.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+(2).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"instruction"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"instruction": {
"type": "string",
"description": "Natural language command."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/erase_by_text": {
"post": {
"summary": "Erase Object by Text",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "erase-object-by-text",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/erase-object-by-text)\n**Description**\n\nRemove specific objects or unwanted elements from an image using natural language descriptions.\n\n**Example:** object_name: \"table\"\n\n\n\n \n | Input Image | \n Output Image | \n
\n \n | \n \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/hq-RlUr_t6xqVk8j7HU7G_2a39319420e6403f9d4e01c70beaa076.png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"object_name"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"object_name": {
"type": "string",
"description": "The name of the object to remove (e.g., \"the lamp\")."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/blend": {
"post": {
"summary": "Image Blending",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "blend-image",
"description": "**Description**\n\nMerge objects, apply textures, or rearrange items within an image using natural language.\n\n**Example:** Instruction: \"Place the art on the shirt, keep the art exactly the same\"\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/shirt.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+(6).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"instruction"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"instruction": {
"type": "string",
"description": "Free-text command describing the blend."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/reseason": {
"post": {
"summary": "Reseason Image",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "reseason",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/image-reseason)\n\n**Description**\n\nChange the season or weather atmosphere of an image.\n\n**Example:** Season: \"winter\"\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/create_a_realistic_image_of_a_green_field_in_the_spring__also_add_trees.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+(3).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"season"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"season": {
"type": "string",
"description": "Desired season (Enum or Custom Text).",
"enum": [
"spring",
"summer",
"autumn",
"winter"
]
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/rewrite_text": {
"post": {
"summary": "Rewrite",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "rewrite",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/rewrite)\n\n**Description**\n\nChange existing text within an image to new specific text.\n\n**Example:** new_text: \"FIBO Edit!\"\n\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/create_an_image_of_cake__with_text_on_it_saying___Hi_there__.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+(4).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"new_text"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"new_text": {
"type": "string",
"description": "The new string to appear in the image."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/sketch_to_colored_image": {
"post": {
"summary": "Sketch to Image",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "sketch-to-image",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/sketch-to-image)\n\n**Description**\n\nConvert a line drawing or sketch into a photorealistic colored image.\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/create_a_b_w_sketch_of_a_cat.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+(5).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/restore": {
"post": {
"summary": "Restore Old Images",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "restore",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/restore-old-images)\n\n**Description**\n\nRenew old photos by removing noise, scratches, and blur.\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/png+-+2026-01-13T134151.337.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+(7).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/colorize": {
"post": {
"summary": "Colorize",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "colorize",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/colorize)\n\n**Description**\n\nAdd vivid colors to B&W photos or convert color to B&W.\n**Example:** style: \"color_contemporary\"\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/png+-+2026-01-13T083840.113.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+-+2026-01-13T084527.903+(1).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"color"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"color": {
"type": "string",
"enum": [
"color_contemporary",
"color_vivid",
"black_and_white",
"sepia_vintage"
],
"description": "The restoration/color style ID."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. \nSee [Webhooks](https://docs.bria.ai/webhooks).\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/restyle": {
"post": {
"summary": "Restyle Image",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "restyle",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/restyle-image)\n\n**Description**\n\nTransform the artistic style of an image. Accepts either a preset Style ID or a custom description.\n\n**Supported Enum IDs:** \n- render_3d\n- cubism\n- oil_painting\n- anime\n- cartoon\n- coloring_book\n- retro_ad\n- pop_art_halftone\n- vector_art\n- story_board\n- art_nouveau\n- cross_etching\n- wood_cut\n\n**Example:** Style: \"oil_painting\"\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/png+-+2026-01-13T085722.786+(1).png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+-+2026-01-13T085839.789.png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"style"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"style": {
"type": "string",
"description": "Style Enum OR custom free text description.",
"enum": [
"render_3d",
"cubism",
"oil_painting",
"anime",
"cartoon",
"coloring_book",
"retro_ad",
"pop_art_halftone",
"vector_art",
"story_board",
"art_nouveau",
"cross_etching",
"wood_cut"
]
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/relight": {
"post": {
"summary": "Relight Image",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"operationId": "relight",
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/relight-image)\n\n**Description**\n\nModify the lighting setup (direction and atmosphere) of an image.\n\n**Example:**\n\n* Light Type: \"spotlight on subject, keep background settings\"\n\n\n \n | Input Image | \n Output Image | \n
\n \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+-+2026-01-13T095546.173.png\") \n | \n \n ![](\"https://bria-datasets.s3.us-east-1.amazonaws.com/Liza/bria_result+-+2026-01-13T100345.725+(1).png\") \n | \n
\n
",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"light_type"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** - **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"light_direction": {
"type": "string",
"description": "Direction (e.g., \"front\", \"side\", \"top-down\").",
"enum": [
"front",
"side",
"bottom",
"top-down"
]
},
"light_type": {
"type": "string",
"description": "Type (e.g., \"sunset\", \"studio\", \"neon\").",
"enum": [
"midday",
"blue hour light",
"low-angle sunlight",
"sunrise light",
"spotlight on subject, keep background settings",
"overcast light",
"soft overcast daylight lighting",
"cloud-filtered lighting",
"fog-diffused lighting",
"moonlight lighting",
"starlight lighting nighttime",
"soft bokeh lighting",
"harsh studio lighting keep background setting"
]
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncEditResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/erase": {
"post": {
"summary": "Eraser",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/eraser)\n\n**Description**\n\n\nThe *Eraser Route* enables the removal of elements or specific areas from a given image.\n\n\nYou can define the area to be removed by providing a mask that outlines the region to be erased. There are two main ways recommended to generate these masks:\n\n1. Masks can be created by allowing users to draw directly on the image with a brush, for example. To access the SDK that demonstrates how to implement a brush feature in your interface, please refer to the following link.\n\n2. By using the `/objects/mask_generator` route, which will generate all the possible masks for an image.\n\n\n**Output Characteristics**\n\n- The modified image is returned at the original resolution, preserving full visual quality without any automatic resizing or downscaling.\n- All areas outside the provided mask remain completely unchanged, ensuring pixel-perfect preservation of unedited regions.",
"operationId": "erase",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"mask"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"mask": {
"type": "string",
"description": "The binary mask image that defines the region where object generation will occur.\n\n**Mask Requirements**\n- The region to generate content must have a pixel value of **255 (white)**.\n- All other areas must have a pixel value of **0 (black)**.\n- The mask must have the **same aspect ratio** as the input image.\n\n**Supported Input Types**\n- **Base64-encoded string** – provide the mask data directly in the request.\n- **URL** – provide a publicly accessible URL to the mask image.\n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n\nEnsure that any provided URL is publicly accessible at the time of the request.\n"
},
"mask_type": {
"type": "string",
"default": "manual",
"enum": [
"manual",
"automatic"
],
"description": "Specifies how the input mask was created.\n\n- **`manual` (default)** – Use when the mask was generated by a user, for example, using a brush tool. \n- **`automatic`** – Use when the mask was generated by an algorithm, such as **SAM** or other automated segmentation methods.\n"
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n- When true: The output image maintains the original transparency of fully and partially transparent pixels.\n- When false: The output image is fully opaque.\n- Has no effect if the input image does not include an alpha channel.\n"
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
}
}
},
"examples": {
"send using url": {
"value": {
"image": "https://labs-assets.bria.ai/sandbox-example-inputs/eraser_image_example.jpg",
"mask": "https://labs-assets.bria.ai/sandbox-example-inputs/eraser_mask_example.jpg"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates.\n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/gen_fill": {
"post": {
"summary": "Generative Fill",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/generative-fill)\n\n**Description**\n\nThe *GenFill Route* enables the generation of objects by prompt in a specific region of an image.\n\nYou can define the area for object generation by using a mask that outlines the region where the object will be created. Our model is optimized to work seamlessly with blob-shaped masks.\n\nMasks can be created by allowing users to draw directly on the image with a brush, for example. To access the SDK that demonstrates how to implement a brush feature in your interface, please refer to the following link.\n\n**Output Characteristics**\n\n- The modified image is returned at the original resolution, preserving full visual quality without any automatic resizing or downscaling.\n- All areas outside the provided mask remain completely unchanged, ensuring pixel-perfect preservation of unedited regions.\n- If the input includes an alpha channel and `preserve_alpha=true`, the original transparency values (both full and partial) are maintained in the output.\n\n**Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n \n- **Prompt Moderation** – Validates the provided prompt and rejects requests containing unsafe or prohibited terms before processing starts.\n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.",
"operationId": "gen-fill",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true,
"description": "API token associated with the organization."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image",
"mask",
"prompt"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string**\n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"mask": {
"type": "string",
"description": "The binary mask image that defines the region where object generation will occur.\n\n**Mask Requirements**\n- The region to generate content must have a pixel value of **255 (white)**.\n- All other areas must have a pixel value of **0 (black)**.\n- The mask must have the **same aspect ratio** as the input image.\n\n**Supported Input Types**\n- **Base64-encoded string** – provide the mask data directly in the request.\n- **URL** – provide a publicly accessible URL to the mask image.\n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n\nEnsure that any provided URL is publicly accessible at the time of the request.\n"
},
"prompt": {
"type": "string",
"description": "The prompt you would like to use to generate the object within the masked region.\n\nPrompt Length Limits: ~90-110 words\n"
},
"refine_prompt": {
"type": "boolean",
"default": true,
"description": "Controls the automatic prompt refinement feature.\n- **`true` (default):** The provided prompt is automatically adjusted for optimal results. The adjusted prompt is then returned in the response payload as `refined_prompt`.\n- **`false`:** The original prompt is used as-is, without modification.\n"
},
"prompt_content_moderation": {
"type": "boolean",
"default": true,
"description": "When enabled (default: `true`), the input prompt is moderated before processing.\n\n**Expected Behavior**\n- The prompt is scanned for NSFW content and terms that violate Bria’s ethical guidelines. \n- If the prompt fails moderation, the request is blocked and the API responds with a 422 error.\n"
},
"negative_prompt": {
"type": "string",
"description": "The prompt you would like to use to specify details or attributes to avoid in the object generated within the masked region."
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n- When true: The output image maintains the original transparency of fully and partially transparent pixels.\n- When false: The output image is fully opaque.\n- Has no effect if the input image does not include an alpha channel.\n"
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"seed": {
"type": "integer",
"description": "You can choose whether you want your generated results to be random or predictable. You can recreate the same result in the future by using the seed value of a result from a response. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
}
}
},
"examples": {
"send using url": {
"value": {
"image": "https://labs-assets.bria.ai/sandbox-example-inputs/genfill_image_example.jpg",
"mask": "https://labs-assets.bria.ai/sandbox-example-inputs/genfill_mask_exmple.jpg",
"prompt": "A red delicious cherry"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request. This can be due to a malformed request, invalid JSON, or a missing required parameter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not Found. The requested resource could not be found. This can be due to:\n- The image or mask URL could not be found.\n content:\napplication/json:\n schema:\n $ref: '#/components/schemas/ErrorResponse'\n"
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity. This error is returned for validation failures, such as:\n- A parameter failing content moderation (e.g., `prompt_content_moderation: true` and an unsafe prompt).\n- Image or mask requirements not being met (e.g., different aspect ratios).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates.\n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/remove_background": {
"post": {
"summary": "Remove Background",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/remove-background)\n\n**Description**\n\n\nThe *Remove BG* Route can be used to remove the background of an image. This route leverages Bria's newest model, RMBG 2.0. For more details and to explore the model, check out the [Hugging Face demo](https://huggingface.co/spaces/briaai/BRIA-RMBG-2.0).\n\n\n**Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n \n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.\n\n\n**Constraints**\n\n\nThe Bria API currently supports only JPEG and PNG files in RGB, RGBA, or CMYK color modes. When the file is of a different type or color mode, the status code 415 will be returned.\n\n\n**Transparency and Customizable Binarization**\n\n\nThis endpoint returns an image where the background is removed, and the foreground remains with varying levels of transparency, allowing for smoother edges and more natural blending when placed over different backgrounds. Additionally, this unique output provides developers with the flexibility to binarize the result—transforming it into a binary mask—by setting a custom transparency threshold according to their specific use case. A binary mask is an image where pixels are either fully visible (foreground) or fully transparent (background), commonly used in visual generative AI and image processing pipelines. This capability enables seamless integration into workflows that require clear separation between subject and background, while still offering control over how strict this separation should be.\n\n\nBelow is a simple Python script to demonstrate how you can binarize the output image from the API. This allows you to set your own threshold to determine which areas are considered \"foreground\" and which are \"background.\"\n\n ```python\n from PIL import Image\n import numpy as np\n\n # Load the image (the output from the API)\n image = Image.open('output_image.png').convert('RGBA')\n\n # Convert to numpy array\n data = np.array(image)\n\n # Define your threshold (0-255, where 255 is fully opaque)\n threshold = 128\n\n # Apply the threshold: if alpha > threshold, set to fully opaque (255), otherwise transparent (0)\n data[:, :, 3] = np.where(data[:, :, 3] > threshold, 255, 0)\n\n # Create a new Image from the modified array\n binarized_image = Image.fromarray(data)\n\n # Save or display\n binarized_image.save('binarized_output.png')\n binarized_image.show()\n ```",
"operationId": "background-remove",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The image that you would like to remove the background from.\nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether partially transparent areas from the input image are retained in the output after background removal, if the input includes an alpha channel.\n- When true: Partially transparent pixels preserve their original alpha values in the output.\n- When false: All non-background areas in the output are rendered fully opaque.\n- Has no effect if the input image does not include an alpha channel.\n"
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
}
}
},
"examples": {
"send using url": {
"value": {
"image": "https://labs-assets.bria.ai/sandbox-example-inputs/remove_background_example.jpg"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai). \n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/replace_background": {
"post": {
"summary": "Replace Background",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/replace-background)\n\n\n**Description**\n\n\n\nThe *Replace BG Route* is used to replace the background of any image.\n\n\nWe offer 3 different background generation modes when generating by text: base, high contol and fast.\n\n - **Base** - clean, high quality backgrounds.\n - **High_control** - Stronger prompt adherence and scene context, finer control over layout and details - **we recommend using this mode.**\n - **Fast** - same core capabilities as base, optimal speed and quality balace.\n\n\nThis endpoint also allows replacing the background with a solid color of your choice. You can specify a hex color code (e.g., #FF5733) in the prompt to control the background color.\n\n\nHere are some examples:\n\n\n**original image**: \n\n\n![](\"https://i.ibb.co/n6JtktM/unnamed-13.jpg\")
\n\n\n**prompt**: in a parking lot\n \n\n\n**result**:\n\n\n![](\"https://i.ibb.co/1zvT5h4/unnamed-14.jpg\")
\n\n\n**Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n\n- **Prompt Moderation** – Validates the provided prompt and rejects requests containing unsafe or prohibited terms before processing starts.\n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.",
"operationId": "background-replace",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true,
"description": "API token associated with the organization."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The image that you would like to remove the background from.\nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"mode": {
"type": "string",
"enum": [
"base",
"high_control",
"fast"
],
"default": "high_control",
"description": "Selects the background-generation mode.\nRelevant only when describing the background by text.\n\n- **Base** - clean, high quality backgrounds.\n- **High_control** - stronger prompt adherence and scene context, finer control over layout and details.\n- **Fast** - same core capabilities as base, optimal speed and quality balace.\n"
},
"ref_images": {
"type": "string",
"description": "One or more reference images to guide the background generation. \n\n**Supported Input Types** \n- **Base64-encoded string** – provide the image data directly in the request. \n- **URL** – provide a publicly accessible URL to the image. \n- **List** – multiple images can be supplied as a list of Base64 strings or URLs. \n\n**Usage Constraints** \n- You must provide **either** `ref_images` **or** `prompt`, but not both. \n- Accepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**. \n\nAll provided images must be accessible and in a supported format at the time of processing.\n"
},
"enhance_ref_images": {
"type": "boolean",
"default": true,
"description": "When set to true, additional logic processes the included reference image to make adjustments for optimal results."
},
"prompt": {
"type": "string",
"description": "Text description of the new scene or background for the provided image. Either ref_images or prompt has to be provided but not both. Bria currently supports prompts in English only, excluding special characters.\n\n**Prompt length guidelines per mode:**\n - base / fast: ~50–60 words\n - high_control: ~90–110 words\n"
},
"refine_prompt": {
"type": "boolean",
"default": true,
"description": "When true, an additional logic takes the prompt that was included and adjusts it to achieve optimal results."
},
"prompt_content_moderation": {
"type": "boolean",
"default": true,
"description": "When enabled (default: `true`), the input prompt is moderated before processing.\n\n**Expected Behavior**\n- The prompt is scanned for NSFW content and terms that violate Bria’s ethical guidelines. \n- If the prompt fails moderation, the request is blocked and the API responds with a 422 error.\n\n**Prompt length guidelines per mode:**\n- base / fast: ~50–60 words\n- high_control: ~90–110 words\n"
},
"negative_prompt": {
"type": "string",
"description": "Elements or features that should be excluded from the generated scene. This parameter is optional and is available only when fast=false. Bria currently supports descriptions in English only."
},
"original_quality": {
"type": "boolean",
"default": false,
"description": "When true, the output image retains the original input image's size; otherwise, the image is scaled to 1 megapixel (1MP) while preserving its aspect ratio."
},
"force_background_detection": {
"type": "boolean",
"default": false,
"description": "When `true`, forces background detection and removal, even if the original image already contains an alpha channel. Useful for refining existing foreground/background separation or ignoring unnecessary alpha channels."
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error. \n"
},
"seed": {
"type": "integer",
"description": "You can choose whether you want your generated results to be random or predictable. You can recreate the same result in the future by using the seed value of a result from the response. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional."
}
}
},
"examples": {
"send with url": {
"value": {
"image": "https://labs-assets.bria.ai/sandbox-example-inputs/replace_bg_example_image.jpg",
"prompt": "Resting on a light pink circular platform placed on a bright red floor in a photo studio. The background is a vivid red wall with subtle vertical lines. Surrounding the platform are numerous 3D red poppy flowers in varying sizes. Sliced and whole grapefruits are arranged around the base of the platform, adding fresh color contrast. Lit evenly by soft studio lighting. Shot from a front angle.",
"mode": "high_control"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessWithSeedAndRefinedPrompt"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/erase_foreground": {
"post": {
"summary": "Erase Foreground",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/erase-foreground)\n\n\n\n**Description**\n\n\n\nThe **Erase Foreground** endpoint removes the primary subject (foreground) from the input image and intelligently generates the background to fill the erased area. \n\n**Output Characteristics** \n- Returns the edited image at its original resolution, ensuring full visual fidelity without any automatic resizing or downscaling. \n- Only the foreground is removed; all other areas remain unaltered, preserving pixel-perfect accuracy in untouched regions. \n- When `preserve_alpha=true` and the input image includes an alpha channel, the output maintains original transparency values (both full and partial). \n\n\n\n\n **Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n\n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.",
"operationId": "erase-foreground",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The image that you would like to remove the background from.\nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n- When true: The output image maintains the original transparency of fully and partially transparent pixels.\n- When false: The output image is fully opaque.\n- Has no effect if the input image does not include an alpha channel.\n"
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error. \n"
}
},
"example": {
"image": "example"
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/blur_background": {
"post": {
"summary": "Blur Background",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "\n\n**Description**\n\n\n\nThe *background/blur Route* is used to create a blur effect on the background of an image. \n\n**Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n\n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.",
"operationId": "blur-bg",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"scale": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 5,
"description": "A scale for determining how blurry the background of the image should be. The options are 1, 2, 3, 4, 5. This parameter is optional."
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n- When true: The output image maintains the original transparency of fully and partially transparent pixels.\n- When false: The output image is fully opaque.\n- Has no effect if the input image does not include an alpha channel.\n"
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
}
}
},
"examples": {
"using_url": {
"summary": "Remove background using URL",
"value": {
"image": "example"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/expand": {
"post": {
"summary": "Expand Image",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/exapnd-image)\n\n\n**Description**\n\n\n\nThe *Image Expension Route* can be used to expand an image, by utilizing generative AI.\n\n\nYou can decide on the image size of the final result as well as the position and size of the original image compared to the final result.\n\n\nAlternatively, you can define a desired aspect_ratio, and the service will automatically place the input image in the center and expand the canvas to match that ratio.\n\n\nIn this way, you can create unique variations of your original image instead of cropping it into different aspect ratios and losing important details.\n\n\nIf aspect_ratio is not provided, both original_image_size and original_image_location must be specified.\n\n\n\n**Optimal input range**\n\n\n***Input Image Area:*** Ensure that the ratio of the input image foreground or main subject to the canvas area is greater than 15% to achieve optimal results.\n\n\n***Canvas Size:*** The canvas size should be up to an area of 5000x5000 pixels.\n\n\n***Prompt:*** This parameter is optional. If not provided or left empty, the service will automatically generate a prompt based on the input image.\n\n\n**Alpha Channel Handling**\n\n\n- If the input image includes an alpha channel and `preserve_alpha=true`, newly generated pixels inherit the alpha values of the nearest original pixels along the same row or column, ensuring smooth transparency transitions.\n\n\n- If the input image contains fully transparent pixels along any edge (top, bottom, left, or right), the request is rejected with a 422 error. Expansion is not supported in such cases to avoid undefined transparency behavior.\n\n\n\nHere are some examples:\n\n\n**original image (Generated by Bria)**: \n\n\n![](\"https://bria-image-repository.s3.amazonaws.com/images/caeaa19524d69ad6.jpg\")
\n\n\n**results**:\n\n\n![](\"https://bria-image-repository.s3.amazonaws.com/images/d4d49719b5a54e49.jpg\")
![](\"https://bria-image-repository.s3.amazonaws.com/images/cbf61f2b859662c0.jpg\")
\n![](\"https://bria-image-repository.s3.amazonaws.com/images/aa9b3036e5c6d43a.jpg\")
\n\n\n **original image (Stock Image)**: \n\n\n![](\"https://bria-image-repository.s3.amazonaws.com/images/c64220ebda5ce787.jpg\")
\n\n\n**results**:\n\n\n![](\"https://bria-image-repository.s3.amazonaws.com/images/d35530e95ab7c509.jpg\")
![](\"https://bria-image-repository.s3.amazonaws.com/images/84752d2fca8a6ae3.jpg\")
\n![](\"https://bria-image-repository.s3.amazonaws.com/images/904f62b0dce4fb8c.jpg\")
\n\n\n\n **Content Moderation**\n\n This endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n\n - **Prompt Moderation** – Validates the provided prompt and rejects requests containing unsafe or prohibited terms before processing starts.\n - **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n - **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.",
"operationId": "image-expansion",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"aspect_ratio": {
"type": [
"string",
"number"
],
"description": "Automatically expands or crops the input image to the specified aspect ratio.\n\nEither `aspect_ratio` or the combination of `original_image_size` and `original_image_location` must be provided.\n\nWhen provided, `canvas_size`, `original_image_size`, and `original_image_location` are ignored.\n\nCenters the input image, expanding edges to reach the target ratio.\n\nAccepts either:\n- A predefined string: \"1:1\", \"2:3\", \"3:2\", \"3:4\", \"4:3\", \"4:5\", \"5:4\", \"9:16\", \"16:9\"\n- A custom float between 0.5 and 3.0\n\nIf the target ratio equals the input image’s current ratio, no changes are made.\n\nIf the computed final dimensions exceed 5000×5000 px in total area, the input image is automatically resized so the area stays within limits.\n"
},
"canvas_size": {
"type": "array",
"items": {
"type": "integer"
},
"default": [
1000,
1000
],
"description": "Desired output canvas dimensions (width, height). Defaults to [1000, 1000] if not provided.\nIgnored when `aspect_ratio` is used.\nMaximum allowed area is 25M pixels (i.e., width × height ≤ 5,000 × 5,000). Exceeding this returns a 400 error.\n"
},
"original_image_size": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The desired size of the original image inside the final canvas, as `[width, height]` in pixels.\nEnsure that the visible part of the input image (foreground or main subject) occupies more than 15% of the total canvas area for optimal results.\nThis field is required when `aspect_ratio` is not provided.\nMust be used together with `original_image_location`.\n"
},
"original_image_location": {
"type": "array",
"items": {
"type": "integer"
},
"description": "The position of the top-left corner of the original image within the final canvas, provided as `[x, y]` in pixels.\nThis defines where the input image will be placed before expansion occurs.\nThe values can be outside the canvas bounds—if so, the image will be cropped accordingly.\nRequired when `aspect_ratio` is not provided.\nMust be used together with `original_image_size`.\n"
},
"prompt": {
"type": "string",
"description": "Optional text prompt to guide the image expansion.\nIf not provided or left empty, a prompt will be automatically generated as part of the service based on the input image.\nCurrently, Bria supports prompts in English only and does not support special characters.\n"
},
"prompt_content_moderation": {
"type": "boolean",
"default": true,
"description": "When enabled (default: `true`), the input prompt is moderated before processing.\n\n**Expected Behavior**\n- The prompt is scanned for NSFW content and terms that violate Bria’s ethical guidelines. \n- If the prompt fails moderation, the request is blocked and the API responds with a 422 error.\n"
},
"seed": {
"type": "integer",
"description": "You can choose whether you want your generated expension to be random or predictable. You can recreate the same result in the future by using the seed value of a result from the response. You can exclude this parameter if you are not interested in recreating your results. This parameter is optional."
},
"negative_prompt": {
"type": "string",
"description": "This parameter is optional. Currently, Bria supports prompts in English only and does not support special characters."
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n- When true: The output image maintains the original transparency of fully and partially transparent pixels.\n- When false: The output image is fully opaque.\n- Has no effect if the input image does not include an alpha channel.\n"
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
}
}
},
"examples": {
"Aspect Ratio": {
"value": {
"image": "https://labs-assets.bria.ai/sandbox-example-inputs/expand_image_example.jpg",
"aspect_ratio": "2:3"
}
},
"Precise location, Canvas size in pixels": {
"value": {
"image": "https://labs-assets.bria.ai/sandbox-example-inputs/expand_image_example.jpg",
"canvas_size": [
1024,
1024
],
"original_image_size": [
512,
512
],
"original_image_location": [
256,
256
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessWithSeedAndPrompt"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/enhance": {
"post": {
"summary": "Enhance Image",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/enhance-image)\n\n**Description**\n\nRegenerate an image with sharper textures and richer details while doubling resolution, up to 10 megapixels output.\n\nNote: this endpoint only supports async response mode - the API immediately returns a status URL to track progress.\n\n**Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n\n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.\n\n\nNote: use [Increase Resolution](https://docs.bria.ai/image-editing-v2/v2-endpoints/increase-resolution) route to increase resolution without impacting details.",
"operationId": "enhance",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"seed": {
"type": "integer",
"description": "Optional seed for controlling generation randomness. You can recreate the same result in the future by using the same seed with the same input parameters.\n"
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n"
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
}
}
},
"example": {
"image": "https://labs-assets.bria.ai/sandbox-example-inputs/enhance_image_example.jpg"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessWithSeed"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/increase_resolution": {
"post": {
"summary": "Increase Resolution",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "[**Try out this capability in Bria's sandbox**](https://platform.bria.ai/image-editing/increase-resolution)\n\n\n**Description**\n\n\n\nThe *Increase Resolution Route* is used to upscale the resolution of any image.\n\n\n**Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n\n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.\n\n**Constraints**\n\n\nThe Bria API currently supports only JPEG and PNG files in RGB, RGBA, or CMYK color modes. When the file is of a different type or color mode, the status code 415 will be returned. \n\n\nIt's possible to increase the resolution of an image up to a total area of 8192x8192 pixels.\n\n\nUnlike the [Enhance Image](https://docs.bria.ai/image-editing/endpoints/enhance-image) route, this endpoint does not add new details — it increases resolution using a dedicated upscaling method that preserves the original image content without regeneration.",
"operationId": "increase-resolution",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n- When true: The output image maintains the original transparency of fully and partially transparent pixels.\n- When false: The output image is fully opaque.\n- Has no effect if the input image does not include an alpha channel.\n"
},
"desired_increase": {
"type": "integer",
"default": 2,
"description": "The resolution multiplier. The possible value are 2,4. It's possible to increase the resolution of an image up to a total area of 8,192x8,192 pixels."
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
}
}
},
"example": {
"image": "example"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/crop_foreground": {
"post": {
"summary": "Crop out foreground",
"tags": [
"v2 endpoints"
],
"servers": [
{
"url": "https://engine.prod.bria-api.com/v2/image/edit"
}
],
"description": "\n\n**Description**\n\n\n\nThe Crop Route is used to remove the background from an image and crop tightly around the foreground or remaining region of interest. It supports both images with and without a background.\n\n**Content Moderation**\n\nThis endpoint includes granular content moderation controls to ensure safe usage across all stages of processing:\n\n- **Input Image Moderation** – Scans the uploaded image and stops processing if inappropriate or restricted content is detected.\n- **Output Image Moderation** – Evaluates the generated image and blocks the response if it violates safety guidelines.",
"operationId": "crop",
"parameters": [
{
"in": "header",
"name": "api_token",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"image"
],
"properties": {
"image": {
"type": "string",
"description": "The source image to be handled by the API. \nSupported input types: \n- **Base64-encoded string** \n- **URL** pointing to an image file that is publicly accessible and available at the time of processing. \n\nAccepted formats: **JPEG**, **JPG**, **PNG**, **WEBP**.\n"
},
"padding": {
"type": "integer",
"description": "Cropping the object with padding around it. Currently, padding is applied to all four borders of the remaining region. This parameter is optional.",
"default": 0
},
"force_background_detection": {
"type": "boolean",
"default": false,
"description": "When `true`, forces background detection and removal, even if the original image already contains an alpha channel. Useful for refining existing foreground/background separation or ignoring unnecessary alpha channels."
},
"preserve_alpha": {
"type": "boolean",
"default": true,
"description": "Controls whether the alpha channel values from the input image are retained in the output, if the input includes an alpha channel.\n- When true: The output image maintains the original transparency of fully and partially transparent pixels.\n- When false: The transparency values from the input are not preserved, but the output may still include an alpha channel (e.g., around the cropped area).\n- Has no effect if the input image does not include an alpha channel.\n"
},
"sync": {
"type": "boolean",
"default": false,
"description": "Specifies the response mode.\n - When `false` (default), the request is processed asynchronously: the API immediately returns a status URL to track progress.\n - 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.\n"
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional URL for receiving the result via webhook when the async job completes. See [Webhooks](https://docs.bria.ai/webhooks)."
},
"visual_input_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to input visual.\n\nExpected behavior:\n- Processing stops if the image fails moderation.\n- Returns a 422 error with details about which parameter failed.\n"
},
"visual_output_content_moderation": {
"type": "boolean",
"default": false,
"description": "When enabled, applies content moderation to result visual.\n\nExpected behavior:\n- If the modified image fails moderation, returns a 422 error.\n"
}
}
},
"example": {
"image": "example"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation (Synchronous Success)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSuccessResponse"
}
}
}
},
"202": {
"description": "Accepted (Asynchronous). You can track the progress and retrieve the final result using the Status Service. For more details, refer to the [Status Service](https://docs.bria.ai/status) section.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncInitialResponse"
}
}
}
},
"400": {
"description": "Bad request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Not found. Image could not be found at the provided URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"415": {
"description": "Unsupported media type.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"429": {
"description": "Request limit exceeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"460": {
"description": "Failed to download image.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"5XX": {
"description": "**Internal Server Error** – A critical failure occurred in Bria's infrastructure, preventing the Status Service from responding. \n- This response indicates a service outage or unexpected runtime failure. \n- Check [Bria's Status Page](https://status.bria.ai) for real-time updates. \n- Contact [Support](mailto:support@bria.ai).\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ErrorObject": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"example": 123
},
"message": {
"type": "string"
},
"details": {
"type": "string"
}
},
"required": [
"code",
"message",
"details"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorObject"
},
"request_id": {
"type": "string"
}
},
"required": [
"error",
"request_id"
]
},
"SyncSuccessResponse": {
"type": "object",
"properties": {
"result": {
"type": "object",
"properties": {
"image_url": {
"type": "string"
}
},
"required": [
"image_url"
]
},
"request_id": {
"type": "string"
}
},
"required": [
"result",
"request_id"
]
},
"SyncEditResponse": {
"type": "object",
"properties": {
"result": {
"type": "object",
"properties": {
"image_url": {
"type": "string"
},
"seed": {
"type": "integer"
},
"structured_instruction": {
"type": "string"
}
},
"required": [
"image_url",
"seed",
"structured_instruction"
]
},
"request_id": {
"type": "string"
},
"warning": {
"type": "string",
"description": "Returned only when ip_signal = true and the instruction field included IP content."
}
},
"required": [
"result",
"request_id"
]
},
"SyncStructuredInstructionResponse": {
"type": "object",
"properties": {
"result": {
"type": "object",
"properties": {
"seed": {
"type": "integer"
},
"structured_instruction": {
"type": "string"
}
},
"required": [
"seed",
"structured_instruction"
]
},
"request_id": {
"type": "string"
},
"warning": {
"type": "string",
"description": "Returned only when ip_signal = true and the instruction field included IP content."
}
},
"required": [
"result",
"request_id"
]
},
"AsyncInitialResponse": {
"type": "object",
"properties": {
"request_id": {
"type": "string"
},
"status_url": {
"type": "string"
}
},
"required": [
"request_id",
"status_url"
]
},
"SyncSuccessWithSeed": {
"allOf": [
{
"$ref": "#/components/schemas/SyncSuccessResponse"
},
{
"type": "object",
"properties": {
"result": {
"allOf": [
{
"$ref": "#/components/schemas/SyncSuccessResponse/properties/result"
},
{
"type": "object",
"properties": {
"seed": {
"type": "string"
}
}
}
]
}
}
}
]
},
"SyncSuccessWithSeedAndRefinedPrompt": {
"allOf": [
{
"$ref": "#/components/schemas/SyncSuccessResponse"
},
{
"type": "object",
"properties": {
"result": {
"allOf": [
{
"$ref": "#/components/schemas/SyncSuccessResponse/properties/result"
},
{
"type": "object",
"properties": {
"seed": {
"type": "integer"
},
"refined_prompt": {
"type": "string",
"description": "Refined version of the input prompt.\n**Returned only when:**\n- The request included a `prompt` parameter.\n- The request did NOT include a `reference_image`.\n"
}
}
}
]
}
}
}
]
},
"SyncSuccessWithSeedAndPrompt": {
"allOf": [
{
"$ref": "#/components/schemas/SyncSuccessResponse"
},
{
"type": "object",
"properties": {
"result": {
"allOf": [
{
"$ref": "#/components/schemas/SyncSuccessResponse/properties/result"
},
{
"type": "object",
"properties": {
"seed": {
"type": "integer"
},
"prompt": {
"type": "string",
"description": "Original prompt sent by the user."
}
}
}
]
}
}
}
]
},
"StatusSuccessResponse": {
"type": "object",
"properties": {
"result": {
"type": "object",
"properties": {
"image_url": {
"type": "string"
}
},
"required": [
"image_url"
]
},
"status": {
"type": "string",
"enum": [
"COMPLETED"
]
},
"request_id": {
"type": "string"
}
},
"required": [
"result",
"status",
"request_id"
]
},
"StatusErrorResponse": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"FAILED"
]
}
},
"required": [
"status"
]
}
]
},
"parameters": {
"ApiTokenHeader": {
"name": "api_token",
"in": "header",
"description": "API Token required for authentication",
"required": true,
"schema": {
"type": "string"
}
}
}
}
}
}