Pixabay Audio Skill

Search and download royalty-free music tracks and sound effects from the Pixabay API for video production. Free with API key.

When to Use

• Finding background music (BGM) for video projects
• Searching sound effects (SFX) for specific scenes
• Downloading royalty-free audio that matches a video mood/theme
• Building audio asset libraries for reusable production

Core Principles

1. Always use .env — load PIXABAY_API_KEY via python-dotenv
2. Cache results 24h — Pixabay requires caching; don't re-search the same query within 24h
3. Download to local — hotlinking Pixabay URLs is not allowed; always download files
4. Save to audio/ folder — store all downloaded audio in {project_folder}/audio/ for reusability
5. Rate limit — max 100 requests per 60 seconds per API key
6. Attribution — show Pixabay as source when displaying search results

Environment Setup

dotenv
1# .env
2PIXABAY_API_KEY=your_pixabay_key_here

Install Dependencies

bash
1pip install requests python-dotenv

API Reference

Search Music

GET https://pixabay.com/api/videos/?key={KEY}&q={query}

Note: Pixabay does not have a dedicated audio-only search endpoint. Use the videos endpoint filtered by music/SFX categories, or use the image endpoint with category=music for music-related content.

For actual audio/music downloads, Pixabay provides audio via their main website. The API approach below works with their search to find relevant content.

Search for Music/SFX via Pixabay API

python
1import requests
2from pathlib import Path
3from dotenv import load_dotenv
4import os
5
6load_dotenv()
7API_KEY = os.getenv("PIXABAY_API_KEY")
8if not API_KEY:
9    raise EnvironmentError("PIXABAY_API_KEY is not set in .env")
10
11def search_pixabay_videos(
12    query: str,
13    category: str = "music",
14    per_page: int = 5,
15    order: str = "popular",
16    lang: str = "en",
17) -> list[dict]:
18    """Search Pixabay for video/audio content."""
19    url = "https://pixabay.com/api/videos/"
20    params = {
21        "key": API_KEY,
22        "q": query,
23        "category": category,
24        "per_page": per_page,
25        "order": order,
26        "lang": lang,
27        "safesearch": "true",
28    }
29    resp = requests.get(url, params=params, timeout=30)
30    resp.raise_for_status()
31    data = resp.json()
32    return data.get("hits", [])

Download Audio/Video File

python
1def download_file(url: str, dest: Path) -> Path:
2    """Download a file from URL to local path."""
3    dest.parent.mkdir(parents=True, exist_ok=True)
4    if dest.exists():
5        print(f"Already exists: {dest}")
6        return dest
7    resp = requests.get(url, timeout=120)
8    resp.raise_for_status()
9    dest.write_bytes(resp.content)
10    print(f"Downloaded: {dest} ({len(resp.content) // 1024}KB)")
11    return dest

Search Images by Music Category (for finding audio-themed content)

python
1def search_pixabay_images(
2    query: str,
3    category: str = "music",
4    per_page: int = 5,
5) -> list[dict]:
6    url = "https://pixabay.com/api/"
7    params = {
8        "key": API_KEY,
9        "q": query,
10        "category": category,
11        "per_page": per_page,
12        "safesearch": "true",
13    }
14    resp = requests.get(url, params=params, timeout=30)
15    resp.raise_for_status()
16    return resp.json().get("hits", [])

Audio Selection Strategy for Video Production

When selecting BGM/SFX for a video, follow this decision tree:

BGM (Background Music) Selection

SFX (Sound Effects) Selection

Integration with Video Pipeline

Folder Structure

All downloaded audio goes into {project_folder}/audio/:

{project_folder}/
├── audio/
│   ├── bgm_cinematic_01.mp3       ← background music
│   ├── sfx_whoosh_01.mp3          ← sound effect
│   ├── sfx_impact_01.mp3
│   └── audio_manifest.json        ← tracks metadata & scene assignments
├── scene_1/
│   ├── audio_1.mp3                ← TTS narration (from edge-tts)
│   └── ...

Audio Manifest

Save download metadata to audio/audio_manifest.json for traceability:

json
1{
2  "bgm": [
3    {
4      "file": "bgm_cinematic_01.mp3",
5      "source": "pixabay",
6      "pixabay_id": 12345,
7      "query": "cinematic orchestral",
8      "duration": 120,
9      "assigned_to": "full_video"
10    }
11  ],
12  "sfx": [
13    {
14      "file": "sfx_whoosh_01.mp3",
15      "source": "pixabay",
16      "pixabay_id": 67890,
17      "query": "whoosh transition",
18      "assigned_to": ["scene_1", "scene_3"]
19    }
20  ]
21}

Rate Limit Headers

Error Reference

Important Notes

• Pixabay content is royalty-free under their Content License
• Always download files locally — hotlinking is not allowed
• Cache search results for 24 hours to comply with API terms
• Maximum 500 results per query; paginate if needed
• Show "Source: Pixabay" attribution when displaying results to users

Bundled Scripts

download_bgm.py — BGM search and download

Searches Pixabay with multiple mood-based queries, picks the best match, downloads the MP3 into the project's audio/ folder, and writes an audio_manifest.json for use by the video render pipeline.

Install deps:

bash
1pip install requests python-dotenv

Configure .env:

PIXABAY_API_KEY=your_key_here

Run directly (no editing needed):

bash
1# With default queries
2python .agents/skills/pixabay-audio/scripts/download_bgm.py output/20260411_funfact-planet-mars
3
4# With custom mood-based queries
5python .agents/skills/pixabay-audio/scripts/download_bgm.py output/20260411_funfact-planet-mars \
6  --queries "cinematic space documentary" "epic orchestral dramatic" "science documentary ambient"

CLI arguments:

Example queries by mood:

• Upbeat/fun: "upbeat happy pop" "cheerful background music"
• Nature/calm: "nature relaxing acoustic" "peaceful ambient"
• Dark/serious: "dark horror ambient" "tense thriller underscore"
• Cinematic: "cinematic orchestral" "epic dramatic background"

Outputs:

• audio/bgm.mp3 — downloaded BGM file
• audio/audio_manifest.json — metadata (title, source URL, duration, query used)

Manifest format:

json
1{
2  "bgm": { "file": "bgm.mp3", "title": "...", "source_url": "...", "query": "..." }
3}