Halo 2.22 API 完整使用指南总结
本文档基于《Halo 2.22.14 API 完整指南》整理，涵盖了所有核心 API 端点的使用方法和最佳实践。
📚 概述
Halo 2.22.14 提供了完整的 RESTful API，支持文章管理、附件上传、内容查询等核心功能。本指南将帮助你快速掌握 Halo API 的使用。
🔑 核心功能概览
1. 文章管理
2. 内容管理
3. 附件管理
⚠️ 重要提示
Halo 2.22 的内容存储机制
Halo 2.22 使用 Snapshot 机制存储文章内容，这与传统 CMS 不同：
Post 对象：仅存储元数据（标题、slug、分类等）
Snapshot 对象：存储实际内容（rawPatch 和 contentPatch 字段）
Base64 编码：内容使用 base64 编码存储
这不是 bug，而是 Halo 2.22 的正常架构设计！
💡 最佳实践
推荐工作流程
graph LR
A[上传图片] --> B[创建文章]
B --> C[获取图片URL]
C --> D[生成Markdown]
D --> E[通过API发布]
关键要点
认证方式：使用 Bearer Token
内容格式：推荐使用 HTML 格式（兼容 ProseMirror）
图片处理：先上传再获取 URL
分页查询：使用
page和size参数
📝 示例代码
获取文章列表
import requests
headers = {"Authorization": f"Bearer {token}"}
resp = requests.get(
"https://www.shopqiu.com/apis/content.halo.run/v1alpha1/posts?phase=PUBLISHED&page=0&size=10",
headers=headers
)
data = resp.json()
posts = data.get('items', [])
上传图片
with open('image.png', 'rb') as f:
files = {'file': ('image.png', f.read(), 'image/png')}
data = {'policyName': 'default-policy'}
resp = requests.post(
"https://www.shopqiu.com/apis/api.console.halo.run/v1alpha1/attachments/upload",
headers=headers,
files=files,
data=data
)
创建文章
create_post_data = {
"spec": {
"title": "文章标题",
"slug": "article-slug",
"owner": "admin",
"publish": False,
"visible": "PUBLIC",
"allowComment": True,
"categories": [],
"tags": []
}
}
🎯 总结
Halo 2.22.14 提供了强大而灵活的 API，支持完整的博客管理功能。理解其 Snapshot 机制是高效使用的关键。
核心优势
✅ 完整的 RESTful API 设计
✅ 灵活的内容管理
✅ 高效的附件处理
✅ 完善的权限控制
适用场景
自动化内容发布
批量文章管理
第三方系统集成
自定义工具开发
文档版本: 1.0
最后更新: 2026-02-28
Halo 版本: 2.22.14
💡 提示: 使用 halo-mcp-server 可以更轻松地管理 Halo 博客，支持自然语言交互和完整的 API 封装。