pexels-media

Pexels 媒体素材获取

从 Pexels 获取高质量、免版税的图片和视频，用于设计、占位图或内容创作。

前提条件

此技能要求设置 PEXELS_API_KEY 环境变量。

# Check if API key is available
echo $PEXELS_API_KEY

如果尚未设置，请从 Pexels API 获取免费的 API 密钥。

API 基础 URL

• 图片：https://api.pexels.com/v1/
• 视频：https://api.pexels.com/videos/

身份验证

所有请求都需要 Authorization 标头：

curl -H "Authorization: $PEXELS_API_KEY" "https://api.pexels.com/v1/search?query=nature"

图片端点

搜索图片

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=QUERY&orientation=ORIENTATION&size=SIZE&color=COLOR&locale=LOCALE&page=PAGE&per_page=PER_PAGE"

参数：

参数	必填	可选值
query	是	搜索词
orientation	否	landscape、portrait、square
size	否	large（24MP）、medium（12MP）、small（4MP）
color	否	red、orange、yellow、green、turquoise、blue、violet、pink、brown、black、gray、white 或十六进制代码（例如 #ffffff）
locale	否	en-US、pt-BR、es-ES、de-DE、fr-FR、ja-JP、zh-CN、ko-KR 等
page	否	页码（默认值：1）
per_page	否	每页结果数（默认值：15，最大值：80）

精选图片

由 Pexels 团队精选的热门图片（每小时更新）：

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/curated?page=1&per_page=15"

按 ID 获取图片

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/photos/PHOTO_ID"

视频端点

搜索视频

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/search?query=QUERY&orientation=ORIENTATION&size=SIZE&min_width=MIN_WIDTH&min_height=MIN_HEIGHT&min_duration=MIN_DURATION&max_duration=MAX_DURATION&page=PAGE&per_page=PER_PAGE"

其他视频参数：

参数	描述
min_width	最小宽度（像素）
min_height	最小高度（像素）
min_duration	最短时长（秒）
max_duration	最长时长（秒）

热门视频

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/popular?min_width=1920&min_duration=10&max_duration=60&page=1&per_page=15"

按 ID 获取视频

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/videos/VIDEO_ID"

合集

精选合集

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/collections/featured?page=1&per_page=15"

合集媒体

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/collections/COLLECTION_ID?type=TYPE&page=1&per_page=15"

类型参数： photos、videos，或省略以获取两者。

可用图片尺寸

下载图片时，API 响应中提供以下尺寸：

键	描述
original	摄影师上传的原始尺寸
large2x	宽度 940px，高度加倍
large	宽度 940px
medium	高度 350px
small	高度 130px
portrait	宽度 800px，高度 1200px
landscape	宽度 1200px，高度 627px
tiny	宽度 280px，高度 200px

可用视频文件

响应中包含多个不同画质的视频文件：

画质	常见分辨率
hd	1280x720
sd	640x360
hls	自适应流媒体
不同规格	可提供时为 Full HD、4K

强制要求：附属元数据文件

重要要求： 每个已下载文件都必须创建一个附属元数据文件。

附属文件命名

对于下载的文件 mountain-sunset.jpg，创建 mountain-sunset.jpg.meta.json。

图片附属文件内容

{
  "source": "pexels",
  "type": "photo",
  "id": 12345,
  "url": "https://www.pexels.com/photo/12345/",
  "download_url": "https://images.pexels.com/photos/12345/pexels-photo-12345.jpeg",
  "downloaded_size": "large",
  "width": 1920,
  "height": 1080,
  "photographer": "John Doe",
  "photographer_url": "https://www.pexels.com/@johndoe",
  "photographer_id": 67890,
  "avg_color": "#7E5835",
  "alt": "Brown mountain during sunset",
  "license": "Pexels License - Free for personal and commercial use",
  "attribution": "Photo by John Doe on Pexels",
  "attribution_html": "<a href=\"https://www.pexels.com/photo/12345/\">Photo</a> by <a href=\"https://www.pexels.com/@johndoe\">John Doe</a> on <a href=\"https://www.pexels.com\">Pexels</a>",
  "downloaded_at": "2025-12-02T14:30:00Z",
  "api_response": {
    // Full original API response for this photo
  }
}

