Pixabay API
Search and retrieve royalty-free images and videos from Pixabay's library of over 4 million assets.
Configuration
The API key is stored in ~/.config/pixabay/api_key. To set up:
mkdir -p ~/.config/pixabay
echo "YOUR_API_KEY" > ~/.config/pixabay/api_key
Read the key with:
PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
Quick Start
Search Images
PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
curl -s "https://pixabay.com/api/?key=${PIXABAY_KEY}&q=yellow+flowers&image_type=photo" | jq
Search Videos
PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
curl -s "https://pixabay.com/api/videos/?key=${PIXABAY_KEY}&q=nature" | jq
Image Search Parameters
| Parameter |
Type |
Description |
key |
str |
Required. API key |
q |
str |
URL-encoded search term (max 100 chars). Example: yellow+flower |
lang |
str |
Language code: 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. Default: en |
id |
str |
Retrieve specific image by ID |
image_type |
str |
all, photo, illustration, vector. Default: all |
orientation |
str |
all, horizontal, vertical. Default: all |
category |
str |
backgrounds, fashion, nature, science, education, feelings, health, people, religion, places, animals, industry, computer, food, sports, transportation, travel, buildings, business, music |
min_width |
int |
Minimum width. Default: 0 |
min_height |
int |
Minimum height. Default: 0 |
colors |
str |
Comma-separated: grayscale, transparent, red, orange, yellow, green, turquoise, blue, lilac, pink, white, gray, black, brown |
editors_choice |
bool |
Editor's Choice only. Default: false |
safesearch |
bool |
Safe content only. Default: false |
order |
str |
popular or latest. Default: popular |
page |
int |
Page number. Default: 1 |
per_page |
int |
Results per page (3-200). Default: 20 |
Video Search Parameters
Same as images, except:
- Endpoint:
https://pixabay.com/api/videos/
- Use
video_type instead of image_type: all, film, animation
Response Structure
Image Response
{
"total": 4692,
"totalHits": 500,
"hits": [
{
"id": 195893,
"pageURL": "https://pixabay.com/en/blossom-bloom-flower-195893/",
"type": "photo",
"tags": "blossom, bloom, flower",
"previewURL": "https://cdn.pixabay.com/.../flower-195893_150.jpg",
"webformatURL": "https://pixabay.com/get/...640.jpg",
"largeImageURL": "https://pixabay.com/get/..._1280.jpg",
"imageWidth": 4000,
"imageHeight": 2250,
"views": 7671,
"downloads": 6439,
"likes": 5,
"user": "Josch13",
"userImageURL": "https://cdn.pixabay.com/user/.../250x250.jpg"
}
]
}
Video Response
{
"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, "height": 1080 },
"medium": { "url": "..._medium.mp4", "width": 1280, "height": 720 },
"small": { "url": "..._small.mp4", "width": 960, "height": 540 },
"tiny": { "url": "..._tiny.mp4", "width": 640, "height": 360 }
}
}
]
}
Image URL Sizes
Replace _640 in webformatURL to get other sizes:
_180 - 180px height_340 - 340px height_960 - max 960x720px
Rate Limits
- 100 requests per 60 seconds
- Results must be cached for 24 hours
- Check headers:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Usage Requirements
When displaying search results, credit Pixabay as the source. Hotlinking images is not allowed - download to local storage for use. Videos may be embedded directly.
Common Workflows
Download Best Image for a Query
PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
# Search and get the first result's large image URL
URL=$(curl -s "https://pixabay.com/api/?key=${PIXABAY_KEY}&q=mountain+sunset&image_type=photo&per_page=3" | jq -r '.hits[0].largeImageURL')
# Download it
curl -o mountain_sunset.jpg "$URL"
Browse Categories
To explore available content, search with category filter:
curl -s "https://pixabay.com/api/?key=${PIXABAY_KEY}&category=nature&editors_choice=true&per_page=5" | jq '.hits[] | {id, tags, previewURL}'
1---2name: pixabay3description: Search and download royalty-free images and videos from Pixabay. This skill should be used when the user needs stock photos, illustrations, vectors, or videos for projects. Supports filtering by type, category, color, orientation, and more.4---5
6# Pixabay API
7
8Search and retrieve royalty-free images and videos from Pixabay's library of over 4 million assets.
9
10## Configuration
11
12The API key is stored in `~/.config/pixabay/api_key`. To set up:
13
14```bash
15mkdir -p ~/.config/pixabay
16echo "YOUR_API_KEY" > ~/.config/pixabay/api_key
17```
18
19Read the key with:
20```bash
21PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
22```
23
24## Quick Start
25
26### Search Images
27
28```bash
29PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
30curl -s "https://pixabay.com/api/?key=${PIXABAY_KEY}&q=yellow+flowers&image_type=photo" | jq
31```
32
33### Search Videos
34
35```bash
36PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
37curl -s "https://pixabay.com/api/videos/?key=${PIXABAY_KEY}&q=nature" | jq
38```
39
40## Image Search Parameters
41
42| Parameter | Type | Description |
43|-----------|------|-------------|
44| `key` | str | **Required.** API key |
45| `q` | str | URL-encoded search term (max 100 chars). Example: `yellow+flower` |
46| `lang` | str | Language code: 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. Default: `en` |
47| `id` | str | Retrieve specific image by ID |
48| `image_type` | str | `all`, `photo`, `illustration`, `vector`. Default: `all` |
49| `orientation` | str | `all`, `horizontal`, `vertical`. Default: `all` |
50| `category` | str | backgrounds, fashion, nature, science, education, feelings, health, people, religion, places, animals, industry, computer, food, sports, transportation, travel, buildings, business, music |
51| `min_width` | int | Minimum width. Default: 0 |
52| `min_height` | int | Minimum height. Default: 0 |
53| `colors` | str | Comma-separated: grayscale, transparent, red, orange, yellow, green, turquoise, blue, lilac, pink, white, gray, black, brown |
54| `editors_choice` | bool | Editor's Choice only. Default: `false` |
55| `safesearch` | bool | Safe content only. Default: `false` |
56| `order` | str | `popular` or `latest`. Default: `popular` |
57| `page` | int | Page number. Default: 1 |
58| `per_page` | int | Results per page (3-200). Default: 20 |
59
60## Video Search Parameters
61
62Same as images, except:
63- Endpoint: `https://pixabay.com/api/videos/`
64- Use `video_type` instead of `image_type`: `all`, `film`, `animation`
65
66## Response Structure
67
68### Image Response
69
70```json
71{
72 "total": 4692,
73 "totalHits": 500,
74 "hits": [
75 {
76 "id": 195893,
77 "pageURL": "https://pixabay.com/en/blossom-bloom-flower-195893/",
78 "type": "photo",
79 "tags": "blossom, bloom, flower",
80 "previewURL": "https://cdn.pixabay.com/.../flower-195893_150.jpg",
81 "webformatURL": "https://pixabay.com/get/...640.jpg",
82 "largeImageURL": "https://pixabay.com/get/..._1280.jpg",
83 "imageWidth": 4000,
84 "imageHeight": 2250,
85 "views": 7671,
86 "downloads": 6439,
87 "likes": 5,
88 "user": "Josch13",
89 "userImageURL": "https://cdn.pixabay.com/user/.../250x250.jpg"
90 }
91 ]
92}
93```
94
95### Video Response
96
97```json
98{
99 "total": 42,
100 "totalHits": 42,
101 "hits": [
102 {
103 "id": 125,
104 "pageURL": "https://pixabay.com/videos/id-125/",
105 "type": "film",
106 "tags": "flowers, yellow, blossom",
107 "duration": 12,
108 "videos": {
109 "large": { "url": "..._large.mp4", "width": 1920, "height": 1080 },
110 "medium": { "url": "..._medium.mp4", "width": 1280, "height": 720 },
111 "small": { "url": "..._small.mp4", "width": 960, "height": 540 },
112 "tiny": { "url": "..._tiny.mp4", "width": 640, "height": 360 }
113 }
114 }
115 ]
116}
117```
118
119## Image URL Sizes
120
121Replace `_640` in `webformatURL` to get other sizes:
122- `_180` - 180px height
123- `_340` - 340px height
124- `_960` - max 960x720px
125
126## Rate Limits
127
128- 100 requests per 60 seconds
129- Results must be cached for 24 hours
130- Check headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
131
132## Usage Requirements
133
134When displaying search results, credit Pixabay as the source. Hotlinking images is not allowed - download to local storage for use. Videos may be embedded directly.
135
136## Common Workflows
137
138### Download Best Image for a Query
139
140```bash
141PIXABAY_KEY=$(cat ~/.config/pixabay/api_key)
142# Search and get the first result's large image URL
143URL=$(curl -s "https://pixabay.com/api/?key=${PIXABAY_KEY}&q=mountain+sunset&image_type=photo&per_page=3" | jq -r '.hits[0].largeImageURL')
144# Download it
145curl -o mountain_sunset.jpg "$URL"
146```
147
148### Browse Categories
149
150To explore available content, search with category filter:
151```bash
152curl -s "https://pixabay.com/api/?key=${PIXABAY_KEY}&category=nature&editors_choice=true&per_page=5" | jq '.hits[] | {id, tags, previewURL}'
153```
majiayu000