CHOOCH API DOCUMENTATION

INTRODUCTION

The Chooch API is organized around REST. The API recognizes objects and concepts in videos and images from our pre-trained models.

The video API is compatible with livestreams and indexes every second of video content.

Image Recognition API

The image recognition API is a straight forward REST API which conducts classification and object recognition predictions on images. The image URL is passed as a field to the API and the API returns a JSON based response with the relevant predictions.

SAMPLE INPUT (IMAGE)

The following is a sample API request for image recognition.

http://api.chooch.ai/predict/image?url=http://s3.amazonaws.com/choochai/4202.jpg&predicttype=dense&apikey=
8gfyrzt1516653897h308348x725z

API input fields are:

  • url: URL of the image file. In this example it is http://s3.amazonaws.com/choochai/415.jpg
  • predicttype: Prediction type you want to make. There are two prediction types:
    1- “basic” and 2- “dense.” Basic retrieves general prediction results. Dense retrieves more detailed multilayer results when available.
  • apikey: API key provided by Chooch. In this example it is 8gfyrzt1516653897h308348x725z

SAMPLE OUTPUT (IMAGE)

The sample JSON response is:

{
  "status": "ok",
  "url": "http://s3.amazonaws.com/choochai/4202.jpg",
  "predictions": [
    {
      "class_title": "red dress",
      "order": "1"
    },
    {
      "class_title": "pink dress",
      "order": "2"
    },
    {
      "class_title": "sonia rykiel style",
      "order": "3"
    },
    {
      "class_title": "girl",
      "order": "4"
    }
  ],
  "predict_type": "dense",
  "objects": {
    "predictions": [
      {
        "sub_predictions": [
          {
            "class_title": "red dress",
            "order": 1
          }
        ],
        "object_title": "girl",
        "coordinates": "117,448,0,715"
      },
      {
        "sub_predictions": [
          {
            "class_title": "see by chloe style",
            "order": 1
          },
          {
            "class_title": "red dress",
            "order": 2
          }
        ],
        "object_title": "person",
        "coordinates": "132,434,13,781"
      },
      {
        "sub_predictions": [
          {
            "class_title": "kate spade style",
            "order": 1
          },
          {
            "class_title": "red dress",
            "order": 2
          },
          {
            "class_title": "olivia",
            "order": 3
          }
        ]
    ],
    "summary": [
      {
        "count": "2",
        "object_title": "footwear"
      },
      {
        "count": "1",
        "object_title": "dark red dress"
      },
      {
        "count": "1",
        "object_title": "face"
      },
      {
        "count": "1",
        "object_title": "hair"
      }
    ]
  },

  "fileid": "ec7995bb557d4416ab97b819917fc18c"
}

The response fields are:

  • url: URL of the image file posted
  • status: Status of the API request. When successful the status is “ok”. For error messages see last section.
  • predict_type: Prediction type, “basic” or “dense”.
  • predictions: Predictions made on the image. The predictions are provided as a list and have class_title and order fields. class_title is the name of the class predicted, and order is the order of relevancy of the particular class.
  • sub_predictions: Predictions made under dense classification. The image or frame is segmented into parts and classified based on the segments.
  • coordinates: Coordinates of the object based on pixels. The format for the coordinates are X1, X2, Y1, Y2.
  • count: The number of times an object or concept appears in an image or a frame.
  • fileid: Unique File ID created for the image. The File ID is to identify the image for future references.
    In this example it is ec7995bb557d4416ab97b819917fc18c

Video Recognition API

The video recognition API is a REST API which indexes videos second by second. The API consists of 2 parts: 1) send video and 2) search. The indexing begins by sending the video. After sending the video, the indexed data can be viewed through the search API.

SAMPLE INPUT (VIDEO)

The following is a sample send video URL for indexing to begin:

https://api.chooch.ai/predict/video?url=http://s3.amazonaws.com/choochai/2113.mp4&apikey=6werc43-1675-6553-8105-951rzn56

API input fields are:

  • url: URL of the video file. In this example it is http://s3.amazonaws.com/choochai/2113.mp4
  • apikey: API key provided by Chooch. In this example it is 6werc43-1675-6553-8105-951rzn56

SAMPLE OUTPUT (VIDEO)

The sample JSON response is:

