多模态搜索-信息查询服务(IQS)-阿里云帮助中心

本文介绍MultimodalSearch（多模态搜索）的接口参数以及使用方法

接口说明

MultimodalSearch致力于在检索效果、成本、时延等维度提供更好的服务能力。目前支持根据文本搜索图片相关信息

接口定义

请求参数

参数

类型

必填

默认值

描述

示例值

query

string

是

搜索问题。取值范围：1~50个字符。

重要

基于效果考虑，尽可能将query限制在30个字符以内，可以在调用接口前客户侧通过模型做Query改写；

狮子

advancedParams

map<string, string>

否

false

高级检索参数：

排除站点范围检索: key为excludeSites, value为以,分割的站点列表

{
    "excludeSites": "www.360doc.com,weibo.com"
}

返回参数

字段			类型	是否可空	字段说明	样例（Query: 狮子）
requestId			string	不可空	请求RequestId, 排查问题时可以提供此信息	35E5608A-A737-2038-****-D9D34C6BFD9E
imageItems[]	title		string	不可空	网站标题	狮子一生征战沙场,背后藏着无数生死搏斗的传奇
	hostPageUrl		string	不可空	图片来源网站链接	https://example.html
	imageUrl		string	不可空	图片链接	https://imageexample.html
	publishedTime		string	不可空	网页发布时间，ISO时间格式。	2024-12-18T22:24:24+08:00
	height		int32	不可空	图片高度	1330
	width		int32	不可空	图片宽度	1000
searchInformation	searchTime		int64	不可空	搜索耗时	1048
queryContext	originalQuery	query	string	不可空	原始请求：query	狮子

说明

服务端的超时时间为5秒

示例

请求参数(RequestBody)

{
  "query": "狮子",
  "advancedParams": {
    "excludeSites": "www.360doc.com,weibo.com"
  }
}

返回参数

