pexels-media

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pexels Media Sourcing

Pexels媒体资源获取

Source high-quality, royalty-free images and videos from Pexels for design work, placeholders, or content creation.

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

Prerequisites

前置条件

This skill requires the

PEXELS_API_KEY

environment variable to be set.

bash

undefined

使用本技能需要设置

PEXELS_API_KEY

环境变量。

bash

undefined

Check if API key is available

检查API密钥是否可用

echo $PEXELS_API_KEY


If not set, obtain a free API key from [Pexels API](https://www.pexels.com/api/).

echo $PEXELS_API_KEY


如果未设置，请从[Pexels API](https://www.pexels.com/api/)获取免费API密钥。

API Base URLs

API基础地址

Photos:
```
https://api.pexels.com/v1/
```
Videos:
```
https://api.pexels.com/videos/
```

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

Authentication

身份验证

All requests require the Authorization header:

bash

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

所有请求都需要携带Authorization请求头：

bash

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

Photo Endpoints

图片接口

Search Photos

搜索图片

bash

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"

Parameters:

Parameter	Required	Values
`query`	Yes	Search term
`orientation`	No	`landscape` , `portrait` , `square`
`size`	No	`large` (24MP), `medium` (12MP), `small` (4MP)
`color`	No	`red` , `orange` , `yellow` , `green` , `turquoise` , `blue` , `violet` , `pink` , `brown` , `black` , `gray` , `white` , or hex code (e.g., `#ffffff` )
`locale`	No	`en-US` , `pt-BR` , `es-ES` , `de-DE` , `fr-FR` , `ja-JP` , `zh-CN` , `ko-KR` , etc.
`page`	No	Page number (default: 1)
`per_page`	No	Results per page (default: 15, max: 80)

bash

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）

Curated Photos

精选图片

Trending photos curated by the Pexels team (updated hourly):

bash

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

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

bash

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

Get Photo by ID

通过ID获取图片

bash

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

bash

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

Video Endpoints

视频接口

Search Videos

搜索视频

bash

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"

Additional Video Parameters:

Parameter	Description
`min_width`	Minimum width in pixels
`min_height`	Minimum height in pixels
`min_duration`	Minimum duration in seconds
`max_duration`	Maximum duration in seconds

bash

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`	最大时长（秒）

Get Video by ID

通过ID获取视频

bash

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

bash

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

Collections

合集

Featured Collections

精选合集

bash

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

bash

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

Collection Media

合集中的媒体资源

bash

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

Type parameter:

photos

videos

, or omit for both.

bash

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

Type参数：

photos

（图片）,

videos

（视频），或留空同时获取两者。

Photo Sizes Available

可用的图片尺寸

When downloading photos, these sizes are available in the API response:

Key	Description
`original`	Original size uploaded by photographer
`large2x`	Width 940px, height doubled
`large`	Width 940px
`medium`	Height 350px
`small`	Height 130px
`portrait`	Width 800px, height 1200px
`landscape`	Width 1200px, height 627px
`tiny`	Width 280px, height 200px

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

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

Video Files Available

可用的视频文件

Videos include multiple quality files in the response:

Quality	Typical Resolution
`hd`	1280x720
`sd`	640x360
`hls`	Adaptive streaming
Various	Full HD, 4K when available

视频响应中包含多种画质的文件：

画质	典型分辨率
`hd`	1280x720
`sd`	640x360
`hls`	自适应流
其他	支持全高清、4K（如有提供）

MANDATORY: Sidecar Metadata Files

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

CRITICAL REQUIREMENT: For EVERY downloaded file, you MUST create a sidecar metadata file.

关键要求： 对于每个下载的文件，必须创建一个附属元数据文件。

Sidecar File Naming

附属文件命名规则

For a downloaded file

mountain-sunset.jpg

, create

mountain-sunset.jpg.meta.json

如果下载的文件名为

mountain-sunset.jpg

，则创建

mountain-sunset.jpg.meta.json

。

Photo Sidecar Content

图片附属文件内容

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
  }
}

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": {
    // 该图片的完整原始API响应内容
  }
}

Video Sidecar Content

视频附属文件内容

json

{
  "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
  }
}

json

{
  "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": {
    // 该视频的完整原始API响应内容
  }
}

Download Workflow

下载工作流

1. Search and Select

1. 搜索并选择资源

bash

undefined

bash

undefined

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}'

undefined

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

undefined

2. Download with Sidecar

2. 下载并生成附属文件

bash

undefined

bash

undefined

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"

undefined

undefined

Rate Limits

请求频率限制

Default: 200 requests/hour, 20,000 requests/month

Check response headers for current limits:

```
X-Ratelimit-Limit
```
```
X-Ratelimit-Remaining
```
```
X-Ratelimit-Reset
```

默认限制： 每小时200次请求，每月20000次请求

可通过响应头查看当前限制：

```
X-Ratelimit-Limit
```
```
X-Ratelimit-Remaining
```
```
X-Ratelimit-Reset
```

Attribution Best Practices

署名最佳实践

While not legally required by the Pexels license, attribution is encouraged:

Minimal: "Photo by [Photographer] on Pexels"
With link: "Photo by Photographer on Pexels"
HTML: Use the
```
attribution_html
```
from the sidecar file

虽然Pexels许可证没有强制要求署名，但建议进行署名：

最简形式： "Photo by [摄影师姓名] on Pexels"
带链接形式： "Photo by 摄影师姓名 on Pexels"
HTML格式： 使用附属文件中的
```
attribution_html
```
内容

Example Use Cases

示例用例

Placeholder Images for UI Design

UI设计占位符图片

bash

undefined

bash

undefined

Get 5 abstract/minimal images for placeholders

获取5张抽象/极简风格的占位符图片

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

undefined

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

undefined

Hero Background Video

首页背景视频

bash

undefined

bash

undefined

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"

undefined

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"

undefined

Product Photography Backgrounds

产品摄影背景

bash

undefined

bash

undefined

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"

undefined

curl -s -H "Authorization: $PEXELS_API_KEY"
"https://api.pexels.com/v1/search?query=white+background+texture&color=white&size=large"

undefined

Checklist

检查清单

When using this skill:

Verify
```
PEXELS_API_KEY
```
is set
Choose appropriate endpoint (search, curated, popular, collection)
Apply relevant filters (orientation, size, color, duration)
Select appropriate resolution for use case
Download file to appropriate location
CREATE SIDECAR METADATA FILE (mandatory)
Consider attribution in final use

使用本技能时，请确认：

已验证
```
PEXELS_API_KEY
```
已设置
选择了合适的接口（搜索、精选、热门、合集）
应用了相关筛选条件（方向、尺寸、颜色、时长）
为使用场景选择了合适的分辨率
将文件下载到了合适的位置
已创建附属元数据文件（强制要求）
在最终使用中考虑了署名

pexels-media

Original

Translation

Pexels Media Sourcing

Pexels媒体资源获取

Prerequisites

前置条件

Check if API key is available

检查API密钥是否可用

API Base URLs

API基础地址

Authentication

身份验证

Photo Endpoints

图片接口

Search Photos

搜索图片

Curated Photos

精选图片

Get Photo by ID

通过ID获取图片

Video Endpoints

视频接口

Search Videos

搜索视频

Popular Videos

热门视频

Get Video by ID

通过ID获取视频

Collections

合集

Featured Collections

精选合集

Collection Media

合集中的媒体资源

Photo Sizes Available

可用的图片尺寸

Video Files Available

可用的视频文件

MANDATORY: Sidecar Metadata Files

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

Sidecar File Naming

附属文件命名规则

Photo Sidecar Content

图片附属文件内容

Video Sidecar Content

视频附属文件内容

Download Workflow

下载工作流

1. Search and Select

1. 搜索并选择资源

Search for photos

搜索图片

Parse and display results

解析并显示结果

2. Download with Sidecar

2. 下载并生成附属文件

Get photo details

获取图片详情

Extract download URL (choose size)

提取下载地址（选择尺寸）

Download the image

下载图片

Create sidecar metadata (MANDATORY)

创建附属元数据文件（强制要求）

Rate Limits

请求频率限制

Attribution Best Practices

署名最佳实践

Example Use Cases

示例用例

Placeholder Images for UI Design

UI设计占位符图片

Get 5 abstract/minimal images for placeholders

获取5张抽象/极简风格的占位符图片

Hero Background Video

首页背景视频

Find short, wide landscape videos

查找短时长、宽屏的风景视频

Product Photography Backgrounds