调用 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 请求头是否为 |
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。