# Unsplash API 调用指南

> 用于 N8N 内容流水线自动配图

---

## 注册与获取 Access Key

1. 访问 [Unsplash Developers](https://unsplash.com/developers)
2. 注册一个 New Application
3. 获取 **Access Key**（即 Client ID）

> 免费额度：50 请求/小时，足够个人/小团队使用

---

## 基础调用方式

### 1. curl 命令（测试用）

```bash
curl -s "https://api.unsplash.com/search/photos" \
  -H "Authorization: Client-ID bzq5vp2kcUqlKTtLL3dwECkha1-jinwttn5JlhwjTBw" \
  -G \
  --data-urlencode "query=AI automation" \
  --data-urlencode "per_page=3"
```

**参数说明：**
- `query`：搜索关键词（英文效果更好）
- `per_page`：返回图片数量（默认 10）

**解析返回结果（安装 jq 后）：**

```bash
curl -s "https://api.unsplash.com/search/photos" \
  -H "Authorization: Client-ID bzq5vp2kcUqlKTtLL3dwECkha1-jinwttn5JlhwjTBw" \
  -G \
  --data-urlencode "query=AI automation" \
  --data-urlencode "per_page=3" \
  | jq '.results[] | {id, description, url: .urls.regular, credit: .user.name}'
```

### 2. 返回字段说明

| 字段 | 说明 |
|------|------|
| `id` | 图片唯一 ID |
| `description` | 图片描述（可作为 alt 文本） |
| `urls.regular` | 常规尺寸链接（可直接用于 Markdown） |
| `urls.small` | 小尺寸链接 |
| `urls.thumb` | 缩略图链接 |
| `user.name` | 作者名（署名用） |
| `user.links.html` | 作者主页链接 |

### 3. 嵌入 Markdown

```markdown
![AI自动化](https://images.unsplash.com/photo-1677442136019-21780ecad995?w=800)

*Photo by John Doe on Unsplash*
```

---

## N8N 集成方式

### 方式一：Unsplash 官方节点

N8N 有 Unsplash 官方节点（推荐）：

```
节点：Unsplash Node
操作：Search Photos
Query：AI automation
Num Results：1
```

### 方式二：HTTP Request 手动调用

如果 N8N 没有 Unsplash 节点，可以用 **HTTP Request** 节点：

```
Method：GET
URL：https://api.unsplash.com/search/photos
Headers：
  Authorization：Client-ID 你的AccessKey
Query Parameters：
  query：AI automation
  per_page：1
```

### 3. 在 N8N 中提取图片 URL

Expression 写法：

```javascript
// 取第一张图片的 regular URL
$json.results[0].urls.regular

// 取第一张图片的描述
$json.results[0].description || $json.results[0].alt_description

// 取作者信息
$json.results[0].user.name
```

---

## 在内容流水线中的使用场景

### 场景 1：封面图生成

AI 改写时要求模型输出一个封面图搜索关键词，如：

```json
{
  "title": "AI Agent 自动化工作流实战",
  "cover_keyword": "robot workflow automation technology"
}
```

N8N 用这个 keyword 调用 Unsplash，拿到封面图 URL。

### 场景 2：文内插图

AI 改写时在文章中插入占位符：

```markdown
这里是正文内容...

[IMAGE: teamwork collaboration]

更多内容...
```

N8N 识别 `[IMAGE: xxx]` 占位符，用 xxx 搜索 Unsplash 替换。

---

## 版权注意事项

Unsplash 图片**可免费商用**，但需遵守以下规则：

1. **署名**：建议在图片下方注明作者名和 Unsplash
2. **不可单独销售**：不能把 Unsplash 图片单独作为商品出售
3. **禁止直接链接**：不要用图片的 CDN 链接作为独立网站图片（会触发防盗链）

**安全做法**：下载图片到自己的图床或 OSS，用自己的域名展示。

---

## 常见问题

**Q：API 返回 401 Unauthorized？**
> 检查 Access Key 是否正确，是否包含空格或引号。

**Q：搜索结果为空？**
> 尝试用英文关键词，或减少 per_page 数量。

**Q：频率超限（429）？**
> 等待 1 小时，或申请更高配额。