多模态搜索API

更新时间:
复制 MD 格式

调用 MultimodalSearch 接口进行联网图片检索,根据文本查询返回图片及其来源网页信息。

一、接口说明

接口名称:MultimodalSearch

能力说明:MultimodalSearch 致力于在检索效果、成本、时延等维度提供更好的服务能力,目前支持根据文本搜索图片相关信息。返回结果包含图片链接、来源网页链接、标题、发布时间与图片尺寸,可直接供多模态模型或智能体消费。

通过请求参数 engineType 选择引擎类型,不同引擎对应不同信源与单价。

重要

本接口目前仅支持文搜图(以文本 query 检索图片),engineType 仅接受 MultimodalSpeed 与 MultimodalSpeedAdvanced 两个取值。传入非法取值将返回 HTTP 400。

说明

服务端超时时间为 5 秒。两个引擎的响应时延差异较大:MultimodalSpeed 通常在 300 毫秒内返回,MultimodalSpeedAdvanced 因需更多资源,耗时通常在 3 秒左右。使用增强搜索时,建议客户端读超时设置为 6 秒以上,避免客户端先于服务端超时。

二、接口定义

请求参数

参数

类型

必填

默认值

描述

示例值

query

string

是

-

搜索问题。取值范围:1~50 个字符。基于效果考虑,建议将 query 控制在 30 个字符以内,可在调用接口前由客户侧通过模型做 Query 改写。超过 50 个字符时服务端不会报错,但检索效果不做保证。

狮子

engineType

string

否

MultimodalSpeed

搜索的引擎类型。可选值:MultimodalSpeed(极速搜索);MultimodalSpeedAdvanced(增强搜索,多种数据源,搜索质量更佳)。传入其他取值将返回 HTTP 400。

MultimodalSpeedAdvanced

advancedParams

map<string, string>

否

-

高级检索参数,key 与 value 均为字符串。excludeSites:排除站点范围检索,value 为以英文逗号分割的域名列表;numResults:返回记录数上限,取值范围 1~30。

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

参数使用说明

  • numResults 是返回条数的上限,不是精确条数。 实际返回条数取决于该 query 可用的图片结果数量,通常少于 numResults。例如请求 numResults=30 时可能返回 28 条,请求 numResults=5 时可能返回 3 条。客户侧不应假定返回条数等于 numResults。

  • 不传 numResults 时返回条数不固定,由服务端根据结果可用性决定。若业务需要稳定的结果规模,请显式传入 numResults。

  • numResults 超出 1~30 范围时返回 HTTP 400,错误码为 Retrieval.InvalidSitesSize。

  • excludeSites 必须填写纯域名,不能带 http://、https:// 协议前缀或路径。 带协议前缀时该条排除规则会静默失效(接口仍返回 HTTP 200,但被排除的站点依然出现在结果中),此为最常见的接入错误。

  • excludeSites 支持父域名匹配:填写 baidu.com 可同时排除 mbd.baidu.com、quanmin.baidu.com 等子域名。

  • 排除站点会显著减少可用结果数量,excludeSites 与 numResults 同时使用时,实际返回条数可能小于 numResults。

返回参数

字段

类型

是否可空

字段说明

样例(Query:狮子)

requestId

string

不可空

请求 RequestId,排查问题时可以提供此信息

35E5608A-A737-2038-****-D9D34C6BFD9E

imageItems[]

array

不可空

图片结果列表,按相关性降序排列。无匹配结果时返回空数组 [],不会缺失该字段

-

imageItems[].title

string

不可空

图片来源网页的标题

狮子一生征战沙场,背后藏着无数生死搏斗的传奇

imageItems[].hostPageUrl

string

不可空

图片来源网页链接

https://www.example.com/news/12345.html

imageItems[].imageUrl

string

不可空

图片链接(第三方站点直链)

https://pic.example.com/2025/lion.jpeg

imageItems[].publishedTime

string