{
    "requestId": "********",
    "imageItems": [
        {
            "title": "狮子一生征战沙场,背后藏着无数生死搏斗的传奇",
            "publishedTime": "2025-04-12T12:47:54+08:00",
            "imageUrl": "http://pic.rmb.bdstatic.com/bjh/bb9193e11fbc/250412/cb5ab496c1b690c6514da34db1ecabb6.jpeg?for=bg",
            "hostPageUrl": "https://quanmin.baidu.com/sv?source=share-h5&pd=qm_share_search&vid=4798422598618199036",
            "height": 1280,
            "width": 720
        },
        {
            "title": "狮子!福气顺着阳光来啦! 狮子!好事跟着暖风到啦! 草原",
            "publishedTime": "2025-09-27T03:25:26+08:00",
            "imageUrl": "http://b0.bdstatic.com/ugc/_aq4Eq8b3neWg7bUSTpRMAb2d849c9780458737158f6dec8dc4bef.jpg",
            "hostPageUrl": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_5267989015389343625",
            "height": 1232,
            "width": 928
        },
        {
            "title": "狮子真的那么臭吗?为啥成了十大最臭动物之一?究竟有多臭?",
            "publishedTime": "2025-10-25T22:17:00+08:00",
            "imageUrl": "http://q9.itc.cn/images01/20251021/2b6c94863d7a45929c8f67590a187329.jpeg",
            "hostPageUrl": "http://news.sohu.com/a/945934548_120545240",
            "height": 853,
            "width": 1280
        },
        {
            "title": "榜首狮子座 狮主!天大的喜信到啦! 光耀穹顶,欢腾满溢!整个狮耀原都沸",
            "publishedTime": "2025-10-05T09:30:43+08:00",
            "imageUrl": "http://pic.rmb.bdstatic.com/bjh/3f119887b814/251005/f0e1de6994276136c35f8763cd79a989.png",
            "hostPageUrl": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4244727221681996203",
            "height": 1121,
            "width": 934
        },
        {
            "title": "curation 146 / lions 狮子",
            "publishedTime": "2022-07-03T00:00:00+08:00",
            "imageUrl": "http://sns-img-qc.xhscdn.com/010273016jh26jo8ja7011bs4ue7rjcpzf?imageView2/2/w/1080/format/webp",
            "hostPageUrl": "http://www.xiaohongshu.com/discovery/item/62c1a8ad000000000102fff2",
            "height": 1441,
            "width": 1080
        },
        {
            "title": "这小狮子也太能闹腾了,快来管管!",
            "publishedTime": "2025-07-17T17:57:00+08:00",
            "imageUrl": "http://b0.bdstatic.com/ugc/Hs065dVoGvbUAK9o9yptiAa61f2cd1e32a33239e119b885321c017.jpg",
            "hostPageUrl": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4778610846744027573",
            "height": 1664,
            "width": 936
        },
        {
            "title": "道道全——你这只沉睡了三年的狮子,该醒了吗?!",
            "publishedTime": "2020-05-15T10:45:12+08:00",
            "imageUrl": "http://gbres.dfcfw.com/Files/picture/20200515/E22CB6AF03759A8791300FD476EE8D99_w1680h1050.jpg",
            "hostPageUrl": "http://guba.eastmoney.com/news,002852,930168103,4195112827546318.html",
            "height": 1050,
            "width": 1680
        },
        {
            "title": "狮子亚种差异与生存现状",
            "publishedTime": "2025-12-13T11:52:08+08:00",
            "imageUrl": "http://pic.rmb.bdstatic.com/bjh/other/7e5c29616163c88db19504ea7dffba39.png?for=bg",
            "hostPageUrl": "https://quanmin.baidu.com/sv?source=share-h5&pd=qm_share_search&vid=18144687723668657466",
            "height": 1664,
            "width": 928
        },
        {
            "title": "当落日把鬃毛镀成金,草原之王卸下了所有锋芒.他把狮群的威严藏进拥抱",
            "publishedTime": "2025-09-19T16:05:08+08:00",
            "imageUrl": "http://b0.bdstatic.com/ugc/creative_center/RNbRETUMRKSxdLMpdzvAjAb7ae17de83fff0353bfa3828051f53b5.jpg",
            "hostPageUrl": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4520815613738106269",
            "height": 2188,
            "width": 988
        },
        {
            "title": "这小狮子也太能闹腾了,快来管管!",
            "publishedTime": "2025-07-17T17:57:00+08:00",
            "imageUrl": "http://b0.bdstatic.com/ugc/Hs065dVoGvbUAK9o9yptiA3e638a890ea5ad2223fe6bc41cbb4821.jpg",
            "hostPageUrl": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4778610846744027573",
            "height": 1664,
            "width": 936
        },
        {
            "title": "狮子家族的温馨时刻,萌娃撒娇,老爸慈爱地看着,画面太有爱啦#ai创作大",
            "publishedTime": "2025-08-02T21:27:14+08:00",
            "imageUrl": "http://b0.bdstatic.com/ugc/Hs065dVoGvbUAK9o9yptiA986dd2160c75da1850b34393452b52ae.jpg",
            "hostPageUrl": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_3800333561420709257",
            "height": 1664,
            "width": 936
        },
        {
            "title": "关于饲养员戳狮子屁屁这件事情,野生动物零距离 动物园 雄狮",
            "publishedTime": "2025-08-27T00:00:00+08:00",
            "imageUrl": "http://q6.itc.cn/q_70/images03/20250827/b908b4f0e1234671a3327b5d325a030b.jpeg",
            "hostPageUrl": "http://www.sohu.com/a/928684234_100114195",
            "height": 1280,
            "width": 720
        },
        {
            "title": "高清图片,堆糖,美图壁纸兴趣社区",
            "publishedTime": "2023-12-24T03:23:39+08:00",
            "imageUrl": "http://c-ssl.dtstatic.com/uploads/item/202102/12/20210212165128_losrw.thumb.400_0.jpg",
            "hostPageUrl": "http://www.duitang.com/blogs/tag/?name=%CA%A8%D7%D3%B6%AF%CE%EF%CD%BC%C6%AC&start=144",
            "height": 711,
            "width": 400
        },
        {
            "title": "马赛马拉国家公园的狮子家族大揭秘!",
            "publishedTime": "2024-12-25T10:54:17+08:00",
            "imageUrl": "http://miaobi-lite.bj.bcebos.com/miaobi/5mao/b%275Lit5Lic6ZuE54uuXzE3MzM4NDY3MjUuMTgzMjY2Mg%3D%3D%27/0.png",
            "hostPageUrl": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4908065249726726296",
            "height": 1050,
            "width": 1621
        },
        {
            "title": "在感情里,狮子会不会不忠?这是一个小伙伴私信的问题,个人觉得比较有",
            "publishedTime": "2024-03-16T10:31:08+08:00",
            "imageUrl": "http://pic.rmb.bdstatic.com/bjh/240316/events/40074e13b9df1b66808a4b74c985e4902381.jpeg@h_1280",
            "hostPageUrl": "https://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4520288067222930888",
            "height": 1280,
            "width": 1778
        },
        {
            "title": "思维绘画周六下午蜡彩班4点50",
            "publishedTime": "2020-11-07T00:00:00+08:00",
            "imageUrl": "http://ss2.meipian.me/users/15565667/12a9d13824a1c862efac377825792599.jpg?meipian-raw/bucket/ivwen/key/dXNlcnMvMTU1NjU2NjcvMTJhOWQxMzgyNGExYzg2MmVmYWMzNzc4MjU3OTI1OTkuanBn/sign/5ff30d4d147e1d9192e168a902c52927.jpg",
            "hostPageUrl": "http://www.meipian.cn/38vc9yej",
            "height": 934,
            "width": 640
        },
        {
            "title": "雄狮互相调情",
            "publishedTime": "2026-01-01T20:12:31+08:00",
            "imageUrl": "http://i2.hdslb.com/bfs/archive/e251d2e1386aa0a84a4cf0b9e30168fa80d32a1d.jpg",
            "hostPageUrl": "http://www.bilibili.com/video/BV171vDBtEeA",
            "height": 1440,
            "width": 2560
        },
        {
            "title": "壁纸 稀树草原,狮子,动物 1920x1080 full hd 2k 高清壁纸, 图片, 照",
            "publishedTime": "2020-11-05T12:31:16+08:00",
            "imageUrl": "http://s2.best-wallpaper.net/wallpaper/iphone/1412/Savanna-lion-animals_iphone_640x960.jpg",
            "hostPageUrl": "http://cn.best-wallpaper.net/savanna-lion-animals_wallpapers.html",
            "height": 960,
            "width": 640
        },
        {
            "title": "黔灵山邋遢狮洗澡了,为何鬃毛依然蓬乱?如何解决\"脏脏\"狮子的发型问题",
            "publishedTime": "2025-12-26T19:17:10+08:00",
            "imageUrl": "http://i0.hdslb.com/bfs/archive/b9e47b113dae41d8589aceade346a5ee34bb0d3d.jpg",
            "hostPageUrl": "http://www.bilibili.com/video/BV1MdBYBBEke",
            "height": 1125,
            "width": 2000
        },
        {
            "title": "为什么生意越来越难做,破产的老板越来越多.道理很简单,草原上狮子越",
            "publishedTime": "2023-09-21T08:53:07+08:00",
            "imageUrl": "http://pic.rmb.bdstatic.com/bjh/114531eef1b85ed9aeb34acc4103d73f1885.jpeg@h_1280",
            "hostPageUrl": "https://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4712827839063249262",
            "height": 1280,
            "width": 1918
        }
    ],
    "searchInformation": {
        "searchTime": 808
    },
    "queryContext": {
        "originalQuery": {
            "query": "狮子"
        }
    }
}

