新增 Unsplash API 调用指南

openclaw/yunce/Unsplash-API调用指南.md

@@ -0,0 +1,162 @@
+# 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 你的AccessKey" \
+  -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 你的AccessKey" \
+  -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 小时，或申请更高配额。