极速不可空,增强可空

网页发布时间,ISO 时间格式。engineType 为 MultimodalSpeedAdvanced 时,部分结果该字段返回 JSON null(非空字符串、非缺失字段),反序列化时需使用可空类型

2024-12-18T22:24:24+08:00

imageItems[].height

int32

不可空

图片高度,单位像素

1330

imageItems[].width

int32

不可空

图片宽度,单位像素

1000

searchInformation.searchTime

int64

不可空

搜索耗时,单位毫秒

1048

queryContext.originalQuery.query

string

不可空

原始请求:query

狮子

结果消费说明

  • 无结果场景:query 无匹配图片时,接口返回 HTTP 200,imageItems 为空数组,requestId、searchInformation、queryContext 字段正常返回。客户侧需处理空列表分支,不要将其视为调用失败。

  • imageUrl 为第三方站点的图片直链,服务端不做代理和转存。部分站点存在防盗链或图片已失效,直接访问可能返回 403 或 404。若业务需要稳定展示,建议客户侧对图片做转存或增加加载失败兜底。

  • 部分 imageUrl 与 hostPageUrl 返回 http 协议链接,在 HTTPS 页面中直接引用会触发混合内容拦截,需客户侧做协议升级或代理。

  • 同一次返回中可能出现来自同一网页的多张图片(title 与 hostPageUrl 相同、imageUrl 不同),如需按网页去重请在客户侧处理。

  • requestId 建议全量记录,排查问题时需提供该值。

三、示例

请求参数(RequestBody)

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

返回参数

{
  "requestId": "35E5608A-A737-2038-****-D9D34C6BFD9E",
  "imageItems": [
    {
      "title": "狮子一生征战沙场,背后藏着无数生死搏斗的传奇",
      "publishedTime": "2025-04-12T12:47:54+08:00",
      "imageUrl": "http://pic.example.com/bjh/250412/cb5ab496c1b690c6514da34db1ecabb6.jpeg",
      "hostPageUrl": "https://example.com/sv?vid=4798422598618199036",
      "height": 1280,
      "width": 720
    },
    {
      "title": "狮子亚种差异与生存现状",
      "publishedTime": "2025-12-13T11:52:08+08:00",
      "imageUrl": "http://pic.example.com/bjh/other/7e5c29616163c88db19504ea7dffba39.png",
      "hostPageUrl": "https://example.com/sv?vid=18144687723668657466",
      "height": 1664,
      "width": 928
    }
  ],
  "searchInformation": {
    "searchTime": 808
  },
  "queryContext": {
    "originalQuery": {
      "query": "狮子"
    }
  }
}
说明

上述返回示例为节选。实际返回条数由服务端根据可用结果决定,numResults 仅作为条数上限。

增强搜索返回片段(publishedTime 为 null)

engineType 传入 MultimodalSpeedAdvanced 时,部分结果的 publishedTime 为 JSON null:

{
  "requestId": "35E5608A-A737-2038-****-D9D34C6BFD9E",
  "imageItems": [
    {
      "title": "狮子亚种差异与生存现状",
      "publishedTime": null,
      "imageUrl": "https://pic.example.com/2025/lion-subspecies.png",
      "hostPageUrl": "https://www.example.com/wildlife/lion.html",
      "height": 522,
      "width": 770
    }
  ],
  "searchInformation": {
    "searchTime": 3424
  },
  "queryContext": {
    "originalQuery": {
      "query": "狮子"
    }
  }
}

无结果时的返回

query 无匹配图片时返回 HTTP 200,imageItems 为空数组:

{
  "requestId": "92d9fb66-382b-4a4d-9f6b-97fe2479ef31",

  "imageItems": [ ],

  "searchInformation": {
    "searchTime": 504
  },
  "queryContext": {
    "originalQuery": {
      "query": "无匹配结果的查询词"
    }
  }
}

四、接口调用

HTTP 调用

