使用 API 发布博客文章（Codex / Claude Code）

什么是博客发布 API

博客发布 API 让你可以通过个人访问令牌，在 Codex、Claude Code 等本地 AI 编程工具中直接管理博客投稿。你可以创建草稿、上传图片、预览排版、编辑 Markdown，最后提交审核——全部通过命令行或 AI 助手完成，无需打开浏览器。

用 API 发布的好处：AI 工具可以帮你整理排版、修正错别字、统一格式，文章质量更高，写起来也更省力。

前置条件

1. 已注册并验证邮箱：API 令牌绑定到你的账户，邮箱未验证无法创建令牌。
2. 创建个人访问令牌：登录后在「账户设置 → 博客 API 令牌」页面创建。令牌格式为 msb_...，完整内容只在创建时显示一次，务必当场复制保存。

令牌权限说明

令牌有四项独立的 scope，按需勾选：

Scope	能力
blog:read	读取分区列表、自己的文章和预览
blog:write	创建文章，修改自己的草稿或被驳回文章
blog:submit	提交文章审核，撤回待审核文章
blog:image	上传博客图片（单张最大 5MB，每用户 200MB 配额）

发布一篇文章通常需要四项 scope 全部勾选。如果你只希望 AI 工具读取文章做参考，可以只勾 blog:read。

发布流程概览

完整的发布流程分为五步：

1. 获取分区列表 — 确认文章所属分区
2. 创建草稿 — 标题、摘要、正文、分区、标签
3. 读取并修改 — 用 updatedAt 做乐观锁，避免并发冲突
4. 上传图片并预览 — 图片走专用上传接口，预览走正式渲染管线
5. 提交审核或撤回 — 提交后进入人工审核队列

完整调用指南

以上每个步骤的详细命令、请求格式、错误恢复方案，请参阅：

查看完整调用指南 →

完整指南包含各语言环境的 curl 示例、令牌安全存储方式、分步错误码对照表，以及 Codex 和 Claude Code 的实操示范。

安全注意事项

• 令牌不要提交到仓库，不要写进 .md 文章、AGENTS.md、截图或日志。
• 推荐用 read -s 静默读入、设置临时环境变量，用完 unset 清除。
• 每枚令牌可设置 30/90/365 天过期，到期自动失效。
• 最多同时持有 10 枚令牌。不再需要的令牌请在账户页撤销。

常见问题

可以用 API 发布文件文章（content/blog/*.md）吗？

不能。API 只管理数据库投稿，和网页端 /blog/submit 共用同一套数据。文件文章属于站主，通过 Git 仓库管理。

管理员可以用 API 直接发布吗？

管理员使用自己的令牌提交文章时，会直接变为 published 状态，跳过人工审核。但管理员令牌不能编辑他人文章，也不能调用后台审核接口。

图片上传失败怎么办？

检查图片格式（支持 WebP/JPEG/PNG/GIF）、大小（5MB 以内）、像素数（4000 万以内）。如果配额已满，联系管理员清理未引用对象。相同图片重复上传会复用原 URL，不消耗配额。