错误码

Status	错误码	错误信息	处理方案
404	InvalidAccessKeyId.NotFound	Specified access key is not found.	检查并确保AccessKey/Secret正确。
403	Retrieval.NotActivate	Please activate AI search service	请下单或联系您的客户经理进行开通。
403	Retrieval.Arrears	Please recharge first.	账户金额不足，请充值
403	Retrieval.NotAuthorised	Please authorize the AliyunIQSFullAccess privilege to the sub-account.	子账号没有进行授权，参考创建RAM用户并授权
403	Retrieval.TestUserPeriodExpired	The test period has expired.	测试已到期（自下单后15天有效），可以联系阿里云客户经理转正式
429	Retrieval.Throttling.User	Request was denied due to user flow control.	超出限流规格，可联系阿里云客户经理进行升配
429	Retrieval.TestUserQueryPerDayExceeded	The query per day exceed the limit.	测试超出日限额（1000次/天），可以联系阿里云客户经理转正式

接口调用

SDK调用

使用阿里云AK/SK认证方式，并使用阿里云SDK发起接口调用

Python SDK

前提条件

您需要确保已安装Python3.8或以上版本。

安装SDK

pip3 install alibabacloud_iqs20241111==1.7.1

调用代码

同步调用

import os

from Tea.exceptions import TeaException
from alibabacloud_iqs20241111 import models
from alibabacloud_iqs20241111.client import Client
from alibabacloud_tea_openapi import models as open_api_models


