openapi: 3.0.0
info:
  title: Overview
  version: ''
  description: >
    Bria's Product Shot Editing API empowers builders with essential tools for
    enhancing product visuals.


    These APIs offer capabilities including precise product cutouts,
    professional packshots with customizable backgrounds, consistent shadow
    effects, and AI-powered lifestyle shots that can place products in
    contextually relevant environments using both textual descriptions and
    reference images.   
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:
  /product/cutout:
    post:
      summary: Product Cutout
      tags:
        - Endpoints
      description: >
        This capability allows you to create a precise cutout of a product from
        any given image. This feature is especially valuable for eCommerce
        platforms and applications, serving as a fundamental building block for
        crafting a user-friendly interface. 


        This API endpoint supports content moderation via an optional parameter
        that can prevent processing if input images contain inappropriate
        content or if the modified output would contain inappropriate content.
      operationId: product-cutout
      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
              properties:
                sku:
                  type: string
                  description: >-
                    The Stock Keeping Unit identifier for the product. This
                    parameter is optional.
                image_url:
                  type: string
                  description: >-
                    The URL of the image containing the product to be cut out.
                    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 image file containing the product to be cut out, in
                    base64 format. Used if image_url is not provided. Accepted
                    formats are jpeg, jpg, png, webp. Maximum file size 12MB.
                force_rmbg:
                  type: boolean
                  default: false
                  description: >-
                    Forces background removal, even if the original image
                    already contains an alpha channel. Useful for refining
                    existing foreground/background separation or ignoring
                    unnecessary alpha channels.
                content_moderation:
                  type: boolean
                  default: false
                  description: >
                    When enabled, applies content moderation to both input
                    visuals and modified outputs.


                    For input images:

                    - Processing stops if the image fails moderation

                    - Returns a 422 error with details about which parameter
                    failed


                    For output images:

                    - If the modified image fails moderation, returns a 422
                    error
            example:
              sku: '12345'
              image_url: URL
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result_url:
                    type: string
                    description: >-
                      The URL of the processed product cutout image. This is a
                      temporary URL that expires after 1 hour.
              example:
                result_url: URL
        '400':
          description: Bad request.
        '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.
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: string
              examples:
                input_violation:
                  value: >-
                    The request could not be completed because the visual in the
                    '{parameter_name}' parameter did not pass content
                    moderation.
                output_violation:
                  value: >-
                    The request could not be completed because the modified
                    visual did not pass content moderation.
        '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.
  /product/packshot:
    post:
      summary: Product Packshot
      tags:
        - Endpoints
      description: >-
        The Product Pack Shot feature is designed to create professional
        standard pack shots. The output is a 2000x2000 px image, with the
        product size and location according to best practices. This feature can
        allow users to take any photo of a product and transform it into a
        professional pack shot, placing the product on a clean, seamless
        background, typically white but customizable to any color.


        This API endpoint supports content moderation via an optional parameter
        that can prevent processing if input images contain inappropriate
        content or if the modified output would contain inappropriate content.
      operationId: product-packshot
      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
              properties:
                sku:
                  type: string
                  description: >-
                    The Stock Keeping Unit identifier for the product. This
                    parameter is optional.
                image_url:
                  type: string
                  description: >-
                    The URL of the product image or product cutout. 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 product image or product cutout file, in base64 format.
                    Used if image_url is not provided. Accepted formats are
                    jpeg, jpg, png, webp. Maximum file size 12MB.
                background_color:
                  type: string
                  description: >-
                    The background hex color code for the pack shot. Optionally,
                    use 'transparent' for a transparent background. This
                    parameter is optional.
                  default: '#FFFFFF'
                force_rmbg:
                  type: boolean
                  default: false
                  description: >-
                    Forces background removal, even if the original image
                    already contains an alpha channel. Useful for refining
                    existing foreground/background separation or ignoring
                    unnecessary alpha channels.
                content_moderation:
                  type: boolean
                  default: false
                  description: >
                    When enabled, applies content moderation to both input
                    visuals and modified outputs.


                    For input images:

                    - Processing stops if the image fails moderation

                    - Returns a 422 error with details about which parameter
                    failed


                    For output images:

                    - If the modified image fails moderation, returns a 422
                    error
            example:
              sku: '12345'
              image_url: URL
              background_color: '#FFFFFF'
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result_url:
                    type: string
                    description: >-
                      The URL of the processed product pack shot image. This is
                      a temporary URL that expires after 1 hour.
              example:
                result_url: URL
        '400':
          description: Bad request.
        '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.
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: string
              examples:
                input_violation:
                  value: >-
                    The request could not be completed because the visual in the
                    '{parameter_name}' parameter did not pass content
                    moderation.
                output_violation:
                  value: >-
                    The request could not be completed because the modified
                    visual did not pass content moderation.
        '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.
  /product/shadow:
    post:
      summary: Product Shadow
      tags:
        - Endpoints
      description: >-
        The Product Shadow API allows you to add consistent and customizable
        shadow to a product cutout. This feature is designed to work in
        combination with other capabilities like product cutout,  product
        packshot and product lifestyle shots, enhancing the visual appeal of
        e-commerce and product imagery.


        If the product image isn't a product cutout, you should use the product
        cutout API first. The product shadow API accepts a product cutout as
        input. Once you have a product cutout with a shadow, you can use it in
        product packshot or product lifestyle shot APIs, where needed.


        This API endpoint supports content moderation via an optional parameter
        that can prevent processing if input images contain inappropriate
        content or if the modified output would contain inappropriate content.
      operationId: product-shadow
      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
              properties:
                sku:
                  type: string
                  description: >-
                    The Stock Keeping Unit identifier for the product. This
                    parameter is optional.
                image_url:
                  type: string
                  description: >-
                    The URL of the product image or product cutout. 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. The input image must have a transparent
                    background, could be obtained by using our background
                    removal or cutout features.
                file:
                  type: string
                  description: >-
                    The product image or product cutout file, in base64 format.
                    Used if image_url is not provided. Accepted formats are
                    jpeg, jpg, png, webp. Maximum file size 12MB. The input
                    image must have a transparent background, could be obtained
                    by using our background removal or cutout features.
                type:
                  type: string
                  description: >-
                    Specifies the type of shadow. It can be 'regular' or
                    'float'. This parameter is optional.
                  default: regular
                background_color:
                  type: string
                  description: >-
                    The background hex color code for the resulting image. If
                    you would like to get a transparent background, don't
                    include this parameter in the request. This parameter is
                    optional.
                shadow_color:
                  type: string
                  description: The shadow color hex code. This parameter is optional.
                  default: '#000000'
                shadow_offset:
                  type: array
                  description: >-
                    Controls the position of the shadow relative to the object,
                    in pixels. Accepts a tuple-like list `[x, y]` where x and y
                    can be positive or negative values. This parameter is
                    optional.
                  items:
                    type: integer
                  default:
                    - 0
                    - 15
                shadow_intensity:
                  type: integer
                  description: >-
                    Adjusts the intensity of the shadow. This parameter is
                    optional.
                  minimum: 0
                  maximum: 100
                  default: 60
                shadow_blur:
                  type: integer
                  description: >-
                    Controls the blur level of the shadow's edges. This
                    parameter is optional. Default for 'shadow_type'=regular is
                    15, while for 'shadow_type'=float is 20.
                shadow_width:
                  type: integer
                  description: >-
                    (For floating shadows) Controls the width of the elliptical
                    shadow, in pixels that could be positive and negative. As
                    default the value is according to the width of the product.
                    This parameter is optional.
                shadow_height:
                  type: integer
                  description: >-
                    (For floating shadows) Controls the height of the elliptical
                    shadow, in pixels that could be positive and negative. This
                    parameter is optional.
                  default: 70
                force_rmbg:
                  type: boolean
                  default: false
                  description: >-
                    Forces background removal, even if the original image
                    already contains an alpha channel. Useful for refining
                    existing foreground/background separation or ignoring
                    unnecessary alpha channels.
                content_moderation:
                  type: boolean
                  default: false
                  description: >
                    When enabled, applies content moderation to both input
                    visuals and modified outputs.


                    For input images:

                    - Processing stops if the image fails moderation

                    - Returns a 422 error with details about which parameter
                    failed


                    For output images:

                    - If the modified image fails moderation, returns a 422
                    error
            example:
              sku: '12345'
              image_url: URL
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result_url:
                    type: string
                    description: >-
                      The URL of the processed product pack shot image. This is
                      a temporary URL that expires after 1 hour.
              example:
                result_url: URL
        '400':
          description: Bad request.
        '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.
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: string
              examples:
                input_violation:
                  value: >-
                    The request could not be completed because the visual in the
                    '{parameter_name}' parameter did not pass content
                    moderation.
                output_violation:
                  value: >-
                    The request could not be completed because the modified
                    visual did not pass content moderation.
        '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.
  /product/lifestyle_shot_by_text:
    post:
      summary: Lifestyle Product Shot by Text
      tags:
        - Endpoints
      description: >-
        Creates enriched product shots by placing them in various environments
        using textual descriptions. 



        This endpoint allows adjusting the background of a product by replacing
        it with a solid color. You can specify a hex color code (e.g., #FF5733)
        in the scene_description to control the background color. This feature
        is only available when generating a single result (num_results=1).



        Additionally, you can change the image size of the final result as well
        as the positioning of the product in the image. This will enable you to
        create new and unique variations of your original image.



        This API endpoint supports content moderation via an optional parameter
        that can prevent processing if input images contain inappropriate
        content, and filters out unsafe modified images - the first blocked
        input image will fail the entire request.
      operationId: product-lifestyle-shot-by-text
      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
              properties:
                sku:
                  type: string
                  description: >-
                    The Stock Keeping Unit identifier for the product. This
                    parameter is optional.
                sync:
                  type: boolean
                  default: false
                  description: >-
                    Determines the response mode. When true, responses are
                    synchronous. With false, responses are asynchronous,
                    immediately providing URLs for images that are generated in
                    the background. It is recommended to use sync=false for
                    optimal performance. When generating more than 1 result, you
                    should use the value false. When placement_type is
                    automatic, sync has to be false.
                fast:
                  type: boolean
                  default: true
                  description: >-
                    Determines the generation mode. When true, the generation
                    will utilize the fast mode which provides the best balance
                    between speed and quality. The false, the regular mode will
                    be utilized.
                image_url:
                  type: string
                  description: >-
                    The URL of the product shot to be placed in a lifestyle
                    shot. 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 product shot file to be placed in a lifestyle shot, in
                    base64 format. Used if image_url is not provided. Accepted
                    formats are jpeg, jpg, png, webp. Maximum file size 12MB.
                scene_description:
                  type: string
                  description: >-
                    Text description of the new scene or background for the
                    provided product shot. Bria currently supports prompts in
                    English only, excluding special characters.
                optimize_description:
                  type: boolean
                  default: true
                  description: >-
                    When true, an additional logic takes the scene_description
                    that was included and adjusts it to achieve optimal results.
                    Built with Meta Llama 3.
                num_results:
                  type: integer
                  default: 4
                  description: >-
                    The number of lifestyle product shots you would like to
                    generate. You will get num_results x 10 results when
                    placement_type=automatic and according to the number of
                    required placements x num_results if
                    placement_type=manual_placement.
                exclude_elements:
                  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, excluding special characters.
                placement_type:
                  type: string
                  description: >-
                    This parameter allows you to control the positioning of the
                    product in the image.

                    - "original" will preserve the original position of the
                    product in the image.

                    - "automatic" will generate results with the 10 recommended
                    positions for the product.

                    - "manual_placement" will allow you to select predefined
                    positions, using the parameter "manual_placement_selection".

                    - "custom_coordinates" Provides precise control over the
                    size and position of the image using the parameters
                    "foreground_image_size" and "foreground_image_location".
                    This includes positions outside the canvas, which may result
                    in cropping.

                    - "manual_padding" will allow you to control the position
                    and size of the image by defining the desired padding in
                    pixels around the product.
                  enum:
                    - original
                    - automatic
                    - manual_placement
                    - manual_padding
                    - custom_coordinates
                original_quality:
                  type: boolean
                  default: false
                  description: >-
                    This flag is only relevant when placement_type=original. If
                    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.
                shot_size:
                  type: array
                  items:
                    type: integer
                  default:
                    - 1000
                    - 1000
                  description: >-
                    The desired size of the final product shot. For optimal
                    results, the total number of pixels should be around
                    1,000,000. This parameter is only relevant when
                    placement_type is automatic,manual_placement or
                    custom_coordinates.
                foreground_image_size:
                  type: array
                  items:
                    type: integer
                  description: >-
                    Specifies the desired dimensions of the foreground image
                    within the generated output. The size is defined as an array
                    of integers representing [width, height] in pixels.
                foreground_image_location:
                  type: array
                  items:
                    type: integer
                  description: >-
                    Specifies the desired [x, y] coordinates for positioning the
                    foreground image within the full shot. The coordinates
                    represent the upper-left corner of the foreground image.
                    Values can extend outside the shot, in which case the input
                    image will be cropped accordingly.
                manual_placement_selection:
                  type: array
                  items:
                    type: string
                    enum:
                      - upper_left
                      - upper_right
                      - bottom_left
                      - bottom_right
                      - right_center
                      - left_center
                      - upper_center
                      - bottom_center
                      - center_vertical
                      - center_horizontal
                  default:
                    - upper_left
                  description: >-
                    If you've selected placement_type=manual_placement, you
                    should use this parameter to specify which
                    placements/positions you would like to use from the list.
                    You can select more than one placement in one request.
                padding_values:
                  type: array
                  items:
                    type: integer
                  default:
                    - 0
                    - 0
                    - 0
                    - 0
                  description: >-
                    The desired padding in pixels around the product, when using
                    placement_type=manual_padding. The order of the values is
                    [left, right, top, bottom]. For optimal results, the total
                    number of pixels, including padding, should be around
                    1,000,000. It is recommended to first use the product cutout
                    API, get the cutout and understand the size of the result,
                    and then define the required padding and use the cutout as
                    an input for this API.
                force_rmbg:
                  type: boolean
                  default: false
                  description: >-
                    Forces background removal, even if the original image
                    already contains an alpha channel. Useful for refining
                    existing foreground/background separation or ignoring
                    unnecessary alpha channels.
                content_moderation:
                  type: boolean
                  default: false
                  description: >
                    When enabled, applies content moderation to both input
                    visuals and modified outputs.


                    For input images:

                    - Processing stops at the first image that fails moderation

                    - Returns a 422 error with details about which parameter
                    failed


                    For synchronous requests (sync=true):

                    - If all modified images fail moderation, returns a 422
                    error

                    - If some images pass and others fail, returns a 200
                    response with successful outputs and "blocked" objects for
                    failed ones


                    For asynchronous requests (sync=false):

                    - Failed images are replaced with zero-byte files at their
                    placeholder URLs

                    - Successful images are stored at their original placeholder
                    URLs   
            examples:
              Original placement:
                value:
                  image_url: IMAGE_URL
                  scene_description: In a living room interior, on a kitchen counter
                  placement_type: original
                  num_results: 2
                  original_quality: true
                  optimize_description: true
                  sync: true
              Automatic placements:
                value:
                  image_url: IMAGE_URL
                  scene_description: in a living room interior, on a kitchen counter
                  placement_type: automatic
                  shot_size:
                    - 900
                    - 550
                  num_results: 1
                  optimize_description: true
              Manual placement from a list:
                value:
                  image_url: IMAGE_URL
                  scene_description: in a living room interior, on a kitchen counter
                  placement_type: manual_placement
                  shot_size:
                    - 900
                    - 550
                  manual_placement_selection:
                    - upper_center
                    - bottom_center
                  num_results: 2
                  optimize_description: true
                  sync: true
              Manual padding:
                value:
                  image_url: IMAGE_URL
                  scene_description: in a living room interior, on a kitchen counter
                  placement_type: manual_padding
                  padding_values:
                    - 20
                    - 30
                    - 20
                    - 30
                  num_results: 2
                  optimize_description: true
                  sync: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    description: >
                      The array contains the results created in the request. In
                      each result, the first value represents the URL of the
                      result, the second value represents the seed, and the
                      third value represents the session id of the result. It
                      will take a few seconds for the image to become available
                      via the URL if sync=false. You can recreate the same
                      result in the future by using the seed as part of the
                      request.


                      When content_moderation is true:

                      - For synchronous requests (sync=true): Results array will
                      contain both successful generations and "blocked" objects
                      for images that failed moderation

                      - For asynchronous requests (sync=false): Failed images
                      will be replaced with zero-byte files at their placeholder
                      URLs
                    items:
                      type: array
                      items:
                        type: string
              examples:
                success:
                  value:
                    result:
                      - - https://storage.server/outputs/valid_output_1.jpeg
                        - '123111'
                        - valid_output_1.jpeg
                      - - https://storage.server/outputs/valid_output_2.jpeg
                        - '123222'
                        - valid_output_2.jpeg
                partial_success:
                  value:
                    result:
                      - - https://storage.server/outputs/valid_output_1.jpeg
                        - '123111'
                        - valid_output_1.jpeg
                      - - blocked:true
                        - error_code:422
                        - >-
                          description:The request could not be completed because
                          the modified visual did not pass content moderation.
        '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.
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: string
              examples:
                input_violation:
                  value: >-
                    The request could not be completed because the visual in the
                    '{parameter_name}' parameter did not pass content
                    moderation.
                all_outputs_blocked:
                  value: >-
                    The request could not be completed because all modified
                    visuals failed content moderation.
        '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.
  /product/lifestyle_shot_by_image:
    post:
      summary: Lifestyle Product Shot by Image
      tags:
        - Endpoints
      description: >-
        Generates enriched product shots by placing them in visually compelling
        environments, guided by a reference image. 


        Additionally, you can change the image size of the final result as well
        as the positioning of the product in the image. This will enable you to
        create new and unique variations of your original image.

        This API endpoint supports content moderation via an optional parameter
        that can prevent processing if input images contain inappropriate
        content, and filters out unsafe modified images - the first blocked
        input image will fail the entire request.
      operationId: product-lifestyle-shot-by-image
      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
              properties:
                sku:
                  type: string
                  description: >-
                    The Stock Keeping Unit identifier for the product. This
                    parameter is optional.
                sync:
                  type: boolean
                  default: false
                  description: >-
                    Determines the response mode. When true, responses are
                    synchronous. With false, responses are asynchronous,
                    immediately providing URLs for images that are generated in
                    the background. It is recommended to use sync=false for
                    optimal performance. When generating more than 1 result, you
                    should use the value false.
                image_url:
                  type: string
                  description: >-
                    The URL of the product shot to be placed in a lifestyle
                    shot. 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 product shot file to be placed in a lifestyle shot, in
                    base64 format. Used if image_url is not provided. Accepted
                    formats are jpeg, jpg, png, webp. Maximum file size 12MB.
                ref_image_url:
                  type: array
                  items:
                    type: string
                  description: >-
                    The URL of the reference image to be used for generating the
                    lifestyle shot. If both ref_image_url and ref_image_file are
                    provided, ref_image_url will be used. Accepted formats are
                    jpeg, jpg, png, webp. Maximum file size 12MB.
                ref_image_file:
                  type: array
                  items:
                    type: string
                  description: >-
                    The reference image file to be used for generating the
                    lifestyle shot, in base64 format. Only a single refernce
                    image is supported at the moment. Used if ref_image_url is
                    not provided. Accepted formats are jpeg, jpg, png, webp.
                    Maximum file size 12MB.
                enhance_ref_image:
                  type: boolean
                  default: true
                  description: >-
                    When set to True, enhances the reference image by applying
                    adjustments, such as lighting, shadows, and texture
                    refinements, to produce more realistic and visually cohesive
                    results. When enabled, this may also incorporate subtle
                    elements from the reference image into the generated
                    background for added authenticity.
                ref_image_influence:
                  type: number
                  format: float
                  minimum: 0
                  maximum: 1
                  default: 1
                  description: >-
                    Controls the degree of similarity between the generated
                    background and the reference image, where 0.0 produces
                    minimal resemblance and 1.0 creates a highly similar output.
                num_results:
                  type: integer
                  default: 4
                  description: >-
                    The number of lifestyle product shots you would like to
                    generate.
                placement_type:
                  type: string
                  description: >-
                    This parameter allows you to control the positioning of the
                    product in the image.

                    - "original" will preserve the original position of the
                    product in the image.

                    - "automatic" will generate results with the 10 recommended
                    positions for the product.

                    - "manual_placement" will allow you to select predefined
                    positions, using the parameter "manual_placement_selection".

                    - "custom_coordinates" Provides precise control over the
                    size and position of the image using the parameters
                    "foreground_image_size" and "foreground_image_location".
                    This includes positions outside the canvas, which may result
                    in cropping.

                    - "manual_padding" will allow you to control the position
                    and size of the image by defining the desired padding in
                    pixels around the product.
                  enum:
                    - original
                    - automatic
                    - manual_placement
                    - manual_padding
                    - custom_coordinates
                original_quality:
                  type: boolean
                  default: false
                  description: >-
                    This flag is only relevant when placement_type=original. If
                    true, the output image retains the original input image's
                    size (and not the reference image size); otherwise, the
                    image is scaled to 1 megapixel (1MP) while preserving its
                    aspect ratio.
                shot_size:
                  type: array
                  items:
                    type: integer
                  default:
                    - 1000
                    - 1000
                  description: >-
                    The desired size of the final product shot. For optimal
                    results, the total number of pixels should be around
                    1,000,000. This parameter is only relevant when
                    placement_type is automatic,manual_placement or
                    custom_coordinates.
                foreground_image_size:
                  type: array
                  items:
                    type: integer
                  description: >-
                    Specifies the desired dimensions of the foreground image
                    within the generated output. The size is defined as an array
                    of integers representing [width, height] in pixels.
                foreground_image_location:
                  type: array
                  items:
                    type: integer
                  description: >-
                    Specifies the desired [x, y] coordinates for positioning the
                    foreground image within the full shot. The coordinates
                    represent the upper-left corner of the foreground image.
                    Values can extend outside the shot, in which case the input
                    image will be cropped accordingly.
                manual_placement_selection:
                  type: array
                  items:
                    type: string
                    enum:
                      - upper_left
                      - upper_right
                      - bottom_left
                      - bottom_right
                      - right_center
                      - left_center
                      - upper_center
                      - bottom_center
                      - center_vertical
                      - center_horizontal
                  default:
                    - upper_left
                  description: >-
                    If you've selected placement_type=manual_placement, you
                    should use this parameter to specify which
                    placements/positions you would like to use from the list.
                    You can select more than one placement in one request.
                padding_values:
                  type: array
                  items:
                    type: integer
                  default:
                    - 0
                    - 0
                    - 0
                    - 0
                  description: >-
                    The desired padding in pixels around the product, when using
                    placement_type=manual_padding. The order of the values is
                    [left, right, top, bottom]. For optimal results, the total
                    number of pixels, including padding, should be around
                    1,000,000. It is recommended to first use the product cutout
                    API, get the cutout and understand the size of the result,
                    and then define the required padding and use the cutout as
                    an input for this API.
                force_rmbg:
                  type: boolean
                  default: false
                  description: >-
                    Forces background removal, even if the original image
                    already contains an alpha channel. Useful for refining
                    existing foreground/background separation or ignoring
                    unnecessary alpha channels.
                content_moderation:
                  type: boolean
                  default: false
                  description: >
                    When enabled, applies content moderation to both input
                    visuals and modified outputs.


                    For input images:

                    - Processing stops at the first image that fails moderation

                    - Returns a 422 error with details about which parameter
                    failed


                    For synchronous requests (sync=true):

                    - If all modified images fail moderation, returns a 422
                    error

                    - If some images pass and others fail, returns a 200
                    response with successful outputs and "blocked" objects for
                    failed ones


                    For asynchronous requests (sync=false):

                    - Failed images are replaced with zero-byte files at their
                    placeholder URLs

                    - Successful images are stored at their original placeholder
                    URLs  
            example:
              image_url: URL
              ref_image_urls:
                - REFERENCE_URL
              num_results: 2
              sync: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    description: >
                      The array contains the results created in the request. In
                      each result, the first value represents the URL of the
                      result, the second value represents the seed, and the
                      third value represents the session id of the result. It
                      will take a few seconds for the image to become available
                      via the URL if sync=false. You can recreate the same
                      result in the future by using the seed as part of the
                      request.


                      When content_moderation is true:

                      - For synchronous requests (sync=true): Results array will
                      contain both successful generations and "blocked" objects
                      for images that failed moderation

                      - For asynchronous requests (sync=false): Failed images
                      will be replaced with zero-byte files at their placeholder
                      URLs
                    items:
                      type: array
                      items:
                        type: string
              examples:
                success:
                  value:
                    result:
                      - - https://storage.server/outputs/valid_output_1.jpeg
                        - '123111'
                        - valid_output_1.jpeg
                      - - https://storage.server/outputs/valid_output_2.jpeg
                        - '123222'
                        - valid_output_2.jpeg
                partial_success:
                  value:
                    result:
                      - - https://storage.server/outputs/valid_output_1.jpeg
                        - '123111'
                        - valid_output_1.jpeg
                      - - blocked:true
                        - error_code:422
                        - >-
                          description:The request could not be completed because
                          the modified visual did not pass content moderation.
        '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.
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: string
              examples:
                input_violation:
                  value: >-
                    The request could not be completed because the visual in the
                    '{parameter_name}' parameter did not pass content
                    moderation.
                all_outputs_blocked:
                  value: >-
                    The request could not be completed because all modified
                    visuals failed content moderation.
        '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.
  /products/consistent_shots:
    post:
      summary: Consistent Product Shots (Coming Soon)
      tags:
        - Endpoints
      description: >-
        **Description**

        This feature allows users to create consistent product shots by
        providing either a textual description of a scene or an image, along
        with a group of product images. The resulting consistent product shots
        are ideal for use on social media, eCommerce websites, product catalogs,
        and other marketing materials, ensuring a uniform and professional
        appearance across all platforms.
      operationId: consistent-product-shots
      responses:
        '200':
          description: Successful operation.
  /product/contextual_keyword_extraction:
    post:
      summary: Contextual Keyword Extraction (Coming Soon)
      tags:
        - Endpoints
      description: >-
        **Description**

        This feature allows users to extract relevant keywords from an image and
        its context, focusing on the primary product rather than secondary
        elements. This capability enhances search optimization in eCommerce by
        ensuring that the keywords accurately represent the product being sold.
        It can be particularly useful for improving product searchability on
        eCommerce websites, enhancing SEO for product listings, automating
        content management, and optimizing social media marketing efforts.
      operationId: contextual-keyword-extraction
      responses:
        '200':
          description: Successful operation.
components: {}
