Markdown 转公众号 HTML
一次 POST 请求，拿到带内联样式的微信兼容 HTML。字体、行距、卡片结构都写进 style 属性里，
粘贴到公众号后台不再掉格式。接口跑在本站的 Pages Function 上，只做排版，不创建草稿，也不接触你的公众号凭证。
/api/convert
内联样式输出
递归把计算样式写进元素，微信侧不依赖任何外部样式表。
主题与字号
theme、fontSize、backgroundType 三个开关控制阅读气质。
零副作用
只返回 HTML，不写草稿、不改素材库、不需要微信 AppID。
快速开始
三步拿到可以粘贴的排版结果。
-
01
配置 API Key
在 Cloudflare Pages 的 Settings → Environment variables 里加一个
CONVERT_API_KEY， 调用时通过请求头Md2wechat-API-Key传递；只想开放演示就设ALLOW_ANONYMOUS=true。 环境变量文档 -
02
发送一次 POST 请求
请求体就是一个 JSON：
markdown必填，其余三个参数都有默认值。 -
03
取
data.html用起来直接粘进公众号后台，或存进你自己的内容库。需要草稿请走独立的发布 API。
认证
只需要一个 API Key，不需要微信凭证，也没有 IP 白名单。
| 请求头 | 类型 | 必填 | 说明 |
|---|---|---|---|
Md2wechat-API-Key |
string | 是 | 本站管理员在 Cloudflare Pages 环境变量 CONVERT_API_KEY 里配置的密钥。缺失或无效返回 401。 |
Content-Type |
string | 是 | 固定 application/json。 |
管理员把 ALLOW_ANONYMOUS 设为 true 时，可以不传 Md2wechat-API-Key 直接调用，适合演示站；
此时请务必保留限流（RATE_LIMIT，默认每 IP 每分钟 30 次）。未配置任何密钥且未开启匿名时返回 503。
浏览器里写死的 Key 等同于公开。前端页面请走你自己的后端中转，由后端带上请求头调用；本页调试台输入的 Key 只存在本地浏览器。
请求与参数
四个字段，三个有默认值。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
markdown 必填 |
string | — | 要转换的 Markdown 正文。支持本站编辑器里的标题、列表、表格、代码块与 ::: 模块语法。 |
theme |
string | default |
主题 ID，default 落到暖橘。可选：warm / minimal / forest / ocean / plum / ink / amber / rose / indigo / olive。 |
fontSize |
string | medium |
字号档位：small / medium / large。 |
backgroundType |
string | default |
底色策略：default 跟随主题纸白，grid 叠一层细网格，none 透明。 |
{
"markdown": "# 一份值得读完的文章\n\n从清楚的结构开始。",
"theme": "default",
"fontSize": "medium",
"backgroundType": "default"
}
在线调试
填参数直接发。本地引擎模式由本页的渲染器实时出结果，不需要密钥。
本地引擎：用本页同一套渲染与内联逻辑生成结果，响应结构与接口一致，无需密钥。
请求体预览
点击「发送请求」查看响应。
代码示例
跟着上面的调试参数实时生成，可直接复制到你自己的服务里。
响应结构
统一信封：code、msg、data。
{
"code": 0,
"msg": "success",
"data": {
"html": "<section>…</section>",
"theme": "default",
"fontSize": "medium",
"backgroundType": "default",
"wordCount": 123,
"estimatedReadTime": 1
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 0 表示成功，其余为业务错误码。 |
msg | string | 结果描述，成功时为 success。 |
data.html | string | 带内联样式的公众号 HTML。 |
data.theme | string | 实际生效的主题 ID。 |
data.fontSize | string | 实际生效的字号档位。 |
data.backgroundType | string | 实际生效的底色策略。 |
data.wordCount | number | 正文字符数，已剔除标记符号。 |
data.estimatedReadTime | number | 预计阅读时长，单位分钟，最小为 1。 |
错误码
按 HTTP 状态码判断，再读 msg 定位字段。
| 状态 | 含义 | 下一步 |
|---|---|---|
| 400 | 参数错误 | 检查 markdown 是否为空，以及主题、字号、底色是否在允许值内。 |
| 401 | 认证失败 | 检查 Md2wechat-API-Key 是否与站点配置的 CONVERT_API_KEY 一致。 |
| 413 | 请求体过大 | 单次正文请控制在 100 K 字符 / 200 KB 以内。 |
| 429 | 请求受限 | 降低频率后重试，建议指数退避（如 1s、2s、4s）。 |
| 503 | 服务未配置 | 站点既没有设置 CONVERT_API_KEY，也没有开启匿名调用。 |
| 5xx | 服务异常 | 保留请求体与时间点，稍后重试或联系维护者。 |
响应带 Access-Control-Allow-Origin: *，第三方页面可以直接请求；预检请求（OPTIONS）返回 204。
代价是任何人都能调用，所以生产环境请务必配好 CONVERT_API_KEY 与限流。
转换与发布是两件事
别把 200 当成草稿已创建。
只做排版
POST /api/convert 返回微信公众号可粘贴的 HTML，不创建草稿、不写素材库、不需要微信凭证。
才建草稿
创建草稿属于另一件事，需要公众号的 AppID / AppSecret 与 IP 白名单，属于微信官方能力，不在本接口范围内。
常见问题
只做转换需要微信 AppID 或 AppSecret 吗？
不需要。转换请求只需要 Md2wechat-API-Key，也不需要公众号白名单与固定出口。
调试台的「本地引擎」和「远程接口」有什么区别？
本地引擎用浏览器里同一套渲染与内联逻辑生成 HTML，不联网、不需要密钥，适合先调参数；
远程接口真实请求本站的 POST /api/convert，结果由服务端生成，与你用 cURL 调到的完全一样。
服务端没有浏览器，样式是怎么内联的？
构建时把 theme.css 编译成规则表（变量烘焙成实值、剔除无法内联的伪元素），
请求时用同一份 Markdown 渲染器产出 HTML，再按 CSS 级联顺序把命中规则拼进 style。
实测与浏览器内联结果的计算样式一致率 100%。
接口支持哪些 theme？
站点内置 10 套：warm / minimal / forest / ocean / plum / ink /
amber / rose / indigo / olive，default 等于 warm。传其它值返回 400。
可以批量转换长文吗？
按单篇调用，服务端并发控制在你这一侧。遇到 429 就退避重试，不要无间隔轮询。
为什么返回的 HTML 里有这么多 style？
公众号会清洗 <style> 与外链样式，只有内联样式能稳定保留。多出来的体积换来的是粘贴后不走样。