{
  "openapi": "3.0.0",
  "info": {
    "title": "Overview",
    "version": "",
    "description": "For access to the AI Search API (excluding the 'Caption' endpoint), please [Contact Us](https://bria.ai/contact-us) \n\nBria's AI Search API equips builders with advanced visual search capabilities that go beyond traditional label or keyword matching.  \n\nThe API enables searching through registered images using either text queries or image references, with results sorted by match scores. \n\nDevelopers can leverage features including image captioning, similarity search, and search refinements through style, atmosphere, and camera angle filters.  \n"
  },
  "externalDocs": {
    "description": "Register and get API Access",
    "url": "https://platform.bria.ai/console/account/api-keys"
  },
  "servers": [
    {
      "url": "https://engine.prod.bria-api.com/v1"
    }
  ],
  "paths": {
    "/caption": {
      "post": {
        "summary": "Get Caption",
        "tags": [
          "Endpoints"
        ],
        "description": "\n\n**Description**\n\n\nThe *Caption Route* is used to get a caption that describes the given image.",
        "operationId": "get-caption",
        "parameters": [
          {
            "in": "header",
            "name": "api_token",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image_url": {
                    "type": "string",
                    "description": "The URL of the input image. If both image_url and image_file are provided, image_url will be used. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB."
                  },
                  "file": {
                    "type": "string",
                    "description": "The file of the input image, in base64 format. Used if image_url is not provided. Accepted formats are jpeg, jpg, png, webp. Maximum file size 12MB."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "caption": {
                            "type": "string",
                            "example": "woman walking on a bridge in the jungle"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Missing or invalid parameters."
          },
          "401": {
            "description": "Unauthorized. Invalid API key or authentication token."
          },
          "404": {
            "description": "Not found. Image could not be found at the provided URL."
          },
          "413": {
            "description": "Payload too large. Image file size exceeds the 12MB limit."
          },
          "415": {
            "description": "Unsupported media type. Invalid file type. Supported file types are jpeg, jpg, png, webp."
          },
          "429": {
            "description": "Request limit exceeded. Your account has reached its maximum allowed requests. Please upgrade your plan or try again later."
          },
          "460": {
            "description": "Failed to download image."
          },
          "500": {
            "description": "Internal server error. An error occurred on the server."
          }
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Search by text",
        "tags": [
          "Endpoints"
        ],
        "description": "**Description**\n\nBy using the *Search Route*, you can utilize Bria's generative search capabilities, which don't require labels or keywords. The user can send any text query and receive relevant images that match the query.\n\nThe *Search Route* returns the images, sorted by the match score, from highest match to lowest match. The images are returned in batches, and you can specify how many images to receive in one batch, and which batch to receive in each call.\n\nSearch will only work on images that have been onboarded using the `register` endpoint.\n**Note:** To use this endpoint, please [Contact Us](https://bria.ai/contact-us).",
        "operationId": "search",
        "parameters": [
          {
            "in": "header",
            "name": "api_token",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "woman traveling in the world"
            },
            "description": "the text query for which the user is looking for matching images."
          },
          {
            "name": "num_results_per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 1
            },
            "description": "how many images you would like to receive from the gallery search. The default value is 50. The maximum value is 500. No need to use this parameter when gallery_search=false."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 1
            },
            "description": "which batch of images you would like to receive in the current call. Synthetic results will only be included in page no. 1. The default value is 1. For each query, we support 800 results, so if you set num_results_per_page=50, you will have 16 pages of results."
          },
          {
            "name": "gallery_id",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "425"
            },
            "description": "Bria will provide you with this parameter which represents your account's image gallery. You must include this parameter."
          },
          {
            "name": "style",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "photo realistic",
              "enum": [
                "stock photography",
                "photo realistic",
                "fashion",
                "retro",
                "sports",
                "still life",
                "hyper realistic",
                "travel",
                "artistic",
                "3d render",
                "realistic",
                "fantasy",
                "comic book",
                "minimalistic"
              ]
            },
            "description": "Which style you would like to see in your results, this parameter is optional."
          },
          {
            "name": "atmosphere",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "dramatic",
                "vivid",
                "warm",
                "cool"
              ],
              "example": "dramatic"
            },
            "description": "Which atmosphere you would like to get in your results, this parameter is optional."
          },
          {
            "name": "camera",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "portrait",
                "close up",
                "aerial",
                "landscape"
              ],
              "example": "portrait"
            },
            "description": "Which camera angle you would like to see in your results, this parameter is optional."
          },
          {
            "name": "medium",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "photography",
                "art"
              ],
              "example": "photography"
            },
            "description": "Which medium should be included in your results, this parameter is optional."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "description": "there are multiple objects in this array (based on the amount specified in num_results_per_page) and each object represents a single image. The images in the array are sorted by the similarity score, from the highest to the lowest. If the specified batch (=page) is empty, the results array will be empty.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "visual_id": {
                            "type": "string",
                            "description": "visual id of the image, documented in Bria.",
                            "example": "a169a6862f24de75"
                          },
                          "org_image_key": {
                            "type": "string",
                            "description": "It will be returned if the image was registered using an org_image_key.",
                            "example": "None"
                          },
                          "source_url": {
                            "type": "string",
                            "description": "It will be returned if the image was registered using a URL.",
                            "example": "None"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request."
          },
          "404": {
            "description": "Specified Image does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Request limit exceeded. Your account has reached its maximum allowed requests. Please upgrade your plan or try again later."
          },
          "500": {
            "description": "Internal server error."
          },
          "506": {
            "description": "Insufficient data. The given input is not supported by the Bria API."
          }
        }
      }
    },
    "/search_similar_images": {
      "get": {
        "summary": "Search by Image",
        "tags": [
          "Endpoints"
        ],
        "description": "**Description**\n\nBy using the *Search Route*, you can utilize Bria's generative search capabilities, which don't require labels or keywords. The user can send any text query and receive relevant images that match the query.\n\nThe *Search Route* returns the images, sorted by the match score, from highest match to lowest match. The images are returned in batches, and you can specify how many images to receive in one batch, and which batch to receive in each call.\n\nSearch will only work on images that have been onboarded using the `register` endpoint.\n\n**Note:** To use this endpoint, please [Contact Us](https://bria.ai/contact-us).",
        "operationId": "search-similar-images",
        "parameters": [
          {
            "in": "header",
            "name": "api_token",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "vhash",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "e01592ef1188df76"
            },
            "description": "the visual id of the image for which the user is looking for similar images."
          },
          {
            "name": "num_results_per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 1
            },
            "description": "how many images you would like to receive in the current call. The default value is 50. The maximum value is 500."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 1
            },
            "description": "which batch of images you would like to receive in the current call. The default value is 1. For each query, we support 800 results, so if you set num_results_per_page=50, you will have 16 pages of results."
          },
          {
            "name": "gallery_id",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "425"
            },
            "description": "Bria will provide you with this parameter which represents your account's image gallery. You must include this parameter."
          },
          {
            "name": "url",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "If you are using the vhash paramater, there is no need to use this parameter"
            },
            "description": "URL of an image, for which you would like to find similar images. When you want to search based on modified images, or images that have not been uploaded or registered to Bria, you can use this parameter. When this parameter is provided, the visual_id parameter can be None. The supported file types are jpg, jpeg and png, up to 12 mb."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "description": "there are multiple objects in this array (based on the amount specified in num_results_per_page) and each object represents a single image. The images in the array are sorted by the similarity score, from the highest to the lowest. If the specified batch (=page) is empty, the results array will be empty.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "visual_id": {
                            "type": "string",
                            "description": "visual id of the image, documented in Bria.",
                            "example": "a169a6862f24de75"
                          },
                          "org_image_key": {
                            "type": "string",
                            "description": "It will be returned if the image was registered using an org_image_key.",
                            "example": "None"
                          },
                          "source_url": {
                            "type": "string",
                            "description": "It will be returned if the image was registered using a URL.",
                            "example": "None"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request."
          },
          "404": {
            "description": "Specified Image does not exist."
          },
          "405": {
            "description": "Method not allowed."
          },
          "429": {
            "description": "Request limit exceeded. Your account has reached its maximum allowed requests. Please upgrade your plan or try again later."
          },
          "500": {
            "description": "Internal server error."
          },
          "506": {
            "description": "Insufficient data. The given input is not supported by the Bria API."
          }
        }
      }
    }
  },
  "components": {}
}