{
    "status": "ok",
    "url": "https://s3.amazonaws.com/choochai/video-1530455600.mp4",
    "seconds": [
        {
        "second": 1,
        "objects": {
            "predictions": [
            {
                "sub_predictions": [
                {
                    "class_title": "tablet computer",
                    "order": 1
                },
                {
                    "class_title": "high-definition television, hdtv",
                    "order": 2
                },
                {
                    "class_title": "liquid crystal display, lcd",
                    "order": 3
                }
                ],
                "object_title": "television",
                "coordinates": "60,643,469,954"
            },
            {
                "sub_predictions": [
                {
                    "class_title": "tablet computer",
                    "order": 1
                },
                {
                    "class_title": "high-definition television, hdtv",
                    "order": 2
                }
                ],
                "object_title": "computer monitor",
                "coordinates": "58,626,486,911"
            },
            {
                "sub_predictions": [
                {
                    "class_title": "laser printer",
                    "order": 1
                },
                {
                    "class_title": "high-definition television, hdtv",
                    "order": 2
                }
                ],
                "object_title": "home appliance",
                "coordinates": "154,566,802,1137"
            }
            ],
            "summary": [
            {
                "count": "1",
                "object_title": "computer monitor"
            },
            {
                "count": "1",
                "object_title": "television"
            },
            {
                "count": "1",
                "object_title": "home appliance"
            }
            ]
        },
        "predictions": [
            {
            "class_title": "high-definition television, hdtv",
            "order": "1"
            },
            {
            "class_title": "television",
            "order": "2"
            },
            {
            "class_title": "tablet computer",
            "order": "3"
            },
            {
            "class_title": "liquid crystal display, lcd",
            "order": "4"
            },
            {
            "class_title": "computer monitor",
            "order": "5"
            },
            {
            "class_title": "home appliance",
            "order": "6"
            },
            {
            "class_title": "laser printer",
            "order": "7"
            }
        ]
        },
        {
        "second": 2,
        "objects": {
            "predictions": [
            {
                "sub_predictions": [
                {
                    "class_title": "tablet computer",
                    "order": 1
                },
                {
                    "class_title": "high-definition television, hdtv",
                    "order": 2
                }
                ],
                "object_title": "television",
                "coordinates": "64,626,500,956"
            },
            {
                "sub_predictions": [
                {
                    "class_title": "tablet computer",
                    "order": 1
                },
                {
                    "class_title": "high-definition television, hdtv",
                    "order": 2
                }
                ],
                "object_title": "computer monitor",
                "coordinates": "61,626,497,916"
            },
            {
                "sub_predictions": [
                {
                    "class_title": "laser printer",
                    "order": 1
                },
                {
                    "class_title": "printer, office supply, machine",
                    "order": 2
                }
                ],
                "object_title": "home appliance",
                "coordinates": "144,570,819,1141"
            }
            ],
            "summary": [
            {
                "count": "1",
                "object_title": "computer monitor"
            },
            {
                "count": "1",
                "object_title": "television"
            },
            {
                "count": "1",
                "object_title": "home appliance"
            }
            ]
        },
        "predictions": [
            {
            "class_title": "high-definition television, hdtv",
            "order": "1"
            },
            {
            "class_title": "television",
            "order": "2"
            },
            {
            "class_title": "tablet computer",
            "order": "3"
            },
            {
            "class_title": "computer monitor",
            "order": "4"
            },
            {
            "class_title": "home appliance",
            "order": "5"
            },
            {
            "class_title": "laser printer",
            "order": "6"
            },
            {
            "class_title": "printer, office supply, machine",
            "order": "7"
            }
        ]
        },
        {
        "second": 3,
        "objects": {
            "predictions": [
            {
                "sub_predictions": [
                
                ],
                "object_title": "curtain",
                "coordinates": "32,699,40,767"
            },
            {
                "sub_predictions": [
                
                ],
                "object_title": "television",
                "coordinates": "250,718,672,1094"
            },
            {
                "sub_predictions": [
                
                ],
                "object_title": "computer monitor",
                "coordinates": "252,720,668,1083"
            }
            ],
            "summary": [
            {
                "count": "1",
                "object_title": "curtain"
            },
            {
                "count": "1",
                "object_title": "television"
            },
            {
                "count": "1",
                "object_title": "computer monitor"
            }
            ]
        },
        "predictions": [
            {
            "class_title": "high-definition television, hdtv",
            "order": "1"
            },
            {
            "class_title": "curtain",
            "order": "2"
            },
            {
            "class_title": "television",
            "order": "3"
            },
            {
            "class_title": "computer monitor",
            "order": "4"
            }
        ]
        }                                            
    ],
    "index_status": "Success (Video Has Been Indexed)",
    "fileid": "a47808dbf9f34928bc85a77fdb919557"
    }

