AI Search API

Overview

The search API of the CleverSee AI Search and Q&A Platform enables precise retrieval of images, documents, and audio/video content from your datasets. After building a search application on the platform, you can call this API to perform searches. The platform supports queries using text (in natural language), images, or a combination of both, supporting multimodal data searches at scale and helping users efficiently locate content.

API

You can use this API with two types of search applications created on the CleverSee AI Search and Q&A Platform: image search applications and audio and video search applications. Image search supports text-to-image, image-to-image, and hybrid text-and-image queries. Audio and video search supports text-to-audio/video, image-to-video, and hybrid text-and-image queries for video.

Data sources

This API supports audio and video data, which can be uploaded and updated through the CleverSee AI Search and Q&A Platform UI or by using the Add/Update Dataset Data API.

Authentication method

Use the Alibaba Cloud SDK to call the CleverSee AI Search service. For detailed instructions, see AI Search Engine API.

Request parameters

Parameters

Request example

The following is a typical request example.

JSON format

curl -X POST 'https://aisearchengine.aliyuncs.com/api/v1/platform/app/search' \
  -H 'Content-Type: application/json' \
  -H "Date: $(LC_ALL=C date -u +'%a, %d %b %Y %H:%M:%S GMT')" \
  -H 'x-acs-apikey: ALS*****' \
  -d '{
    "appId": "your_app_id",
    "query": {
      "texts": ["a little girl"],
      "imageUrls": ["https://your-image-url.com/image.jpg"],
      "pageSize": 10,
      "pageNo": 1
    }
  }'

Response parameters

Top-level structure

3.2 items Element structure details

Each object in the items array represents a search result. The content field contains different attributes depending on the media type (image, video, or audio). The following describes the common structure and the fields that are specific to video and audio:

Image searchitems

Audio and video searchitems

Response examples

Image search example

JSON format

  {
    "code": 200,
    "message": "success",
    "data": {
      "size": 1,
      "page": 1,
      "total": 1,
      "traceInfo": null,
      "extra": {
        "exclude_ids": ["3f95b343xxxxxxxxxxxx"]
      },
      "items": [
        {
          "id": "3f95b343xxxxxxxxxxxx",
          "score": 0.8029279573006508,
          "content": {
            "s_name": "sample_image.png",
            "image_url": "https://.../image.png?Expires=...",
            "pk_id": "3f95b343xxxxxxxxxxxx",
            "s_dataset_id": "594"
          },
          "algorithm": {},
          "traceInfo": null
        }
      ],
      "status": "200",
      "errorMessage": null
    },
    "requestId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }

Video search example

JSON format

{
  "code": 200,
  "data": {
    "total": 1,
    "size": 1,
    "traceInfo": null,
    "extra": {
      "exclude_ids": ["01XXXXXXXXXXXXXXX"]
    },
    "errorMessage": null,
    "page": 1,
    "items": [{
      "score": 0.577594,
      "traceInfo": null,
      "id": "01XXXXXXXXXXXXXXX",
      "content": {
        "s_raw_file_path": "https://.../video.mp4?Expires=...",
        "s_raw_length": 1036122,
        "pk_id": "01XXXXXXXXXXXXXXX",
        "s_global_summary": "The first half of the video focuses on the conflicts and collaborations between characters, presenting complex relationships and emotional changes through multiple plot developments, including chases, dialogues, and investigations. The second half shifts to stage performance content, showing a singer's live performance and audience interaction at a large event. The overall content combines narrative storytelling with musical performance elements.",
        "s_raw_cover_pic": "https://.../frame_1.jpg?Expires=...",
        "s_name": "demo_video.mp4",
        "s_dataset_id": "833",
        "s_global_keywords": "Plot interaction, Character relationships, Investigation and chase, Musical performance, Stage singing",
        "s_video_topic": "Plot and musical performance",
        "s_video_type": "Film & TV/Variety Show"
      },
      "algorithm": {}
    }],
    "status": "200"
  },
  "requestId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "message": "success"
}

Error codes

Media resource URLs

To get presigned URLs for downloading media files (images or videos) from the search results, see the Get Presigned URLs for Media Resources in Search Results API.