{ "openapi": "3.0.0", "info": { "title": "Overview", "version": "", "description": "The **Status Service** provides progress tracking for asynchronous requests. This functionality is supported exclusively for **V2 endpoints**.\n\n### Workflow\n1. Submit a request with `sync=false` (default behavior).\n2. The API returns a `status_url` and a `request_id`.\n3. Continuously poll the `status_url` (or use the `/status/{request_id}` endpoint) until the `status` field indicates a terminal state.\n\n### Status Values\n- **`IN_PROGRESS`** – The request has been accepted and is currently being processed. \n Continue polling until the status changes to either `COMPLETED` or an error state.\n\n- **`COMPLETED`** – The request was successfully processed. \n The response includes either `result.image_url` for images or `result.video_url` for videos, , or structured_prompt (for structured prompt generation).\" \n For some endpoints, additional optional fields (seed, prompt, refined_prompt, structured_prompt) may be included.\n- **`ERROR`** – A processing error occurred in the pipeline. \n The response includes an `error` object with details about the failure. Polling should be stopped.\n\n- **`UNKNOWN`** – An unexpected internal error occurred (equivalent to an HTTP `500` in asynchronous workflows). \n This status should not occur under normal circumstances. If it does, contact [Support](mailto:support@bria.ai). and provide the `request_id`.\n" }, "tags": [ { "name": "Endpoints" } ], "externalDocs": { "description": "Register and get API Access", "url": "https://platform.bria.ai/console/account/api-keys" }, "servers": [ { "url": "https://engine.prod.bria-api.com/v2" } ], "paths": { "/status/{request_id}": { "get": { "tags": [ "Endpoints" ], "servers": [ { "url": "https://engine.prod.bria-api.com/v2" } ], "summary": "Get Request Status", "description": "Retrieves the current status of an asynchronous request.\n\n **Behavior**\n- Under normal operation, this endpoint returns **`200 OK`**, regardless of whether the request is in progress, completed, or has failed at the job level. \n- The `status` field in the response (`IN_PROGRESS`, `COMPLETED`, `ERROR`, `UNKNOWN`) indicates the state of the job. \n- When the job fails (status=`ERROR`), details of the failure are provided in the `error` object, but the HTTP status remains `200`.\n- When `status=COMPLETED`, `result` includes `image_url` for images or `video_url` for videos, or structured_prompt based on the original endpoint.\n\n**Other Possible Responses**\n- **`404 NOT_FOUND`** – Returned when the specified `request_id` does not exist or has expired. \n- **`5XX`** – Returned when the Status Service itself experiences an internal error.\n For real-time updates, check [Bria's Status Page](https://status.bria.ai). You can also contact our [Support](mailto:support@bria.ai).\n\n- When `status=COMPLETED`, `result` may also include:\n - `seed` – Deterministic seed used for generation (if supported by the endpoint).\n - `prompt` – Original prompt provided by the user (if applicable).\n - `refined_prompt` – System-enhanced version of the input prompt (if applicable).\n - `structured_prompt` – The detailed JSON structured prompt used for V2 generation.\n", "operationId": "get_status", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the request." }, { "in": "header", "name": "api_token", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The `status` field indicates whether the request completed successfully or failed.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StatusSuccessResponse" }, { "$ref": "#/components/schemas/StatusErrorResponse" } ] }, "examples": { "completed_image_generation": { "summary": "Completed Image Generation Request", "value": { "status": "COMPLETED", "result": { "image_url": "https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/fibo/new_year_2026.png", "seed": "123456", "structured_prompt": "{\"short_description\": \"A photorealistic, high-resolution rendering of balloon lettering spelling out \\\"HAPPY NEW YEAR 2026\\\" against a pristine white backdrop. The balloons are meticulously crafted with a metallic, reflective surface, showcasing a vibrant color palette of Pantone Bran, Crocus, and Deja vu blue. The composition is perfectly aligned and balanced, emphasizing the celebratory message with natural, soft lighting that creates subtle, elegant reflections and shadows.\",\"objects\": [{\"description\": \"A cluster of individual balloon letters forming the word \\\"HAPPY\\\". Each letter is inflated and has a smooth, highly reflective metallic surface, catching and distorting the ambient light. The letters are arranged horizontally, slightly overlapping to create a cohesive word.\",\"location\": \"top-left to center\",\"relationship\": \"Part of the main textual display, positioned above 'NEW YEAR'.\",\"relative_size\": \"large within frame\",\"shape_and_color\": \"Irregular letter shapes, primarily Pantone Bran (a rich, deep orange-brown) with hints of Crocus (a vibrant purple) and Deja vu blue (a muted, dusty blue) in the reflections.\",\"texture\": \"Smooth, highly reflective metallic foil.\",\"appearance_details\": \"Slightly rounded edges, showing subtle seams where the foil is joined. The surface exhibits a high degree of realism with minor imperfections and creases visible upon close inspection.\",\"number_of_objects\": 5,\"orientation\": \"Horizontal\"},{\"description\": \"A cluster of individual balloon letters forming the phrase \\\"NEW YEAR\\\". These letters are also inflated and possess the same metallic, reflective quality as the 'HAPPY' balloons. They are arranged horizontally, directly below 'HAPPY', maintaining a consistent visual style.\",\"location\": \"center\",\"relationship\": \"Part of the main textual display, positioned below 'HAPPY' and above '2026'.\",\"relative_size\": \"large within frame\",\"shape_and_color\": \"Irregular letter shapes, primarily Crocus (a vibrant purple) with reflections of Pantone Bran and Deja vu blue.\",\"texture\": \"Smooth, highly reflective metallic foil.\",\"appearance_details\": \"Each letter is distinct, with a slightly inflated, three-dimensional appearance. The metallic sheen creates a dynamic interplay of light and color across their surfaces.\",\"number_of_objects\": 7,\"orientation\": \"Horizontal\"},{\"description\": \"A cluster of individual balloon numbers forming \\\"2026\\\". These numbers are crafted from the same metallic balloon material, maintaining visual continuity with the words above. They are positioned centrally below 'NEW YEAR'.\",\"location\": \"bottom-center\",\"relationship\": \"Part of the main textual display, positioned below 'NEW YEAR'.\",\"relative_size\": \"large within frame\",\"shape_and_color\": \"Numerical shapes, primarily Deja vu blue (a muted, dusty blue) with reflections of Pantone Bran and Crocus.\",\"texture\": \"Smooth, highly reflective metallic foil.\",\"appearance_details\": \"The numbers appear robust and fully inflated, with crisp edges and a flawless metallic finish that reflects the surrounding light sources.\",\"number_of_objects\": 4,\"orientation\": \"Horizontal\"},{\"description\": \"Several small, spherical balloons scattered around the main lettering, acting as decorative accents. These balloons are also metallic and share the same color palette, adding depth and a festive touch to the scene.\",\"location\": \"scattered around the main lettering\",\"relationship\": \"Complementary decorative elements to the main balloon lettering.\",\"relative_size\": \"small\",\"shape_and_color\": \"Spherical, in Pantone Bran, Crocus, and Deja vu blue.\",\"texture\": \"Smooth, reflective metallic.\",\"appearance_details\": \"Perfectly round and shiny, reflecting miniature versions of the light sources and the main lettering.\",\"number_of_objects\": 5,\"orientation\": \"Various, floating\"}],\"background_setting\": \"A clean, seamless white studio backdrop, providing a stark contrast that makes the colorful balloons pop. The backdrop extends smoothly from the floor to the wall, creating an infinite white space that eliminates distractions and emphasizes the subject.\",\"lighting\": {\"conditions\": \"Bright, natural light, simulating a well-lit studio environment.\",\"direction\": \"Soft, diffused light coming from slightly above and in front of the balloons, with secondary fill light from the sides.\",\"shadows\": \"Soft, subtle, and elongated shadows cast behind and beneath the balloons, indicating depth and dimension without being harsh or distracting. The shadows are light gray against the white background.\"},\"aesthetics\": {\"composition\": \"Centered and perfectly aligned, with the balloon lettering arranged in a clear, readable hierarchy. The overall composition is balanced and symmetrical, drawing the viewer's eye directly to the celebratory message.\",\"color_scheme\": \"A vibrant, harmonious palette of Pantone Bran (orange-brown), Crocus (purple), and Deja vu blue, creating a festive yet sophisticated feel against the neutral white background.\",\"mood_atmosphere\": \"Joyful, celebratory, optimistic, and clean.\",\"preference_score\": \"very high\",\"aesthetic_score\": \"very high\"},\"photographic_characteristics\": {\"depth_of_field\": \"Shallow, with the balloons in sharp focus and the background subtly blurred to emphasize the subject, though the white backdrop inherently provides minimal blur.\",\"focus\": \"Sharp focus on the balloon lettering, highlighting the intricate details and reflective surfaces.\",\"camera_angle\": \"Eye-level, providing a direct and engaging view of the balloon arrangement.\",\"lens_focal_length\": \"Standard lens (e.g., 50mm), ensuring a natural perspective without distortion, ideal for capturing the full arrangement clearly.\"},\"style_medium\": \"photograph\",\"text_render\": [{\"text\": \"HAPPY NEW YEAR 2026\",\"location\": \"center\",\"size\": \"large within frame\",\"color\": \"Pantone Bran, Crocus, Deja vu blue (as balloon colors)\",\"font\": \"inflated balloon lettering\",\"appearance_details\": \"Metallic, reflective, three-dimensional balloon letters.\"}],\"context\": \"This is a concept for a high-resolution, ultra-realistic promotional image or greeting card for a New Year's celebration, intended for digital display or print media.\",\"artistic_style\": \"realistic, detailed, vibrant\"}" }, "request_id": "123456" } }, "completed_image_edit": { "summary": "Completed Request (image editing)", "value": { "status": "COMPLETED", "result": { "image_url": "https://example.com/generated_image.png" }, "request_id": "123456" } }, "completed_video": { "summary": "Completed Request (video)", "value": { "status": "COMPLETED", "result": { "video_url": "https://example.com/generated_video.mp4" }, "request_id": "123456" } }, "completed_structured_prompt": { "summary": "Completed Structured Prompt Request", "value": { "status": "COMPLETED", "result": { "seed": "123456", "structured_prompt": "{\\\"short_description\\\": \\\"A close-up shot of an elegant ring featuring a prominent, teardrop-shaped red gemstone...\\\",\\\"objects\\\": [...],...}" }, "request_id": "123456" } }, "completed_image_edit_with_seed": { "summary": "Completed Request (image edit, with seed)", "value": { "status": "COMPLETED", "result": { "image_url": "https://example.com/generated_image.png", "seed": "42" }, "request_id": "123456" } }, "completed_image_edit_with_prompt": { "summary": "Completed Request (image edit, with prompt)", "value": { "status": "COMPLETED", "result": { "image_url": "https://example.com/generated_image.png", "seed": "42", "prompt": "A fantasy landscape with mountains" }, "request_id": "123456" } }, "completed_image_edit_with_refined_prompt": { "summary": "Completed Request (image edit, with refined prompt)", "value": { "status": "COMPLETED", "result": { "image_url": "https://example.com/generated_image.png", "seed": "42", "refined_prompt": "High-detail fantasy landscape with dramatic mountains" }, "request_id": "123456" } }, "error": { "summary": "Error Response", "value": { "status": "ERROR", "error": { "code": 500, "message": "Internal Server Error", "details": "Unexpected error occurred." }, "request_id": "123456" } } } } } }, "404": { "description": "The provided `request_id` does not exist or has expired.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NOT_FOUND" ] } }, "required": [ "status" ] }, "examples": { "not_found_example": { "summary": "Request ID Not Found", "value": { "status": "NOT_FOUND" } } } } } }, "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" }, "examples": { "internal_error": { "summary": "Service Outage", "value": { "error": { "code": 503, "message": "Service Unavailable", "details": "Bria's Status Service is temporarily unavailable. Please try again later." } } } } } } } } } } }, "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" ] }, "StatusSuccessResponse": { "type": "object", "properties": { "result": { "oneOf": [ { "title": "ImageResult", "type": "object", "properties": { "image_url": { "type": "string" }, "seed": { "type": "integer", "description": "Deterministic generation seed (returned only for endpoints that support reproducible outputs)." }, "prompt": { "type": "string", "description": "Original prompt sent by the user (returned only if applicable)." }, "refined_prompt": { "type": "string", "description": "Refined version of the input prompt (returned only if applicable and supported by the endpoint)." }, "structured_prompt": { "type": "string", "description": "The detailed JSON structured prompt used for the V2 generation (returned only by V2 image generation and structured prompt generation endpoints)." } }, "required": [ "image_url" ] }, { "title": "VideoResult", "type": "object", "properties": { "video_url": { "type": "string" } }, "required": [ "video_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": [ "ERROR", "UNKNOWN" ] } }, "required": [ "status" ] } ] } } } }