openapi: 3.0.3
x-bc-implicit-head: true
x-bc-implicit-options: true
info:
  title: Brightcove Image API
  description: |-
    The Images API allows you to resize, crop, and/or rotate an image.

    **Supported image formats: png, jpg, gif**

    **Base URL: https://images.brightcovecdn.com**
  version: 1.0.0
  x-bc-access: public
servers:
  - url: "https://images.brightcovecdn.com"
    variables: {}
  - url: "https://images-stage.brightcovecdn.com"
    variables: {}
  - url: "https://images-qa.brightcovecdn.com"
    variables: {}
components:
  parameters:
    AccountId:
      description: Account ID.
      explode: false
      in: path
      name: account_id
      required: true
      schema:
        type: string
      style: simple
    ImageURL:
      name: imageURL
      in: path
      description: >
        image URL - must be `encodeURIComponent` encoded. You can use this [string encoder](https://apis.support.brightcove.com/general/utilities/string-encoder.html)
      required: true
      style: simple
      schema:
        type: string
    ImageToken:
      name: image-token
      in: path
      description: A generated Image Token per account to allow images transformations. Tokens must be obtained from Brightcove Support.
      required: true
      style: simple
      schema:
        type: string
    Crop:
      name: crop
      explode: true
      in: query
      description: >-
        Crop width and height in the format 200x200 - note that you can use any combination of the 3 parameters together.
      required: false
      style: form
      schema:
        type: string
    Fallback:
      name: fallback
      explode: true
      in: query
      description: >-
        If `true` a black image will be returned if the requested image cannot be.
      required: false
      style: form
      schema:
        type: boolean
        default: false
    FillArea:
      name: fillArea
      explode: true
      in: query
      description: >-
        Keep the aspect ratio of the image filling entirely the area given by the resize parameter. Default behavior fills only one side of the same area.
      required: false
      style: form
      schema:
        type: boolean
        default: false
    Nocache:
      name: nocache
      explode: true
      in: query
      description: >-
        If true, the API response will include a `Cache-Control` header with the value `public, max-age=0`. If included, this parameter **must** follow one of the other parameters.
      required: false
      style: form
      schema:
        type: boolean
        default: false
    Resize:
      name: resize
      explode: true
      in: query
      description: >-
        Resize width and height in the format widthxheight (example: 300x200)
      required: false
      style: form
      schema:
        type: string
    # Width:
    #   name: width
    #   explode: true
    #   in: query
    #   description: >-
    #     Will resize the image to the width specified. **Must** be used with the `height` parameter.
    #   required: false
    #   style: form
    #   schema:
    #     type: integer
    # Height:
    #   name: height
    #   explode: true
    #   in: query
    #   description: >-
    #     Will resize the image to the height specified. **Must** be used with the `width` parameter.
    #   required: false
    #   style: form
    #   schema:
    #     type: integer
    Rotate:
      name: rotate
      explode: true
      in: query
      description: Rotate image the specified degrees - note that you can use any combination of the 3 parameters together
      required: false
      style: form
      schema:
        type: string
    Watermark:
      name: rotate
      explode: true
      in: query
      description: Add a play button watermark
      required: false
      style: form
      schema:
        type: boolean
paths:
  /image/v1/{{account_id}}/{image-token}/url/{imageURL}:
    parameters:
      - $ref: "#/components/parameters/AccountId"
      - $ref: "#/components/parameters/ImageToken"
      - $ref: "#/components/parameters/ImageURL"
      - $ref: "#/components/parameters/Resize"
      - $ref: "#/components/parameters/Crop"
      - $ref: "#/components/parameters/Rotate"
      # - $ref: "#/components/parameters/Width"
      # - $ref: "#/components/parameters/Height"
      - $ref: "#/components/parameters/Fallback"
      - $ref: "#/components/parameters/FillArea"
      - $ref: "#/components/parameters/Watermark"
      - $ref: "#/components/parameters/Nocache"
    get:
      summary: Get a specific Image with the specified transformations
      operationId: TransformCustomImage
      tags:
        - Custom Image transformations
      responses:
        "200":
          description: Expected response to a valid request
          content:
            image/*:
              example: '(Returns the image file)'
        "404":
          description: Image not found or unsupported image type
          content:
            application/json:
              example:
                {
                  "error":"Unexpected response code while fetching image"
                }
        "500":
          description: Internal Server Error
          content:
            application/json:
              example:
                {
                  "error":"Unexpected error"
                }