class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> Client:
        config = open_api_models.Config(
            # TODO: 使用您的AK/SK进行替换(建议通过环境变量加载)
            access_key_id='$YOUR_ACCESS_KEY',
            access_key_secret='$YOUR_ACCESS_SECRET'
        )
        config.endpoint = f'iqs.cn-zhangjiakou.aliyuncs.com'
        return Client(config)

    @staticmethod
    def main() -> None:
        client = Sample.create_client()
        advancedParams = {
            "excludeSites": "www.360doc.com,weibo.com"
        }
        run_instances_request = models.MultimodalSearchRequest(
            body=models.MultimodalSearchBody(
                query='狮子',
                advanced_params=advancedParams
            )
        )
        try:
            response = client.multimodal_search(run_instances_request)
            print(
                f"api success, request_id:{response.body.request_id}, size :{len(response.body.image_items)}, server_cost:{response.body.search_information.search_time}")
            for index, item in enumerate(response.body.image_items):
                print(f"{index}. {'-' * 20}")
                print(f"title:{item.title}")
                print(f"image_url:{item.image_url}")
                print(f"host_page_url:{item.host_page_url}")
                print(f"published_time:{item.published_time}")
                print(f"width:{item.width}")
                print(f"height:{item.height}")

        except TeaException as e:
            code = e.code
            request_id = e.data.get("requestId")
            message = e.data.get("message")
            print(f"api exception, requestId:{request_id}, code:{code}, message:{message}")


if __name__ == '__main__':
    Sample.main()

异步调用

import os
import asyncio

from Tea.exceptions import TeaException
from alibabacloud_iqs20241111 import models
from alibabacloud_iqs20241111.client import Client
from alibabacloud_tea_openapi import models as open_api_models


class Sample:
    def __init__(self):
        pass

    def create_client(self) -> Client:
        config = open_api_models.Config(
            # TODO: 使用您的AK/SK进行替换(建议通过环境变量加载)
            access_key_id='$YOUR_ACCESS_KEY',
            access_key_secret='$YOUR_ACCESS_SECRET'
        )
        config.endpoint = f'iqs.cn-zhangjiakou.aliyuncs.com'
        return Client(config)

    async def main_async(self) -> None:
        client = self.create_client()
        advancedParams = {
            "excludeSites": "www.360doc.com,weibo.com"
        }
        run_instances_request = models.MultimodalSearchRequest(
            body=models.MultimodalSearchBody(
                query='狮子',
                advanced_params=advancedParams
            )
        )
        try:
            response = await client.multimodal_search_async(run_instances_request)
            print(
                f"api success, request_id:{response.body.request_id}, size :{len(response.body.image_items)}, server_cost:{response.body.search_information.search_time}")
            for index, item in enumerate(response.body.image_items):
                print(f"{index}. {'-' * 20}")
                print(f"title:{item.title}")
                print(f"image_url:{item.image_url}")
                print(f"host_page_url:{item.host_page_url}")
                print(f"published_time:{item.published_time}")
                print(f"width:{item.width}")
                print(f"height:{item.height}")

        except TeaException as e:
            code = e.code
            request_id = e.data.get("requestId")
            message = e.data.get("message")
            print(f"api exception, requestId:{request_id}, code:{code}, message:{message}")


if __name__ == '__main__':
    sample = Sample()
    asyncio.run(sample.main_async())

Java SDK

前提条件

已安装Java8或以上版本。

Maven依赖

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>iqs20241111</artifactId>
    <version>1.7.1</version>
</dependency>

调用代码

package com.aliyun.iqs.example;

import com.aliyun.iqs20241111.Client;
import com.aliyun.iqs20241111.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

import java.util.HashMap;
import java.util.Map;