使用产品的凭证(API-KEY)进行认证。API-KEY 在控制台「创建、查看凭证 Key」中创建,创建后需等待约 5 分钟生效。

  • 请求方法:POST

  • 请求地址:https://cloud-iqs.aliyuncs.com/search/multimodal

  • 认证方式:请求头 Authorization: Bearer $API_KEY

  • 请求体:Content-Type: application/json

最简调用:

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

带全部可选参数的调用:

curl -X POST https://cloud-iqs.aliyuncs.com/search/multimodal \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "狮子",
    "engineType": "MultimodalSpeedAdvanced",
    "advancedParams": {
      "numResults": "20",
      "excludeSites": "www.360doc.com,weibo.com"
    }
  }'

HTTP 调用的错误响应结构

调用失败时返回非 200 状态码,响应体为 JSON,包含四个字段(errorCode 与 code、errorMessage 与 message 内容一致,为兼容不同版本客户端而重复返回):

{
  "errorCode": "Retrieval.InvalidAPIKey",
  "errorMessage": "Incorrect APIKey provided. You can find your api key at https://ipaas.console.aliyun.com/api-key",
  "code": "Retrieval.InvalidAPIKey",
  "message": "Incorrect APIKey provided. You can find your api key at https://ipaas.console.aliyun.com/api-key"
}
说明

请求体 JSON 格式非法或 engineType 取值不合法时,返回 HTTP 400,响应体可能为非 JSON 的文本内容。客户侧应先判断 HTTP 状态码,再解析响应体,避免在非 200 响应上直接反序列化导致异常。

SDK 调用

使用阿里云 AK/SK 认证方式,并使用阿里云 SDK 发起接口调用。服务接入点如下:

地域名称

地域 ID

公网接入地址

华北 3(张家口)

cn-zhangjiakou

iqs.cn-zhangjiakou.aliyuncs.com

Python SDK

前提条件:Python 3.8 或以上版本。安装 SDK:

pip3 install alibabacloud_iqs20241111==1.10.2

同步调用:

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

def create_client() -> Client:
    # 建议通过环境变量加载 AK/SK,避免硬编码
    config = open_api_models.Config(
        access_key_id='$YOUR_ACCESS_KEY',
        access_key_secret='$YOUR_ACCESS_SECRET'
    )
    config.endpoint = 'iqs.cn-zhangjiakou.aliyuncs.com'
    return Client(config)

def main() -> None:
    client = create_client()
    request = models.MultimodalSearchRequest(
        body=models.MultimodalSearchBody(
            query='狮子',
            advanced_params={
                "numResults": "20",
                "excludeSites": "www.360doc.com,weibo.com"
            }
        )
    )
    try:
        response = client.multimodal_search(request)
        print(f"request_id:{response.body.request_id}, "
              f"size:{len(response.body.image_items)}, "
              f"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}, height:{item.height}")
    except TeaException as e:
        print(f"api exception, requestId:{e.data.get('requestId')}, "
              f"code:{e.code}, message:{e.data.get('message')}")

if __name__ == '__main__':
    main()

异步调用:将 client.multimodal_search(request) 替换为 await client.multimodal_search_async(request),并在 asyncio.run() 中执行调用函数,其余代码一致。

SDK 字段命名对照

SDK 中的字段名与 HTTP 请求体的 JSON 字段名不同,从 HTTP 迁移到 SDK 时请按下表转换:

HTTP JSON 字段

Python SDK

Java / Go SDK

query

query

query / Query

engineType

engine_type

engineType / EngineType

advancedParams

advanced_params

advancedParams / AdvancedParams

imageItems

image_items

imageItems / ImageItems

hostPageUrl

host_page_url

hostPageUrl / HostPageUrl

publishedTime

published_time

publishedTime / PublishedTime

searchInformation.searchTime

search_information.search_time

searchInformation.searchTime

advancedParams 内部的 key(excludeSites、numResults)在所有语言中均保持驼峰原样,不做转换。

