audio_codebuddy/docs/pixabay-api-reference.md

Pixabay API 参考文档

翻译整理时间：2026-05-30

---

一、搜索图片

GET https://pixabay.com/api/

参数

参数	类型	必填	说明
key	string	✅	API Key
q	string		URL 编码的搜索词。不传则返回所有图片。不超过 100 字符。示例："yellow+flower"
lang	string		搜索语言。可选值：cs, da, de, en, es, fr, id, it, hu, nl, no, pl, pt, ro, sk, fi, sv, tr, vi, th, bg, ru, el, ja, ko, zh。默认 "en"
id	string		按 ID 获取特定图片
image_type	string		图片类型："all", "photo", "illustration", "vector"。默认 "all"
orientation	string		方向："all", "horizontal", "vertical"。默认 "all"
category	string		分类筛选。可选值：backgrounds, fashion, nature, science, education, feelings, health, people, religion, places, animals, industry, computer, food, sports, transportation, travel, buildings, business, music
min_width	int		最小宽度（px）。默认 0
min_height	int		最小高度（px）。默认 0
colors	string		颜色筛选，逗号分隔。可选值："grayscale", "transparent", "red", "orange", "yellow", "green", "turquoise", "blue", "lilac", "pink", "white", "gray", "black", "brown"
editors_choice	bool		仅精选图片："true", "false"。默认 "false"
safesearch	bool		安全搜索："true", "false"。默认 "false"
order	string		排序："popular", "latest"。默认 "popular"
page	int		页码。默认 1
per_page	int		每页数量：3 - 200。默认 20
callback	string		JSONP 回调函数名
pretty	bool		美化 JSON 输出："true", "false"。默认 "false"（生产环境不要用）

调用示例

https://pixabay.com/api/?key=YOUR_KEY&q=yellow+flowers&image_type=photo

响应

{
  "total": 4692,       // 总命中数
  "totalHits": 500,    // API 可访问的最大数量（默认最多500张）
  "hits": [
    {
      "id": 195893,
      "pageURL": "https://pixabay.com/en/blossom-bloom-flower-195893/",
      "type": "photo",
      "tags": "blossom, bloom, flower",
      "previewURL": "..._150.jpg",        // 150px 低分辨率预览
      "previewWidth": 150,
      "previewHeight": 84,
      "webformatURL": "..._640.jpg",      // 640px 中等尺寸（24小时有效）
      "webformatWidth": 640,
      "webformatHeight": 360,
      "largeImageURL": "..._1280.jpg",    // 1280px 大图
      "fullHDURL": "..._1920.jpg",        // 1920px 全高清（需要 full API access）
      "imageURL": "...jpg",               // 原始尺寸（需要 full API access）
      "imageWidth": 4000,
      "imageHeight": 2250,
      "imageSize": 4731420,
      "views": 7671,
      "downloads": 6439,
      "likes": 5,
      "comments": 2,
      "user_id": 48777,
      "user": "Josch13",
      "userImageURL": "..._250x250.jpg"
    }
  ]
}

注意：fullHDURL 和 imageURL 仅当账户获得 full API access 后才返回。

webformatURL 尺寸替换

webformatURL 中的 _640 可替换为：

• _180 → 180px 高
• _340 → 340px 高
• _960 → 960×720px 最大尺寸

---

二、搜索视频

GET https://pixabay.com/api/videos/

参数（与图片接口相同，但多了以下）

参数	类型	说明
video_type	string	视频类型："all", "film", "animation"。默认 "all"

⚠️ 不支持 image_type 参数，改用 video_type

调用示例

https://pixabay.com/api/videos/?key=YOUR_KEY&q=yellow+flowers

响应

{
  "total": 42,
  "totalHits": 42,
  "hits": [
    {
      "id": 125,
      "pageURL": "https://pixabay.com/videos/id-125/",
      "type": "film",
      "tags": "flowers, yellow, blossom",
      "duration": 12,
      "videos": {
        "large": {
          "url": "..._large.mp4",
          "width": 1920,      // 通常是 3840x2160，旧视频可能是 1920x1080
          "height": 1080,
          "size": 6615235,
          "thumbnail": "..._large.jpg"
        },
        "medium": {
          "url": "..._medium.mp4",
          "width": 1280,      // 通常是 1920x1080，旧视频 1280x720
          "height": 720,
          "size": 3562083,
          "thumbnail": "..._medium.jpg"
        },
        "small": {
          "url": "..._small.mp4",
          "width": 640,       // 通常是 1280x720，旧视频 960x540
          "height": 360,
          "size": 1030736,
          "thumbnail": "..._small.jpg"
        },
        "tiny": {
          "url": "..._tiny.mp4",
          "width": 480,       // 通常是 960x540，旧视频 640x360
          "height": 270,
          "size": 426799,
          "thumbnail": "..._tiny.jpg"
        }
      },
      "views": 4462,
      "downloads": 1464,
      "likes": 18,
      "comments": 0,
      "user_id": 1281706,
      "user": "Coverr-Free-Footage",
      "userImageURL": "..._250x250.png"
    }
  ]
}

视频格式说明

格式	典型分辨率	说明
large	3840×2160 (4K)	不一定所有视频都有，无则返回空 URL
medium	1920×1080 (1080p)	所有视频都有此格式，最可靠
small	1280×720 (720p)	所有视频都有
tiny	960×540	所有视频都有

下载提示：在 URL 后面加 ?download=1 参数可触发浏览器下载。

---

三、JavaScript 调用示例

var API_KEY = '56075876-e50393dbd0ed322a9fd293aec';
var URL = "https://pixabay.com/api/?key=" + API_KEY + "&q=" + encodeURIComponent('red roses');
$.getJSON(URL, function(data) {
  if (parseInt(data.totalHits) > 0)
    $.each(data.hits, function(i, hit) { console.log(hit.pageURL); });
  else
    console.log('No hits');
});

---

四、我们的使用策略

图片搜索优化

• ✅ 关键词自动转多候选查询（去停用词）
• ✅ 默认 safesearch=true 安全搜索
• ✅ 默认 image_type=photo 照片类型
• ✅ 本地缓存（同关键词只拉一次）

新增优化（2026-05-30）

• 🎬 视频搜索：searchVideos() 直接从 Pixabay 搜视频素材，比图片+Ken Burns 效果好
• 🏷️ 分类推断：LLM 关键词 → Pixabay category 自动映射，缩小搜索范围
• 📐 方向过滤：视频合成默认 orientation=horizontal 横屏素材
• ⭐ 精选优先：editors_choice=true 优先高质量素材
• 🆕 新鲜素材：order=latest 替代默认的 popular 排序