# 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
```

### 响应

```json
{
  "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
```

### 响应

```json
{
  "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 调用示例

```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 排序