The response fields are:

  • url: URL of the video file.
  • status: Status of the API request. When successful the status is “Success (Video is being indexed)”. For errors see last section.
  • predicttype: Predict type is video for videos.
  • sub_predictions: Predictions made under dense classification. The image or frame is segmented into parts and classified based on the segments.
  • coordinates: Coordinates of the object based on pixels. The format for the coordinates are X1, X2, Y1, Y2.
  • count: The number of times an object or concept appears in an image or a frame.
  • fileid: Unique File ID created for the video. The File ID is to identify the indexed video for future reference and searches within the video. In this example it is a47808dbf9f34928bc85a77fdb919557

VIEWING INDEXED VIDEO

After the video is indexed, the indexed data can be viewed through the search API by using the File ID of the video. The following is a sample API request URL for viewing indexed data.

https://api.chooch.ai/predict/search?fileid=4d67a288b10741fa91683d3529b44aa9&apikey=6werc43-1675-6553-8105-951rzn56

The response fields are:

  • apikey: : API key provided by Chooch. In this example it is 6werc43-1675-6553-8105-951rzn56
  • predicttype: Predict type is video for videos.
  • fileid: Unique File ID created for the video. The File ID is to identify the indexed video for future reference and searches within the video. In this example it is 4d67a288b10741fa91683d3529b44aa9

The sample JSON response is:

{
    status: "ok",
    url: "http://s3.amazonaws.com/choochai/2113.mp4",
    indexstatus: "Success (Video Has Been Indexed)",
    seconds: [{
            second: 1,
            predictions: [{
                    class_title: "football stadium",
                    order: "1"
                },
                {
                    class_title: "stadium, bowl, arena, sports stadium",
                    order: "2"
                }
            ]
        },
        {
            second: 2,
            predictions: [{
                    class_title: "football stadium",
                    order: "1"
                },
                {
                    class_title: "stadium, bowl, arena, sports stadium",
                    order: "2"
                }
            ]
        },
        {
            second: 3,
            predictions: [{
                    class_title: "football stadium",
                    order: "1"
                },
                {
                    class_title: "stadium, bowl, arena, sports stadium",
                    order: "2"
                }
            ]
        },
        {
            {
                second: 4,
                predictions: [{
                        class_title: "football stadium",
                        order: "1"
                    },
                    {
                        class_title: "stadium, bowl, arena, sports stadium",
                        order: "2"
                    }
                ]
            },
            {
                second: 5,
                predictions: [{
                        class_title: "football stadium",
                        order: "1"
                    },
                    {
                        class_title: "stadium, bowl, arena, sports stadium",
                        order: "2"
                    } {
                        class_title: "field game",
                        order: "3"
                    },
                    {
                        class_title: "press box",
                        order: "4"
                    }

                ]
            },
        ],
        fileid: "4d67a288b10741fa91683d3529b44aa8"
    }

The response fields are:

  • status: Status of the API request. When successful the status is “ok”. For errors see last section
  • url: URL of the video file.
  • indexstatus: Status of video index. When complete the status is "Success (Video Has Been Indexed)". For errors see next section.
  • seconds: Each second in the video is indexed. Each item is a second in the video and there are predictions for every second, similar to the image prediction API. Each item has a second and predictions field. Predictions for every second are listed in the predictions field with the class_title and order fields.

    GENERAL STATUS MESSAGES

  • ok
  • Error (Wrong Parameters)
  • Error (Invalid API Key)
  • Error (You Have Reached Your Trial API Call Limit)
  • Error (No File)

    VIDEO INDEX STATUS MESSAGES

  • Waiting to Be Processed
  • In Process Error Occurred (Not Valid Video File)
  • Error Occurred (Reached Your API Call Limit)
  • Success (Video Has Been Indexed)
hello@chooch.ai