Unitary AI Detoxify API

openapi: 3.1.0
info:
  title: Unitary content classification API Authentication Detoxify API
  description: '

    This API is for classifying image and video files to detect various types of potentially harmful content.


    ## Before you start:

    - You will need an API key to access this API. Please email contact@unitary.ai to obtain one.

    - If using the webhooks function then a preshared secret will also be required.



    ## API Authentication


    All API requests (except to /authenticate) require a valid API token in the `Authorization` header.

    To obtain an API token you should POST to /authenticate with your API key.


    API Tokens will be valid for a period of time (default 24h) and should be re-used until they expire or are invalidated.

    Please note that the /authenticate endpoint is rate-limited and excessive requests will return errors.


    ## Submitting media for classification


    Unitary''s API accepts files for the image/video endpoints and free text on the detoxify endpoint.

    The files or texts are submitted to the aforementioned endpoints for asynchronous classification returning a `job_id`

    associated with each request.


    Media files can either be sent as multi-part form uploads, or preferably by including a `url` field in the request where the media file can be downloaded from. Presigned object-storage URLs are supported.


    ### Current limitations

    To ensure high quality and speed in our responses, we have a few limitations on the size and type of media we process. Please let us know if any of these limitations represent an issue for you. We are more than happy to reevaluate our solution to meet your needs.

    - The maximum allowed image size is 10 MB The maximum allowed video size is 200 MB. Requests made with media files larger than the limits specified may not be processed.

    - The image formats we support are .png and .jpeg

    - The video formats we support are .Mp4, Mpeg, Webm, Mov, Mkv, M4v


    ## Receiving classification results


    For receiving results we support multiple methods:


    - The preferred method is to utilise the webhook function by including a `callback_url` parameter in the classification request. Results will be delivered by a POST request to the `callback_url` as soon as the resource is classified.

    - Results can also be retrieved by polling the GET endpoints. This method may be inconvenient as processing can take multiple hours.


    '
  version: 1.0.0
tags:
- name: Detoxify
paths:
  /detoxify/text/:
    post:
      tags:
      - Detoxify
      summary: Queue text for Detoxify classification
      description: This endpoint predicts the Detoxify categories of text.
      operationId: text_detoxify_classify_detoxify_text__post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_text_detoxify_classify_detoxify_text__post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobIDResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - JWTBearer: []
  /detoxify/text/{job_id}:
    get:
      tags:
      - Detoxify
      summary: Retrieve the results of a queued Detoxify classification
      description: This endpoint returns the results of a previously queued classify job
      operationId: text_results_detoxify_text__job_id__get
      parameters:
      - required: true
        schema:
          type: string
          format: uuid4
          title: Job Id
        name: job_id
        in: path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse_DetoxifyResponse_'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - JWTBearer: []
components:
  schemas:
    DetoxifyResponse:
      properties:
        toxicity:
          type: number
          title: Toxicity
        severe_toxicity:
          type: number
          title: Severe Toxicity
        obscene:
          type: number
          title: Obscene
        threat:
          type: number
          title: Threat
        insult:
          type: number
          title: Insult
        identity_attack:
          type: number
          title: Identity Attack
        sexual_explicit:
          type: number
          title: Sexual Explicit
      type: object
      required:
      - toxicity
      - severe_toxicity
      - obscene
      - threat
      - insult
      - identity_attack
      - sexual_explicit
      title: DetoxifyResponse
    JobIDResponse:
      properties:
        job_id:
          type: string
          format: uuid4
          title: Job Id
      type: object
      required:
      - job_id
      title: JobIDResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AsyncResponse_DetoxifyResponse_:
      properties:
        status:
          allOf:
          - $ref: '#/components/schemas/AsyncResponseStatus'
          title: Status of classification job
        results:
          allOf:
          - $ref: '#/components/schemas/DetoxifyResponse'
          title: Classification results
        msg:
          type: string
          title: Error details
      type: object
      required:
      - status
      title: AsyncResponse[DetoxifyResponse]
    AsyncResponseStatus:
      enum:
      - done
      - failed
      - queued
      title: AsyncResponseStatus
      description: An enumeration.
    Body_text_detoxify_classify_detoxify_text__post:
      properties:
        callback_url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Webhooks callback URL
        text:
          type: string
          maxLength: 262144
          title: Text to classify (max 256kb)
        model:
          allOf:
          - $ref: '#/components/schemas/DetoxifyModel'
          title: Detoxify model type
          default: multilingual
        correlation_id:
          type: string
          maxLength: 128
          title: An optional id chosen by the user to correlate requests and responses
      type: object
      required:
      - text
      title: Body_text_detoxify_classify_detoxify_text__post
    DetoxifyModel:
      type: string
      enum:
      - multilingual
      title: DetoxifyModel
      description: An enumeration.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    JWTBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT