md2wechat API 服务 · Markdown 转公众号 HTML
返回编辑器
API REFERENCE / CONVERT

Markdown 转公众号 HTML

一次 POST 请求，拿到带内联样式的微信兼容 HTML。字体、行距、卡片结构都写进 style 属性里， 粘贴到公众号后台不再掉格式。转换接口只做排版，不创建草稿，也不接触你的公众号凭证。

POST https://www.md2wechat.cn/api/convert
4请求参数
6内置主题
JSON响应格式
0副作用

内联样式输出

递归把计算样式写进元素，微信侧不依赖任何外部样式表。

主题与字号

theme、fontSize、backgroundType 三个开关控制阅读气质。

零副作用

只返回 HTML，不写草稿、不改素材库、不需要微信 AppID。

快速开始

三步拿到可以粘贴的排版结果。

  1. 01

    拿到 API Key

    向维护者申请 Convert API 的密钥，通过请求头 Md2wechat-API-Key 传递。 获取 API Key

  2. 02

    发送一次 POST 请求

    请求体就是一个 JSON：markdown 必填，其余三个参数都有默认值。

  3. 03

    取 data.html 用起来

    直接粘进公众号后台，或存进你自己的内容库。需要草稿请走独立的发布 API。

认证

只需要一个 API Key，不需要微信凭证，也没有 IP 白名单。

请求头类型必填说明
Md2wechat-API-Key string 是 服务端签发的密钥。缺失或无效返回 401。
Content-Type string 是 固定 application/json。
密钥放在服务端。

浏览器里写死的 Key 等同于公开。前端页面请走你自己的后端中转，由后端带上请求头调用。

请求与参数

四个字段，三个有默认值。

参数类型默认说明
markdown 必填 string — 要转换的 Markdown 正文。支持本站编辑器里的标题、列表、表格、代码块与 ::: 模块语法。
theme string default 主题 ID。官方支持原生、精选与模板主题；本站内置 warm / minimal / forest / ocean / plum / ink。
fontSize string medium 字号档位：small / medium / large。
backgroundType string default 底色策略：default 跟随主题纸白，grid 叠一层细网格，none 透明。
请求体 
{
  "markdown": "# 一份值得读完的文章\n\n从清楚的结构开始。",
  "theme": "default",
  "fontSize": "medium",
  "backgroundType": "default"
}

在线调试

填参数直接发。本地引擎模式由本页的渲染器实时出结果，不需要密钥。

本地引擎：用本页同一套渲染与内联逻辑生成结果，响应结构与官方一致，无需密钥。

markdown string · 必填 0 字符
请求体预览 

          


          

            
            
          

        


        

          

            待发送
          

          

            
            
            
            
          

          

            
点击「发送请求」查看响应。

          

          
          
        

      

    


    
    

      

        
代码示例

        
跟着上面的调试参数实时生成，可直接复制到你自己的服务里。

      


      

        

          

            
            
            
            
          

          
        

        

      

    


    
    

      

        
响应结构

        
统一信封：code、msg、data。

      


      

        

          200 · application/json
          
        

        
{
  "code": 0,
  "msg": "success",
  "data": {
    "html": "<section>…</section>",
    "theme": "default",
    "fontSize": "medium",
    "backgroundType": "default",
    "wordCount": 123,
    "estimatedReadTime": 1
  }
}

      


      

        

          
字段类型说明

          
            
codenumber0 表示成功，其余为业务错误码。

            
msgstring结果描述，成功时为 success。

            
data.htmlstring带内联样式的公众号 HTML。

            
data.themestring实际生效的主题 ID。

            
data.fontSizestring实际生效的字号档位。

            
data.backgroundTypestring实际生效的底色策略。

            
data.wordCountnumber正文字符数，已剔除标记符号。

            
data.estimatedReadTimenumber预计阅读时长，单位分钟，最小为 1。

          
        

      

    


    
    

      

        
错误码

        
按 HTTP 状态码判断，再读 msg 定位字段。

      


      

        

          
状态含义下一步

          
            
400参数错误检查 markdown 是否为空，以及主题、字号、底色是否在允许值内。

            
401认证失败检查 Md2wechat-API-Key 是否存在、有效、未过期。

            
429请求受限降低频率后重试，建议指数退避（如 1s、2s、4s）。

            
5xx服务异常保留请求体与时间点，稍后重试或联系维护者。

          
        

      


      

        
        

          浏览器直连可能被跨域拦住。
          
调试台的「远程接口」若停在 Failed to fetch，通常是缺少 CORS 响应头，不是密钥问题。服务端调用（cURL / Python / Node）不受影响。

        

      

    


    
    

      

        
转换与发布是两件事

        
别把 200 当成草稿已创建。

      


      

        

          
本站 · Convert API

          
只做排版

          
POST /api/convert 返回微信公众号可粘贴的 HTML，不创建草稿、不写素材库、不需要微信凭证。

        

        

          
国际站 · Publishing API

          
才建草稿

          
https://md2wechat.com/api/v1 在配置微信凭证并显式授权后创建草稿，属于独立的服务面。

        

      

    


    
    

      

        
常见问题

      


      

        

          只做转换需要微信 AppID 或 AppSecret 吗？
          
不需要。转换请求只需要 Md2wechat-API-Key，也不需要公众号白名单与固定出口。

        

        

          调试台的「本地引擎」和远程接口有区别吗？
          
本地引擎用本页同一套 Markdown 渲染与内联逻辑生成 HTML，响应结构与字段完全对齐官方契约，适合在没有密钥时验证参数与排版；远程接口则真实请求 https://www.md2wechat.cn/api/convert，结果取决于你的密钥与官方主题库。

        

        

          站点里的 6 套主题怎么对应到接口的 theme？
          
本地引擎接受 warm / minimal / forest / ocean / plum / ink，default 落到暖橘。官方接口另有原生与模板主题 ID，以官方文档为准。

        

        

          可以批量转换长文吗？
          
按单篇调用，服务端并发控制在你这一侧。遇到 429 就退避重试，不要无间隔轮询。

        

        

          为什么返回的 HTML 里有这么多 style？
          
公众号会清洗 <style> 与外链样式，只有内联样式能稳定保留。多出来的体积换来的是粘贴后不走样。