pexels-stock-photos

Pexels Stock Photos

通过 Pexels API 搜索并下载免费图库照片（每小时 200 次请求，每月免费 20,000 次）。 所有内容均可免费用于商业和非商业用途，只需注明摄影师姓名并链接到 Pexels。

路由：Pexels 与 AI 生成

用户说……	工具
“找一张新加坡的照片” / “搜索办公室图片” / “一张桌子的图库图片”	Pexels（此技能）
“我需要一张真实照片用于这张幻灯片” / “为我的文章找些图片”	Pexels（此技能）
“生成一张猫的图片” / “创建一张……的图片” / “给我画一幅插图”	宿主的图像生成工具
“放大这张图” / “移除背景” / “编辑：调暖一些”	宿主的 AI 图像编辑技能
“可用于正式制作的主视觉图片” / “我们认真做好这件事”	宿主的多阶段图像生成技能

**关键词测试：**如果用户说 photo、picture、stock image 或 find/search → 使用 Pexels。如果用户说 generate、create、make、draw 或 illustration → 使用 AI 生成。

适用场景

• 用户要求“X 的照片”或“Y 的图库图片”
• 制作需要真实图像的演示文稿（PPTX）
• 为文章/博客配上真实照片
• 需要专业摄影作品的社交媒体帖子
• 任何要求使用“真实”图像而非 AI 生成图像的场景

不适用场景：

• AI 艺术作品 / 创意生成 → 使用宿主的图像生成工具
• 编辑现有图像 → 使用宿主的图像编辑技能
• 屏幕截图或示意图 → 使用适当的工具

API 参考

基础 URL：https://api.pexels.com/v1/ 身份验证：Authorization: <PEXELS_API_KEY> 请求头

端点

端点	方法	用途
/search	GET	按查询词搜索照片
/curated	GET	精选热门照片
/photos/:id	GET	按 ID 获取指定照片

搜索参数

参数	类型	默认值	说明
query	string	必填	例如："singapore skyline"
orientation	string	—	landscape、portrait、square
size	string	—	large（24MP）、medium（12MP）、small（4MP）
color	string	—	red、orange、blue、……或十六进制值 #ffffff
locale	string	en-US	zh-CN、ja-JP 等
per_page	int	15	最多 80
page	int	1	分页

照片资源 src 尺寸

尺寸	分辨率	用途
original	原始分辨率	打印、高画质
large2x	940×650 @2x	Retina 显示屏
large	940×650	网页、演示文稿
medium	高约 350px	缩略图、预览图
small	高约 130px	小尺寸缩略图
portrait	800×1200	竖版/移动设备
landscape	1200×627	幻灯片、社交媒体
tiny	280×200	占位图

工作流

1. 搜索照片

curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=singapore+skyline&per_page=5&orientation=landscape"

解析 JSON 响应，并向用户展示结果：照片 ID、摄影师、替代文本、尺寸和 Pexels URL。

2. 下载照片

使用搜索响应中的 src URL——不要自行拼接 images.pexels.com URL（slug/扩展名不一定固定；Pexels 文档要求使用 src）。每个照片对象都包含现成的尺寸变体（参见上方的 src 表）。

# Download the size you need, straight from the photo's src field
# (e.g. the value of photos[0].src.large from the search JSON)
curl -sL -o /tmp/pexels_<id>.jpeg "<photo.src.large>"

通过宿主的文件交付机制将文件交给用户。

3. 展示结果

展示搜索结果时，请使用表格格式：

| # | ID | Photographer | Alt | Dimensions |
|---|-----|-------------|-----|------|
| 1 | 5097071 | Dylan Chan | Singapore skyline at dusk | 6016×3384 |

请附上 Pexels URL，以便用户在下载前预览。

署名

按照 Pexels 指南：

• 注明摄影师姓名：“Photo by [Name] on Pexels”
• 链接回照片页面 URL
• 展示多张照片时，注明“Photos provided by Pexels”

署名示例：

Photo by Dylan Chan on Pexels
https://www.pexels.com/photo/high-rise-buildings-in-singapore-5097071/

常见陷阱

1. 环境中未设置 API 密钥。 发出请求前必须设置 PEXELS_API_KEY。调用 curl 前，请从环境或 .env 文件中加载该密钥。

2. 查询中使用空格。 请将空格编码为 + 或 %20。 singapore skyline → singapore+skyline。

3. 预览时下载原图。 原始文件可能超过 10MB。预览时使用 large 或 medium，仅在用户需要完整分辨率时才使用 original。

4. 注意速率限制。 每小时 200 次请求，每月 20k 次请求——但只有 API 调用 （搜索、精选内容、照片查询）会计入。通过 images.pexels.com 上的 src URL 下载 CDN 内容（无需 API 密钥） 不会计入。使用 per_page=15-80 批量搜索，以尽量减少 API 调用。

5. 未注明来源。 Pexels 要求明确注明摄影师并附上 Pexels 链接。交付照片时务必附上来源说明。

6. 手动拼接照片 URL。 不要自行构造 images.pexels.com/photos/... URL——照片的 slug 和扩展名并非固定。请务必通过 API 响应中的 src.* URL 下载。

验证清单

• 环境中已设置 PEXELS_API_KEY
• 搜索查询返回结果（检查 total_results > 0）
• 下载的文件存在且非空
• 交付的照片附有来源说明
• 发出大量请求时检查速率限制标头（X-Ratelimit-Remaining）