MD2Card API 文档 | MD2Card - Markdown 转知识卡片工具

/api/generate

将 Markdown 文本转换为精美的卡片图片。

认证方式

使用 API Key 进行认证，需要在请求头中添加 x-api-key 字段。

x-api-key: your_api_key

请求方法

POST

请求参数

请求体为 JSON 格式，包含以下字段：

参数	类型	必填	默认值	说明
markdown	string	否	"# 默认 markdown"	要转换的 Markdown 文本
theme	string	否	"apple-notes"	卡片主题样式 ID
themeMode	string	否	只支持个别样式	主题的模式 ID (例如 `light-mode`, `dark-mode`)
width	number	否	440	卡片宽度（像素）
height	number	否	586	卡片高度（像素）
splitMode	string	否	"noSplit"	分割模式 `autoSplit`、`noSplit`,`hrSplit`
mdxMode	boolean	否	false	是否启用 MDX 模式
overHiddenMode	boolean	否	false	是否启用溢出隐藏模式

可用主题列表

中文名称	英文名称	ID	主题的模式ID
苹果备忘录	Apple Notes	apple-notes	light-mode,dark-mode
线圈笔记本	Coil Notebook	coil-notebook	blue-mode,pink-mode,mint-mode,yellow-mode
波普艺术	Pop Art	pop-art	default-mode,pink-blue-mode,mint-mode,purple-mode
字节范	ByteDance	bytedance
阿里橙	Alibaba	alibaba
艺术装饰	Art deco	art-deco
玻璃拟态	Glass Morphism	glassmorphism
温暖柔和	Warm & Soft	warm
简约高级灰	Minimal Gray	minimal
极简黑白	Minimalist B&W	minimalist
梦幻渐变	Dreamy Gradient	dreamy
清新自然	Fresh Nature	nature
紫色小红书	Purple Social	xiaohongshu
笔记本	Notebook	notebook
暗黑科技	Dark Tech	darktech
复古打字机	Vintage Typewriter	typewriter
水彩艺术	Watercolor Art	watercolor
中国传统	Traditional Chinese	traditional-chinese
儿童童话	Children's Fairy Tale	fairytale
商务简报	Business Brief	business
日本杂志	Japanese Magazine	japanese-magazine
赛博朋克	Cyberpunk	cyberpunk
青野晨光	meadow dawn	meadow-dawn

其他自定义主题也可以，指定为自定义主题的 class 类名称，点击主题名称边上的icon可以查看主题的模式ID

响应格式

成功响应

{
  "images": [
    {
      "url": "https://md2crad-1256585691.cos-website.ap-shanghai.myqcloud.com/screenshots/1234567890_abc.png",
      "fileName": "screenshots/1234567890_abc.png"
    }
  ]
}

错误响应

{
  "error": "处理失败",
  "message": "错误详细信息"
}

调用示例

curl -X POST 'https://md2card.cn/api/generate' \
  -H 'x-api-key: 69dc693bf34b45cd9ccbadc9819dd547590edbcab88e472bb9bf45a41562c3fc' \
  -H 'Content-Type: application/json' \
  -d '{
    "markdown": "# Hello World\n md2card api 文档",
    "theme": "apple-notes",
    "width": 440,
    "height": 586
  }'

注意事项

初次调用，可能需要一定的处理时间
生成的图片将被上传到腾讯云 COS，返回可访问的 URL
请求超时时间为 60 秒，如果处理时间过长会返回错误
建议合理设置卡片尺寸，避免生成过大的图片

/api/wechat/convert-and-draft

将 Markdown 文本转换为适合微信公众号的富文本格式，可选择仅返回 HTML 或直接上传到微信草稿箱。

认证方式

使用 API Key 进行认证，需要在请求头中添加 x-api-key 字段。

x-api-key: your_api_key

请求方法

POST

请求参数

请求体为 JSON 格式，包含以下字段：

参数	类型	必填	默认值	说明
markdown	string	否	""	要转换的 Markdown 文本
theme	string	否	"bytedance"	卡片主题样式 ID
coverImageUrl	string	否	""	封面图片的 URL
title	string	否	""	文章标题
author	string	否	""	文章作者
digest	string	否	""	文章摘要
content_source_url	string	否	""	文章来源 URL

可用主题列表

中文名称	英文名称	ID	说明
字节范	ByteDance	bytedance	默认主题
阿里橙	Alibaba	alibaba
笔记本	Notebook	notebook
商务简报	Business Brief	business
日本杂志	Japanese Magazine	japanese-magazine

微信凭证（可选）

需要在请求头中提供微信小程序或公众号的凭证，用于上传图片和创建草稿箱：

Wechat-Appid: your_wechat_appid
Wechat-App-Secret: your_wechat_appsecret

如果不提供以上凭证，API 将仅返回内联 CSS 的 HTML 文本，不会上传到微信。

响应格式

成功响应 - 仅返回HTML

当不提供微信凭证时，返回以下格式：

{
  "success": true,
  "html": "<!DOCTYPE html>...",
  "cost": 1
}

成功响应 - 上传微信草稿箱

当提供微信凭证时，返回以下格式：

{
  "success": true,
  "message": "Draft created successfully!",
  "data": {
    "media_id": "1234567890abcdef",
    "wordCount": 150,
    "cost": 3
  }
}

错误响应

{
  "success": false,
  "error": "错误类型",
  "message": "错误详细信息",
  "cost": 0
}

调用示例

仅获取 HTML

curl -X POST 'https://md2card.cn/api/wechat/convert-and-draft' \
  -H 'x-api-key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "markdown": "# Hello World\n md2card api 文档",
    "theme": "bytedance"
  }'

上传到微信草稿箱

curl -X POST 'https://md2card.cn/api/wechat/convert-and-draft' \
  -H 'x-api-key: your-key \
  -H 'Wechat-Appid:  your-app-key' \
  -H 'Wechat-App-Secret: your-Secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "测试标题",
    "markdown": "# Hello World\n md2card api 文档",
    "theme": "bytedance",
    "coverImageUrl": "https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png"
  }'

积分消耗规则

仅返回 HTML：消耗 1积分
上传微信草稿箱：消耗 3积分

注意：调用 API 前需要确保账户有足够的积分，否则会返回 402 错误。需要至少 3 积分才能调用此 API

注意事项

高级草稿服务响应时间：5-10秒（取决于转换服务和微信服务器响应时间）
必须配置IP白名单，否则会报错：40164 - IP未在白名单中

微信公众号配置

开发者信息配置

微信开发者平台获取开发者ID(AppID)和开发者密码(AppSecret)

IP白名单配置

微信公众号后台 → 设置与开发 → 安全中心 → 配置白名单IP。