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

md2card 目前针对私有部署版本，提供了一个 API 接口，可以生成知识卡片图片。

/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

响应格式

成功响应

{
  "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 '<your-domain>/api/generate' \
  -H 'x-api-key: 69dc693bf34b45cd9ccbadc9819dd547590edbcab88e472bb9bf45a41562c3fc' \
  -H 'Content-Type: application/json' \
  -d '{
    "markdown": "# Hello World\nThis is a test",
    "theme": "apple-notes",
    "width": 440,
    "height": 586
  }'

注意事项

分割模式建议不要 autoSplit，会导致渲染慢的情况。
图片生成过程使用 Puppeteer 进行截图，可能需要一定的处理时间
生成的图片将被上传到腾讯云 COS，返回可访问的 URL
请求超时时间为 20 秒，如果处理时间过长会返回错误
建议合理设置卡片尺寸，避免生成过大的图片