视频附属文件内容

{
  "source": "pexels",
  "type": "video",
  "id": 12345,
  "url": "https://www.pexels.com/video/12345/",
  "download_url": "https://videos.pexels.com/video-files/12345/...",
  "downloaded_quality": "hd",
  "width": 1920,
  "height": 1080,
  "duration": 30,
  "user": {
    "id": 67890,
    "name": "John Doe",
    "url": "https://www.pexels.com/@johndoe"
  },
  "video_files": [
    {
      "id": 1,
      "quality": "hd",
      "file_type": "video/mp4",
      "width": 1920,
      "height": 1080,
      "link": "https://..."
    }
  ],
  "video_pictures": [
    {
      "id": 1,
      "picture": "https://...",
      "nr": 0
    }
  ],
  "license": "Pexels License - Free for personal and commercial use",
  "attribution": "Video by John Doe on Pexels",
  "downloaded_at": "2025-12-02T14:30:00Z",
  "api_response": {
    // Full original API response for this video
  }
}

下载工作流

1. 搜索并选择

# Search for photos
RESPONSE=$(curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=office+workspace&orientation=landscape&per_page=5")

# Parse and display results
echo "$RESPONSE" | jq '.photos[] | {id, photographer, alt, url: .src.large}'

2. 下载并创建附属文件

# Get photo details
PHOTO_ID=12345
PHOTO_DATA=$(curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/photos/$PHOTO_ID")

# Extract download URL (choose size)
DOWNLOAD_URL=$(echo "$PHOTO_DATA" | jq -r '.src.large')
FILENAME="pexels-$PHOTO_ID-large.jpg"

# Download the image
curl -L -o "$FILENAME" "$DOWNLOAD_URL"

# Create sidecar metadata (MANDATORY)
echo "$PHOTO_DATA" | jq '{
  source: "pexels",
  type: "photo",
  id: .id,
  url: .url,
  download_url: .src.large,
  downloaded_size: "large",
  width: .width,
  height: .height,
  photographer: .photographer,
  photographer_url: .photographer_url,
  photographer_id: .photographer_id,
  avg_color: .avg_color,
  alt: .alt,
  license: "Pexels License - Free for personal and commercial use",
  attribution: ("Photo by " + .photographer + " on Pexels"),
  downloaded_at: (now | todate),
  api_response: .
}' > "$FILENAME.meta.json"

速率限制

• 默认值： 每小时 200 次请求，每月 20,000 次请求
• 检查响应标头以查看当前限制：
  • X-Ratelimit-Limit
  • X-Ratelimit-Remaining
  • X-Ratelimit-Reset

署名最佳实践

虽然 Pexels 许可协议未要求署名，但建议注明来源：

• 简洁格式：“Photo by [Photographer] on Pexels”
• 含链接：“Photo by Photographer on Pexels”
• **HTML：**使用附属文件中的 attribution_html

使用案例

UI 设计占位图

# Get 5 abstract/minimal images for placeholders
curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=minimal+abstract&orientation=square&size=small&per_page=5"

主视觉背景视频

# Find short, wide landscape videos
curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/search?query=nature+aerial&orientation=landscape&min_width=1920&min_duration=5&max_duration=15"

产品摄影背景

# Search for clean, neutral backgrounds
curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=white+background+texture&color=white&size=large"

检查清单

使用此技能时：

• 确认已设置 PEXELS_API_KEY
• 选择合适的端点（搜索、精选、热门、合集）
• 应用相关筛选条件（方向、尺寸、颜色、时长）
• 根据使用场景选择合适的分辨率
• 将文件下载到合适的位置
• 创建附属元数据文件（强制要求）
• 考虑在最终使用时注明来源

References

• Pexels API Documentation
• Pexels License
• Pexels API Help