Java SDK

前提条件:Java 8 或以上版本。Maven 依赖:

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

调用代码:

package com.aliyun.iqs.example;

import com.aliyun.iqs20241111.Client;
import com.aliyun.iqs20241111.models.*;
import com.aliyun.teaopenapi.models.Config;

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 {
        // 建议通过环境变量加载 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);
        advancedParams.put("numResults", "20");
        input.setAdvancedParams(advancedParams);

        MultimodalSearchRequest request = new MultimodalSearchRequest().setBody(input);

        try {
            MultimodalSearchResponse response = client.multimodalSearch(request);
            MultimodalSearchOutput result = response.getBody();
            System.out.println("requestId:" + result.getRequestId());
            result.getImageItems().forEach(item -> System.out.println(
                item.getTitle() + " | " + item.getImageUrl() + " | " + item.getHostPageUrl()));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Go SDK

前提条件:Go 版本不低于 1.10.x。安装 SDK:

require (
  github.com/alibabacloud-go/iqs-20241111 v1.10.2
  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) {
  // 建议通过环境变量加载 AK/SK,避免硬编码
  accessKeyID := "YOUR_ACCESS_KEY"
  accessKeySecret := "YOUR_ACCESS_SECRET"

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

func runMultimodalSearch(client *iqs20241111.Client) error {
  body := &iqs20241111.MultimodalSearchBody{
    Query: tea.String("狮子"),
    AdvancedParams: map[string]interface{}{
      "numResults":   "20",
      "excludeSites": "www.360doc.com,weibo.com",
    },
  }
  request := &iqs20241111.MultimodalSearchRequest{Body: 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] items: %d\n", *resp.Body.RequestId, len(resp.Body.ImageItems))
  return nil
}

func main() {
  client, err := createClient()
  if err != nil {
    log.Fatalf("Failed to create client: %v", err)
  }
  if err := runMultimodalSearch(client); err != nil {
    log.Fatalf("Error running multimodal search: %v", err)
  }
}
说明
  • Go SDK 中 AdvancedParams 的类型为 map[string]interface{},但服务端按字符串解析,value 请统一传字符串(如 "numResults": "20")。

  • MCP / Skill 等其他接入方式,请参考「接入方式」章节

五、错误码

参数错误

以下错误在两种认证方式下均可能出现,需检查请求参数。

Status

错误码

错误信息

处理方案

400

MissingParameter

Required parameter 'query' is not found.

query 缺失或为空字符串,请传入 1~50 个字符的查询词。

400

Retrieval.InvalidSitesSize

The specified parameter numResults's size is not in range [1, 30]

advancedParams.numResults 超出 1~30 范围,请调整取值。

400

-

响应体为非 JSON 的文本内容

engineType 取值非法或请求体 JSON 格式错误。engineType 仅支持 MultimodalSpeed 与 MultimodalSpeedAdvanced。

认证与账号状态错误

Status

错误码

错误信息

适用认证方式

处理方案

403

Retrieval.InvalidAPIKey

Incorrect APIKey provided. You can find your api key at https://ipaas.console.aliyun.com/api-key

HTTP(API-KEY)

检查 Authorization 请求头是否为 Bearer $API_KEY 格式、API-KEY 是否正确。新建的 API-KEY 需等待约 5 分钟生效。

403

-

-

HTTP(API-KEY)

未携带 Authorization 请求头,请补充认证信息。

404

InvalidAccessKeyId.NotFound

Specified access key is not found.

SDK(AK/SK)

检查并确保 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.

SDK(AK/SK)

子账号没有进行授权,参考「创建 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 次/天),可联系阿里云客户经理转正式。

说明

HTTP 调用返回 404 且响应体为空时,请检查请求方法与路径:本接口仅支持对 https://cloud-iqs.aliyuncs.com/search/multimodal 发起 POST 请求,使用 GET 等其他方法将返回 404。