> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 文搜图

文搜图接口根据文字描述检索相关图片，可用于内容自动配图等场景，图片数据来自百度搜图。该接口仅在 [Step Plan](https://platform.stepfun.com/docs/zh/step-plan/overview.md) 通道提供，按调用次数计费，具体价格见[计费详情](https://platform.stepfun.com/docs/zh/guides/pricing/details.md)。

> [!WARNING]
>
> 返回图片的版权归原站点所有，接口不进行版权检测或商用授权判断，请在使用前自行评估合规性。

## 请求地址

`POST https://api.stepfun.com/step_plan/v1/search-image`

## 请求参数

* `query` `string` ***required***\
  搜索词，建议使用中文，也支持英文。
* `topk` `int` ***optional***\
  返回图片张数的上限。

## 请求响应

* `code` `int`\
  状态码，`0` 表示成功。
* `msg` `string`\
  提示信息，成功时为空字符串。
* `data` `object`\
  返回数据。

  * `result` `object`\
    搜索结果。

    * `block` `bool`\
      是否命中审核拦截。`true` 表示命中拦截，此时 `search_results` 为空；`false` 表示未拦截。
    * `search_results` `object array`\
      图片结果列表，可能为空。

      * `contentUrl` `string`\
        原图地址。
      * `snippet` `string`\
        图片描述，可用作 alt 文本。
      * `width` `int`\
        原图宽度，单位为像素。
      * `height` `int`\
        原图高度，单位为像素。
      * `hostPageUrl` `string`\
        图片所在网页地址。
      * `hostname` `string`\
        图片来源域名。

## 示例

> [tab] cURL
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> curl --location 'https://api.stepfun.com/step_plan/v1/search-image' \
>     -H 'Content-Type: application/json' \
>     -H 'Authorization: Bearer $STEPFUN_API_KEY' \
>     -d '{
>         "query": "故宫",
>         "topk": 2
>     }'
> ```

> [tab] Python
>
> ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> import os
> import requests
>
> resp = requests.post(
>     "https://api.stepfun.com/step_plan/v1/search-image",
>     headers={
>         "Authorization": f"Bearer {os.environ['STEPFUN_API_KEY']}",
>         "Content-Type": "application/json",
>     },
>     json={"query": "故宫", "topk": 2},
> )
>
> result = resp.json()["data"]["result"]
> for item in result["search_results"]:
>     print(item["contentUrl"], item["snippet"])
> ```

返回示例：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "code": 0,
  "msg": "",
  "data": {
    "result": {
      "block": false,
      "search_results": [
        {
          "contentUrl": "http://q1.itc.cn/images01/20250921/4aefdeaeff0f4f2999ce3e959a902265.jpeg",
          "snippet": "故宫博物院,中国最大的古代文化艺术博物馆",
          "width": 5650,
          "height": 3687,
          "hostPageUrl": "http://travel.sohu.com/a/937199080_122365627",
          "hostname": "travel.sohu.com"
        },
        {
          "contentUrl": "http://q2.itc.cn/images01/20251010/bf333868e5e243a6808ad887067a7766.jpeg",
          "snippet": "北京故宫博物院今天过100岁生日",
          "width": 1920,
          "height": 1080,
          "hostPageUrl": "http://gov.sohu.com/a/942413642_120479584",
          "hostname": "gov.sohu.com"
        }
      ]
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.