api-ninjas-com AI API

openapi: 3.2.0
info:
  title: Ninjas AI API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: AI
paths:
  /v1/embeddings:
    post:
      tags:
      - AI
      summary: Encode text to vector
      description: Encodes any given text into a 768-dimensional vector using state-of-the-art NLP machine learning models.
      operationId: encodeText
      security:
      - ApiKeyAuth: []
      requestBody:
        description: Text to be encoded
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingsOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingsOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingsOpenapi_ErrorResponse'
  /v1/facedetect:
    post:
      tags:
      - AI
      summary: Detect faces in an image
      description: Runs computer-vision face detection on an image supplied in the POST request body and returns the faces found. Takes no query parameters.
      operationId: detectFaces
      requestBody:
        description: Image file containing faces. Must be either JPEG or PNG format.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: Image file to be analyzed
              required:
              - image
      responses:
        '200':
          description: A list of detected faces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceDetectResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceDetectOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceDetectOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceDetectOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/imagetotext:
    post:
      tags:
      - AI
      summary: Extracts text from an image
      description: Given an input image, return all detected texts and their bounding boxes.
      operationId: extractTextFromImage
      security:
      - ApiKeyAuth: []
      requestBody:
        description: Image to extract text from
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageToTextRequest'
        required: true
      responses:
        '200':
          description: Successful response with extracted text data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageToTextResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageToTextOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageToTextOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageToTextOpenapi_ErrorResponse'
  /v1/objectdetection:
    post:
      summary: Detect objects in an image
      description: Detects and labels the objects present in an image using a neural network. The image is sent in the body of the POST request.
      operationId: detectObjects
      tags:
      - AI
      requestBody:
        description: Image file to be processed for object detection.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: Image file. Must be either JPEG or PNG format and smaller than 2000 by 2000.
              required:
              - image
      responses:
        '200':
          description: A list of detected objects with labels, confidence percentages, and bounding boxes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectDetectionResponse'
        '400':
          description: Bad Request - Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectDetectionOpenapi_ErrorResponse'
        '401':
          description: Unauthorized - API key missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectDetectionOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectDetectionOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/sentiment:
    get:
      tags:
      - AI
      summary: Analyzes the sentiment of the provided text
      description: Analyzes the sentiment of a piece of text and returns a sentiment result for it. Requires `text` of at most 2000 characters.
      operationId: analyzeSentiment
      parameters:
      - name: text
        in: query
        description: Query text for sentiment analysis. Maximum 2000 characters.
        required: true
        schema:
          type: string
          maxLength: 2000
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentimentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentimentOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentimentOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentimentOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    ObjectDetectionOpenapi_ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message describing the failure.
    FaceDetectOpenapi_ErrorResponse:
      type: object
      properties:
        message:
          type: string
    FaceDetectResponse:
      type: array
      items:
        type: object
        properties:
          x:
            type: integer
            format: int32
            description: The x-coordinate of the top-left corner of the bounding box.
          y:
            type: integer
            format: int32
            description: The y-coordinate of the top-left corner of the bounding box.
          width:
            type: integer
            format: int32
            description: Width of the bounding box in pixels.
          height:
            type: integer
            format: int32
            description: Height of the bounding box in pixels.
        required:
        - x
        - y
        - width
        - height
    ImageToTextOpenapi_ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing the failure.
    ImageToTextResponse:
      type: object
      properties:
        texts:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
                description: Extracted text from the image.
              boundingBox:
                type: array
                items:
                  type: integer
                description: Bounding box coordinates for the detected text.
          description: List of detected texts and their bounding boxes.
    ObjectDetectionResponse:
      type: array
      items:
        type: object
        properties:
          label:
            type: string
            description: The label of the detected object.
          confidence:
            type: string
            description: The confidence score of the detected object (between 0 and 1), returned as a string.
          bounding_box:
            type: object
            properties:
              x1:
                type: string
                description: X-coordinate of the top-left corner of the bounding box, returned as a string.
              y1:
                type: string
                description: Y-coordinate of the top-left corner of the bounding box, returned as a string.
              x2:
                type: string
                description: X-coordinate of the bottom-right corner of the bounding box, returned as a string.
              y2:
                type: string
                description: Y-coordinate of the bottom-right corner of the bounding box, returned as a string.
    SentimentResponse:
      type: object
      properties:
        score:
          type: number
          format: float
          description: Sentiment analysis score from -1 to 1. 1 is the most positive, -1 is the most negative, and 0 is neutral.
        text:
          type: string
          description: Text that was analyzed.
        sentiment:
          type: string
          description: Overall sentiment of the text. Possible values are POSITIVE, WEAK_POSITIVE, NEGATIVE, WEAK_NEGATIVE, and NEUTRAL.
          enum:
          - POSITIVE
          - WEAK_POSITIVE
          - NEGATIVE
          - WEAK_NEGATIVE
          - NEUTRAL
    EmbeddingsOpenapi_ErrorResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
    EmbeddingsResponse:
      type: object
      properties:
        embeddings:
          type: array
          items:
            type: number
          description: A 768-dimensional vector as an array that encodes the meaning of the input text.
    ImageToTextRequest:
      type: object
      properties:
        image:
          type: string
          format: binary
          description: Image file to extract text from. Must be either JPEG or PNG format.
      required:
      - image
    EmbeddingsRequest:
      type: object
      properties:
        text:
          type: string
          description: Query text to embed. Maximum 5000 characters.
          maxLength: 5000
      required:
      - text
    SentimentOpenapi_ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message detailing the cause of the error.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api