images-search

圖片搜尋

需要 API 金鑰：請至 https://api.search.brave.com 取得

方案：包含在 Search 方案中。詳見 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

快速開始 (cURL)

基本搜尋

curl -s "https://api.search.brave.com/res/v1/images/search?q=mountain+landscape" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

帶參數

curl -s "https://api.search.brave.com/res/v1/images/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=northern lights photography" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=20" \
  --data-urlencode "safesearch=strict"

端點

GET https://api.search.brave.com/res/v1/images/search

驗證方式：X-Subscription-Token: <API_KEY> 標頭

參數

參數	型別	必填	預設值	說明
q	string	是	-	搜尋查詢（1-400 字元，最多 50 個單字）
country	string	否	US	搜尋國家（2 字母國家代碼或 ALL）
search_lang	string	否	en	2 個以上字元的語言代碼
count	int	否	50	回傳結果數（1-200）
safesearch	string	否	strict	off 或 strict（圖片搜尋無 moderate 選項）
spellcheck	bool	否	true	自動修正查詢；修正後的查詢在 query.altered 中

回應格式

{
  "type": "images",
  "query": {
    "original": "mountain landscape",
    "altered": null,
    "spellcheck_off": false,
    "show_strict_warning": false
  },
  "results": [
    {
      "type": "image_result",
      "title": "Beautiful Mountain Landscape",
      "url": "https://example.com/mountain-photo",
      "source": "example.com",
      "page_fetched": "2025-09-15T10:30:00Z",
      "thumbnail": {
        "src": "https://imgs.search.brave.com/...",
        "width": 200,
        "height": 150
      },
      "properties": {
        "url": "https://example.com/images/mountain.jpg",
        "placeholder": "https://imgs.search.brave.com/placeholder/...",
        "width": 1920,
        "height": 1080
      },
      "meta_url": {
        "scheme": "https",
        "netloc": "example.com",
        "hostname": "example.com",
        "favicon": "https://imgs.search.brave.com/favicon/...",
        "path": "/mountain-photo"
      },
      "confidence": "high"
    }
  ],
  "extra": {
    "might_be_offensive": false
  }
}

回應欄位

欄位	型別	說明
type	string	永遠為 "images"
query.original	string	原始查詢
query.altered	string?	拼字檢查後的查詢（若無修正則為 null）
query.spellcheck_off	bool?	是否停用拼字檢查
query.show_strict_warning	bool?	若嚴格 SafeSearch 隱藏了相關結果則為 true
results[]	array	圖片結果清單
results[].type	string	永遠為 "image_result"
results[].title	string?	圖片標題
results[].url	string?	找到圖片的頁面網址
results[].source	string?	來源網域
results[].page_fetched	string?	最後爬取頁面的 ISO 日期時間
results[].thumbnail.src	string?	Brave 代理的縮圖網址（約 500px 寬）
results[].thumbnail.width	int?	縮圖寬度
results[].thumbnail.height	int?	縮圖高度
results[].properties.url	string?	原始全尺寸圖片網址
results[].properties.placeholder	string?	低解析度佔位圖網址（Brave 代理）
results[].properties.width	int?	原始圖片寬度（可能為 null）
results[].properties.height	int?	原始圖片高度（可能為 null）
results[].meta_url.scheme	string?	URL 協定
results[].meta_url.netloc	string?	網路位置
results[].meta_url.hostname	string?	小寫網域
results[].meta_url.favicon	string?	Favicon 網址
results[].meta_url.path	string?	URL 路徑
results[].confidence	string?	相關性：low、medium 或 high
extra.might_be_offensive	bool	結果是否可能包含冒犯性內容

使用案例

• 視覺內容探索：建立圖片庫、情緒板或視覺研究工具。使用 count=200 以獲得全面涵蓋。當需要圖片特定中繼資料（尺寸、縮圖）時，優先於 web-search。
• 內容豐富化：為文章或產生的內容加入相關圖片。使用 country 和 search_lang 來鎖定目標受眾的語言地區。
• 安全圖片檢索：預設 safesearch=strict 確保開箱即用的闔家適宜結果。僅有兩種模式（off/strict）— 與網頁/影片/新聞搜尋不同，沒有 moderate 選項。
• 大量批次檢索：每次請求最多 200 張圖片（網頁搜尋為 20 張，影片/新聞為 50 張）。適合大量圖片來源收集或視覺分析管線。

注意事項

• SafeSearch：圖片搜尋預設為 strict（比網頁搜尋更嚴格）
• 大量回傳：每次請求最多可回傳 200 筆結果
• 縮圖：由 Brave 代理以保護使用者隱私（寬度 500px）。使用 properties.url 取得原始全解析度圖片。
• 尺寸：部分圖片的 properties.width/height 可能遺失
• 佔位圖：properties.placeholder 是低解析度網址（非內嵌 base64），適合用於漸進式載入的 UX