public class MultimodalSearchExample {
    public static void main(String[] args) throws Exception {
        Client client = initClient();
        invoke(client, "狮子", "www.360doc.com,weibo.com");
    }

    private static Client initClient() throws Exception {
        // TODO: 使用您的AK/SK进行替换(建议通过环境变量加载)
        String accessKeyId = System.getenv("ACCESS_KEY");
        String accessKeySecret = System.getenv("ACCESS_SECRET");

        Config config = new Config()
            .setAccessKeyId(accessKeyId)
            .setAccessKeySecret(accessKeySecret);

        config.setEndpoint("iqs.cn-zhangjiakou.aliyuncs.com");
        return new Client(config);
    }

    private static void invoke(Client client, String query, String excludeSites) {

        MultimodalSearchBody input = new MultimodalSearchBody();
        input.setQuery(query);
        Map<String, String> advancedParams = new HashMap<>();
        advancedParams.put("excludeSites",excludeSites);
        input.setAdvancedParams(advancedParams);
        MultimodalSearchRequest request = new MultimodalSearchRequest().setBody(input);

        try {
            long start = System.currentTimeMillis();
            MultimodalSearchResponse response = client.multimodalSearch(request);
            MultimodalSearchOutput result = response.getBody();
            long end = System.currentTimeMillis() - start;
            System.out.println("cost:" + end + " requestId:" + result.getRequestId());
            printOutput(result);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static void printOutput(MultimodalSearchOutput output) {
        // 使用 GsonBuilder 创建带格式化的 Gson 实例
        Gson gson = new GsonBuilder()
            .setPrettyPrinting()
            .disableHtmlEscaping()
            .create();

        // 输出格式化的 JSON
        String prettyJson = gson.toJson(output);
        System.out.println(prettyJson);
    }
}

Go SDK

前提条件

Go 环境版本必须不低于 1.10.x

安装SDK

require (
  github.com/alibabacloud-go/iqs-20241111 v1.7.1
  github.com/alibabacloud-go/darabonba-openapi/v2 v2.0.10
)

调用代码

package main

import (
  "fmt"
  "log"

  openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
  iqs20241111 "github.com/alibabacloud-go/iqs-20241111/client"
  util "github.com/alibabacloud-go/tea-utils/v2/service"
  "github.com/alibabacloud-go/tea/tea"
)

const endpointURL = "iqs.cn-zhangjiakou.aliyuncs.com"

func createClient() (*iqs20241111.Client, error) {
  // TODO: 使用您的AK/SK进行替换
  accessKeyID := "YOUR_ACCESS_KEY"
  accessKeySecret := "YOUR_ACCESS_SECRET"

  if accessKeyID == "" || accessKeySecret == "" {
    return nil, fmt.Errorf("ACCESS_KEY or ACCESS_SECRET environment variable is not set")
  }

  config := &openapi.Config{
    AccessKeyId:     tea.String(accessKeyID),
    AccessKeySecret: tea.String(accessKeySecret),
    Endpoint:        tea.String(endpointURL),
  }

  return iqs20241111.NewClient(config)
}

func runGenericSearch(client *iqs20241111.Client) error {
  body := &iqs20241111.MultimodalSearchBody{
    Query: tea.String("狮子"),
  }
  request := &iqs20241111.MultimodalSearchRequest{
    body,
  }
  runtime := &util.RuntimeOptions{}

  resp, err := client.MultimodalSearchWithOptions(request, nil, runtime)
  if err != nil {
    return fmt.Errorf("multimodal search failed: %w", err)
  }

  fmt.Printf("[%s] response: %s\n", *resp.Body.RequestId, resp.Body)
  return nil
}

func main() {
  client, err := createClient()
  if err != nil {
    log.Fatalf("Failed to create client: %v", err)
  }

  if err := runGenericSearch(client); err != nil {
    log.Fatalf("Error running multimodal search: %v", err)
  }
}

HTTP调用

使用信息查询服务（IQS）产品的凭证（API-KEY）进行认证，并使用HTTP发起接口调用。创建并查看凭证，获取API-KEY。

curl  -X POST https://cloud-iqs.aliyuncs.com/search/multimodal \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "query": "狮子"
}'

重要

$API_KEY 替换为信息查询服务控制台中创建的API-KEY（创建并查看凭证），创建API-KEY需要等待5min生效。