Unsplash_内容创作 skill-PHP中文网

Unsplash

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

搜索、浏览并下载Unsplash高质量免费照片，支持筛选、随机选择及查看详细照片元数据。

Unsplash API. 搜索,浏览, 从 Unsplash 的数百万图像库下载高质量的免费照片. .

功能概述

Unsplash API. 搜索,浏览, 从 Unsplash 的数百万图像库下载高质量的免费照片. .是一项面向实际任务的技能，主要用于Setup & Authoration.；Get your Access Key.；

核心要点

Create accounts at https://unsplash.co。
它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。

使用与执行

从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。

Unsplash API

在 Unsplash 拥有的数百万张高质量免费图片库中进行搜索、浏览和下载。

配置与身份验证

获取您的 Access Key

在 https://unsplash.com/developers 注册账号
注册一个新应用
复制您的 Access Key（以您的应用名称开头）

存储凭据

mkdir -p ~/.config/unsplash
echo "YOUR_ACCESS_KEY" > ~/.config/unsplash/access_key
chmod 600 ~/.config/unsplash/access_key

或设置环境变量：

export UNSPLASH_ACCESS_KEY="your_access_key_here"

速率限制

演示版：每小时 50 次请求
生产环境：每小时 5,000 次请求（需通过应用审核后生效）
仅 /v1/messages 类端点计入限制；图片 URL（images.unsplash.com）不计入

常用操作

搜索图片

curl "https://api.unsplash.com/search/photos?query=nature&per_page=10" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

参数说明：

query：搜索关键词（必需）
page：页码（默认为 1）
per_page：每页返回结果数（默认为 10，最大为 30）
order_by：relevant（默认）或 latest
color：按颜色筛选（black_and_white、black、white、yellow、orange、red、purple、magenta、green、teal、blue）
orientation：landscape、portrait 或 squarish

获取随机图片

curl "https://api.unsplash.com/photos/random?query=coffee&count=1" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

参数说明：

query：限定搜索关键词（可选）
count：返回图片数量（1–30，默认为 1）
orientation：按朝向筛选
collections：按收藏集 ID 筛选（多个 ID 用英文逗号分隔）

获取图片详情

curl "https://api.unsplash.com/photos/PHOTO_ID" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

返回完整的图片元数据，包括 EXIF 信息、地理位置、用户信息以及全部图片 URL。

记录下载行为（必需！）

重要提示：为遵守 API 使用规范，在下载图片时必须调用该端点。

curl "https://api.unsplash.com/photos/PHOTO_ID/download" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

此操作将使该图片的下载计数器加一。响应中包含实际下载地址。

列出编辑精选动态流

curl "https://api.unsplash.com/photos?per_page=10" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

浏览收藏集

# 列出所有收藏集
curl "https://api.unsplash.com/collections?per_page=10" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# 获取某收藏集下的图片
curl "https://api.unsplash.com/collections/COLLECTION_ID/photos" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

用户上传的图片

curl "https://api.unsplash.com/users/USERNAME/photos?per_page=10" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

处理图片

图片 URL

每张图片的响应中均包含以下 URL 字段：

{
  "urls": {
    "raw": "https://images.unsplash.com/photo-xxx?ixid=xxx",
    "full": "...?ixid=xxx&q=80&fm=jpg",
    "regular": "...?ixid=xxx&w=1080&fit=max",
    "small": "...?w=400&fit=max",
    "thumb": "...?w=200&fit=max"
  }
}

动态缩放

可在任意图片 URL 后追加参数（请务必保留 ixid 参数！）：

w=1500：设定宽度
h=800：设定高度
dpr=2：设备像素比
q=75：质量（取值范围：1–100）
fm=jpg：格式（支持 jpg、png、webp、avif）
fit=crop：适配模式（crop、max、clip）
crop=entropy：裁剪策略

示例：

https://images.unsplash.com/photo-xxx?ixid=xxx&w=1500&h=1000&fit=crop&q=85

BlurHash 占位符

每张图片均附带 blur_hash 字段——一种紧凑字符串表示法，可用于在图片加载过程中显示模糊占位图。

{
  "blur_hash": "LoC%a7IoIVxZ_NM|M{s:%hRjWAo0"
}

响应结构

图片对象（精简版）

{
  "id": "LBI7cgq3pbM",
  "created_at": "2016-05-03T11:00:28-04:00",
  "width": 5245,
  "height": 3497,
  "color": "#60544D",
  "blur_hash": "LoC%a7IoIVxZ_NM|M{s:%hRjWAo0",
  "description": "A man drinking coffee",
  "urls": { "raw": "...", "full": "...", "regular": "..." },
  "links": {
    "download": "...",
    "download_location": "https://api.unsplash.com/photos/xxx/download"
  },
  "user": {
    "username": "johndoe",
    "name": "John Doe",
    "profile_image": { "small": "...", "medium": "...", "large": "..." }
  }
}

搜索响应

{
  "total": 133,
  "total_pages": 7,
  "results": [ /* 图片对象数组 */ ]
}

最佳实践

署名要求

始终为所用图片标注原始创作者：

Photo by [Name] on Unsplash

如有可能，请链接至摄影师的 Unsplash 主页。

下载追踪

在允许用户下载前，必须调用 /photos/:id/download
此操作为 Unsplash API 使用规范中的强制要求
仅用于展示图片时无需调用（热链访问会自动统计浏览量）

热链访问（Hotlinking）

可直接从 images.unsplash.com 热链引用图片
此类请求不计入速率限制
浏览次数将被自动统计
使用或修改图片 URL 时，请始终保留 ixid 参数

缓存策略

公开端点（如搜索、图片详情等）支持缓存
建议在客户端缓存搜索结果，以减少 API 调用频次

速查表

# 存储密钥
export UNSPLASH_ACCESS_KEY="your_key"

# 搜索
curl "https://api.unsplash.com/search/photos?query=ocean&per_page=5" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# 随机图片
curl "https://api.unsplash.com/photos/random?query=mountains" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# 获取图片详情
curl "https://api.unsplash.com/photos/PHOTO_ID" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# 记录下载（下载时必需！）
curl "https://api.unsplash.com/photos/PHOTO_ID/download" 
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"