openapi: 3.0.1
info:
  title: Vision Check API
  summary: >-
    <b>An API for checking the context and authenticity of visual assets and
    managing those visionAnalyses</b>
  description: >-
    The Compass Vision API provides users with an endpoint to analyze an image
    by submitting its URL, returning a confidence score indicating whether the
    image is a deep fake or AI-generated. Upon submitting the image URL, the API
    processes it using advanced AI detection algorithms to evaluate features
    commonly associated with manipulated or synthetically generated visuals. 


    The response will include a confidence score, where a higher score indicates
    a higher likelihood that the image is a deep fake or AI-generated. This API
    is ideal for use in content moderation, authenticity verification, and media
    analysis tools.


    You can try these out in your browser with the [OpenAPI
    Spec](https://api.blackbird.ai/compass/openapi/#/VisionAnalyses). Be sure to
    hit "Authorize 🔓" and enter your credentials first.
servers:
  - url: https://api.blackbird.ai/compass
x-hideTryItPanel: false
x-codeSamples: true
paths:
  /visionAnalyses:
    post:
      summary: Create a new vision analysis
      description: >-
        Creates a new vision analysis. The resource isn't fully created
        immediately and you'll want to poll the `/visionAnalyses/{id}` GET for
        the result.
      operationId: createVisionAnalysis
      parameters:
        - name: cache-control
          in: header
          required: false
          description: >-
            Whether to bypass the cached response. Requires permission to bypass
            the cache.
          schema:
            type: string
            enum:
              - no-cache
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVisionAnalysisRequest'
      responses:
        '200':
          description: Vision analysis accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessingVisionAnalysis'
    get:
      summary: Gets all the vision analyses the caller has submitted.
      description: >-
        Note that the result is eventually consistent with creation of a
        visionAnalysis, so you might not read your own write when you query for
        all visionAnalyses
      operationId: getVisionAnalyses
      parameters:
        - name: start
          in: query
          required: false
          allowReserved: true
          schema:
            type: string
            format: date-time
          description: >-
            Filter vision analyses created after this date (inclusive with
            ascending sort order, exlusive with descending sort order)
        - name: end
          in: query
          required: false
          allowReserved: true
          schema:
            type: string
            format: date-time
          description: >-
            Filter vision analyses created before this date (exclusive with
            ascending sort order, inclusive with descending sort order)
        - name: offsetKey
          in: query
          required: false
          allowReserved: true
          schema:
            type: string
          description: >-
            The identifier for the offset to start at. Use the nextOffsetKey
            from the prior page to get the next page.
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: The direction to sort vision analyses by created_at
      responses:
        '200':
          description: Vision Analyses found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisionAnalysesQueryResponse'
  /visionAnalyses/{id}:
    get:
      summary: Get input and analysis
      description: >-
        Retrieves the vision analysis with the input and the generated analysis
        around it
      operationId: getVisionAnalysis
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The ID of the vision analysis to retrieve.
          example: 914e5150-7a8c-40a7-b0d9-4738e9d31f9e
      responses:
        '200':
          description: Vision Analysis found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisionAnalysis'
        '404':
          description: Vision Analysis not found
components:
  securitySchemes:
    oAuth2Password:
      type: oauth2
      flows:
        password:
          tokenUrl: https://api.blackbird.ai/compass/token
          scopes: {}
    clientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.blackbird.ai/auth/oauth2/token
          scopes: {}
  schemas:
    VisualizationType:
      type: string
      enum:
        - heatmap
        - bounding_box
      description: The type of annotation to apply to the frames of the video.
    VisionAnalysisOptions:
      type: object
      required:
        - explain
      additionalProperties: false
      properties:
        explain:
          type: boolean
          description: >-
            Whether to explain the vision analysis result when there is anything
            worth explaining or not.
          default: false
        isVideo:
          type: boolean
          description: >-
            Whether to use video analysis, requires an additional permission and
            is rate limited separately
          default: false
        needFramesAnnotation:
          type: boolean
          description: >-
            Whether to annotate the frames of the video with a heatmap or
            bounding box.
          default: false
        framesAnnotationType:
          type: array
          description: >-
            The type of annotation to apply to the frames of the video. Only one
            value is supported at a time.
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/VisualizationType'
    BaseVisionAnalysis:
      type: object
      required:
        - id
        - created_at
        - updated_at
        - status
        - input
        - options
      properties:
        id:
          type: string
          description: The ID of the vision analysis
          example: 7bf34023-641f-4191-a836-8cd4716266f3
        created_at:
          type: string
          format: date-time
          description: The datetime the vision analysis was created
        updated_at:
          type: string
          format: date-time
          description: The datetime the vision analysis was last updated.
        input:
          type: string
          format: url
          description: The input to generate a vision analysis of
        options:
          $ref: '#/components/schemas/VisionAnalysisOptions'
        status:
          type: string
          description: The status of the vision analysis generation
    ProcessingVisionAnalysis:
      allOf:
        - $ref: '#/components/schemas/BaseVisionAnalysis'
        - type: object
          properties:
            status:
              type: string
              enum:
                - processing
          example:
            id: 7bf34023-641f-4191-a836-8cd4716266f3
            input: >-
              https://blackbird.ai/wp-content/uploads/2024/09/GU-BlknW0AA78y0-1.jpeg
            options:
              explain: true
              needFramesAnnotation: true
              framesAnnotationType:
                - heatmap
            created_at: '2024-10-10T13:01:29.822Z'
            updated_at: '2024-10-10T13:01:29.822Z'
            status: processing
    VisionAnalysisData:
      type: object
      required:
        - fake
      properties:
        fake:
          type: object
          description: >-
            The analysis of whether the content is fake and why it is determined
            to be/not-be fake
          required:
            - confidence
            - isFake
          properties:
            confidence:
              type: number
              description: >-
                Represents the model's certainty about the classification
                expressed as a value between 0.5 and 1, where a higher value
                indicates higher confidence
            isFake:
              type: boolean
              description: Whether the content is fake or not.
            explanation:
              type: string
              description: >-
                Why the content is considered fake. Only returned if the content
                was determined to be fake
            annotations:
              type: object
              description: >-
                The annotations of the content. Only returned if the content was
                determined to be fake
              properties:
                url:
                  type: string
                  description: The URL of the annotation
                format:
                  type: string
                  enum:
                    - jpeg
                    - mp4
                  description: The format of the annotation
                type:
                  type: string
                  enum:
                    - video
                  description: The type of the annotation
                height:
                  type: number
                  description: The height of the annotation
                width:
                  type: number
                  description: The width of the annotation
    SuccessfulVisionAnalysis:
      allOf:
        - $ref: '#/components/schemas/BaseVisionAnalysis'
        - type: object
          required:
            - analysis
          properties:
            status:
              type: string
              enum:
                - success
            analysis:
              $ref: '#/components/schemas/VisionAnalysisData'
          example:
            updated_at: '2024-10-10T13:01:32.890Z'
            created_at: '2024-10-10T13:01:29.822Z'
            status: success
            input: https://x.com/i/status/1868091847064932761
            options:
              explain: true
              needFramesAnnotation: true
              framesAnnotationType:
                - heatmap
            id: 7bf34023-641f-4191-a836-8cd4716266f3
            analysis:
              fake:
                isFake: true
                confidence: 1
                explanation: >-
                  The image appears to show signs of being manipulated. The
                  lighting on the face and surrounding elements lacks
                  consistency, suggesting artificial enhancement. The
                  reflections on the laptop screen are unusually sharp and do
                  not match the soft ambient light from the room. Additionally,
                  the smoothness of the model's skin appears overly perfected,
                  which is an indicator of potential digital alteration. The
                  presence of the stickers on the laptop lacks natural wear,
                  which can further suggest artificiality, reinforcing the
                  classification as a fake.
                annotations:
                  - url: >-
                      https://compass-vision-uploads.s3.us-west-2.amazonaws.com/hybrid_deepfake_video_annotation/39e0cd4f-e9e1-4d1c-94e9-6bafc3054a6f.mp4?AWSAccessKeyId=ASIA5SOOCSZGWOMA3HRE&Signature=v%2FaY%2BFreqi7Orx%2F56ToQYD8v7VU%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEG0aCXVzLXdlc3QtMiJHMEUCIBwB4bJO8Xf2MrdleRmSLr%2FtA%2BMEAQS84EyhxNMgfObaAiEAunh1iFTqbnzjpNrWFa2WVTV6CSlMV75uGV38IUb6GTgqrQIIRhADGgw5MzI5NzY5NTcwMDUiDK2VWa39Mw0m8BugSSqKAuUTyrLLpLFNHLiGPg8SVF6RjRmfagP6G48zrOKALGx0oWoJAltJo7FyRnzYSab5ntxuZzpZen50htUCKOGgv0TXlVGbCyCP%2FwWqniOgpkgbaZqU2tOHzw%2Fwwej8niGM6eXVAMGm3kcyDSJahaP5YLLkbDGAlAW0%2FMoQ415QtmLpPmC1G%2FngMTmlNiDSfrBFX384d2vhkRFa2FelXBQ9kRrNo49CWp2ad6FeIgUxHetsvLVFDQpMO%2FmJrWFHHZN9uhKpsfjl%2B%2B4Wx1D0%2BHHyrsE%2FszZeZSdM%2FdPtNfxsbWSk63F1rSCb5iIgMzQRbLREs1LzO94XwikYKYHc6%2FoXX1MTQB5%2BMFZAI%2BuuMJ2uhsIGOp0B1IUz8wTP8c8sTN%2B%2FNS5cbPN5XmHS3V4S5WUllmvGwUxoDvdh%2BD%2BlFiBkzwET3iWSJ0N%2Btc4IGou6WifusWQffKCN%2BTSICGJ0FzIUWkJTrTCwL3Kxv1DUaqrQECNg37LnrTX%2BETvSMDK12a62gB%2FDYrQ7j2s0zJMjMCR%2BB%2FPXLufDGRpcYj9nNxLMiDEn9NK%2B1NYr3IywQXFqSXUbmw%3D%3D&Expires=1749217063
                    format: jpeg
                    type: image
                    height: 1000
                    width: 1000
    FailureVisionAnalysis:
      allOf:
        - $ref: '#/components/schemas/BaseVisionAnalysis'
        - type: object
          required:
            - error
          properties:
            status:
              type: string
              enum:
                - failed
            errorCode:
              type: string
              enum:
                - invalidInput
                - invalidContent
                - corruptContent
                - unsupportedFileType
                - unableToRetrieveData
                - serverError
              description: >
                The codified reason the request couldn't be completed: 

                - invalidInput: The input was not a resolvable URL

                - invalidContent: The content did not meet the required size,
                resolution, or color constraints

                - corruptContent: The content could not be parsed as it's
                specified filetype

                - unsupportedFileType: The URL is to a file type that is not
                supported

                - unableToRetrieveData: The URL did not return data in a timely
                fashion

                - serverError: An unexpected problem occurred. Check again
                later.
            error:
              type: string
              example: There was an error processing your vision analysis.
          example:
            id: 7bf34023-641f-4191-a836-8cd4716266f3
            input: https://example.com/not/an/image
            options:
              explain: true
            created_at: '2024-10-10T13:01:29.822Z'
            updated_at: '2024-10-10T13:01:29.822Z'
            status: failed
            error: Couldn't download image
    VisionAnalysis:
      oneOf:
        - $ref: '#/components/schemas/ProcessingVisionAnalysis'
        - $ref: '#/components/schemas/SuccessfulVisionAnalysis'
        - $ref: '#/components/schemas/FailureVisionAnalysis'
      discriminator:
        propertyName: status
        mapping:
          processing: '#/components/schemas/ProcessingVisionAnalysis'
          success: '#/components/schemas/SuccessfulVisionAnalysis'
          failed: '#/components/schemas/FailureVisionAnalysis'
    VisionAnalysesQueryResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VisionAnalysis'
        nextOffsetKey:
          type: string
          description: The offset key of the next page of data.
    CreateVisionAnalysisRequest:
      type: object
      required:
        - input
      additionalProperties: false
      properties:
        input:
          type: string
          format: url
          description: >-
            The input to generate a vision analysis of. Images must have a
            minumum width and height of 200px and maximum width and height of
            4000px. The following file formats are supported - PNG, JPEG, JPG,
            JPEG 2000, WebP, BMP, GIF, TIFF, TIF, DIB, ICO, EPS, PSD, PPM, PGM,
            PBM, PNM, TGA, XBM
          x-image-constraints:
            minWidth: 200
            minHeight: 200
            maxWidth: 4000
            maxHeight: 4000
            formats:
              - PNG
              - JPEG
              - JPG
              - JPEG 2000
              - WebP
              - BMP
              - GIF
              - TIFF
              - TIF
              - DIB
              - ICO
              - EPS
              - PSD
              - PPM
              - PGM
              - PBM
              - PNM
              - TGA
              - XBM
              - MP4
        options:
          $ref: '#/components/schemas/VisionAnalysisOptions'
      example:
        input: https://blackbird.ai/wp-content/uploads/2024/09/GU-BlknW0AA78y0-1.jpeg
        options:
          explain: true
          isVideo: false
          needFramesAnnotation: false
          framesAnnotationType:
            - heatmap
security:
  - clientCredentials: []
  - oAuth2Password: []
