代码美化图片API：从curl调试到工程化封装实践
适用场景
在日常开发与内容创作中，程序员经常需要将代码片段以美观、高可读的形式分享出去。无论是技术博客的配图、社交媒体的代码贴，还是项目文档中的示例截图，一张带有语法高亮和设计主题的代码图片往往比纯文本更有吸引力。然而手动截图存在分辨率低、背景不统一、无法快速批量处理等痛点。代码美化图片 API 提供了一种编程化的解决方案：开发者只需提交代码内容及相关配置，即可获得 SVG 或 PNG 格式的精致代码卡片。
典型场景包括：
- 自动生成技术文章的代码插图，实现发布流水线中“代码→图片”的自动化。
- 构建在线代码分享工具，让用户粘贴代码后一键生成分享图。
- 在 CI/CD 流程中为代码片段生成截图，用于测试报告或代码审查摘要。
接口能力边界
在使用前需要明确该 API 的能力范围与限制：
- 输入：支持 16 种编程语言的语法高亮（auto、python、javascript、typescript、json、bash、go、rust、java、c、cpp、html、css、sql、yaml、markdown）。如果选择
auto，接口会尝试自动识别语言。 - 输出：支持 SVG、PNG 或 JSON 三种格式。SVG 可缩放且可被文本编辑器修改；PNG 适合直接在社交平台展示；JSON 格式返回包含图片 base64 以及元数据，方便前端直接解码并渲染。
- 主题：内置 8 套设计主题（aurora/sunset/forest/midnight/rose/ocean/volcano/mono），每套主题有对应的配色方案，适用于不同的展示背景。
- 性能：QPS 限制为 3 次/秒，适合中等规模的调用需求。如果需要进行批量处理，建议在客户端控制请求频率或使用队列机制。
- 缩放：通过
scale参数可以控制 PNG 的放大倍数（1-4），用于适配 Retina 屏幕或高清印刷需求。SVG 输出不受此参数影响。
请求参数与鉴权
鉴权方式
接口采用 API Key 鉴权，需要在请求头中携带Authorization字段，值为Bearer <your_api_key>。API Key 需要从 API 管理后台获取，请妥善保管，不要泄露到公开仓库或客户端代码中。
请求体字段
请求体是一个 JSON 对象，各字段说明如下：
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | 是 | 要渲染的代码文本内容 |
language | string | 否 | 编程语言（默认 auto），可选值见上文 |
theme | string | 否 | 设计主题（默认 aurora） |
title | string | 否 | 卡片顶部显示的标题 |
line_numbers | number | 否 | 是否显示行号：1 显示，0 不显示（默认 1） |
scale | number | 否 | PNG 放大倍数（1-4，默认 2） |
output | string | 否 | 输出格式：svg / png / json（默认 json） |
注意：code字段需要包含完整的代码文本，如果代码中包含特殊字符（如双引号），请确保在 JSON 中进行正确的转义。
curl 调试示例
以下是一个完整的可复制 curl 命令，请在运行前将$APIZERO_API_KEY替换为您的实际 API Key：
curl -sS \ -X POST \ -H "Authorization: Bearer $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "function factorial(n) {\n if (n <= 1) return 1;\n return n * factorial(n - 1);\n}", "language": "javascript", "theme": "midnight", "title": "factorial.js", "line_numbers": 1, "scale": 2, "output": "json" }' \ "https://v1.apizero.cn/api/code-beautify"服务器返回的 JSON 示例（已省略二进制部分）：
{ "code": 0, "msg": "成功", "request_id": "req_a1b2c3d4", "data": { "height": 260, "language": "javascript", "line_count": 4, "png_base64": "iVBORw0KGgoAAAANSUhEUg...", "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" ...>...</svg>", "theme": "midnight", "theme_name": "午夜", "title": "factorial.js", "width": 720 } }若只想获取 SVG 原始字符串，可将output设为svg，此时data.svg字段即为完整的 SVG 内容。若设为png，则data.png_base64为 Base64 编码的 PNG 图片数据。
返回值字段解读
响应体结构固定为 JSON 对象，顶级包含code、msg、request_id和data。
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务状态码，0 表示成功 |
msg | string | 提示信息，成功时为“成功”，失败时描述错误原因 |
request_id | string | 唯一请求标识，用于排查问题 |
data | object | 返回内容，包含以下子字段 |
data对象中的字段：
| 字段 | 类型 | 说明 |
|---|---|---|
svg | string | SVG 代码字符串（仅 output 为 svg 或 json 时返回） |
png_base64 | string | PNG 图片的 Base64 编码（仅 output 为 png 或 json 时返回） |
width | int | 生成图片的宽度（像素） |
height | int | 生成图片的高度（像素） |
language | string | 实际使用的编程语言 |
line_count | int | 代码行数 |
theme | string | 实际使用的主题标识 |
theme_name | string | 主题的中文名称 |
title | string | 卡片标题 |
注意：当output为json时，data.svg和data.png_base64都会返回，方便开发者同时获取两种格式。
常见错误处理
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| 返回 401 | Authorization 头缺失或 API Key 无效 | 检查 API Key 是否正确，确认请求头格式为Bearer <key> |
| 返回 400，msg 为“缺少必填参数” | code字段未提供或为空 | 确保 JSON 中包含非空code字段 |
| 返回 400，msg 为“不支持的语言” | language值不在允许列表内 | 使用自动识别auto或查阅文档确认支持的语言 |
| 返回 400，msg 为“不支持的输出格式” | output值不是 svg/png/json | 检查输入值 |
| 返回 429 | 超出 QPS 限制（3次/秒） | 降低请求频率，或在客户端实现退避重试 |
| 响应 code 非 0 | 业务逻辑错误，msg 会给出详情 | 根据 msg 调整请求参数 |
| 生成的图片中代码排版错乱 | 代码中混有 Tab 或不规范的缩进 | 建议在提交前将 Tab 替换为空格，或使用统一缩进 |
工程化封装注意事项
1. 封装 SDK 或函数
在生产环境中不应直接拼接 curl 命令，而应将其封装在编程语言的 HTTP 客户端中。下面以 Node.js 为例展示一个通用封装：
// beautifyCode.js import axios from 'axios'; // 或使用原生的 fetch const API_URL = 'https://v1.apizero.cn/api/code-beautify'; const API_KEY = process.env.APIZERO_API_KEY; /** * 美化代码为图片数据 * @param {Object} options * @param {string} options.code - 代码内容 * @param {string} [options.language='auto'] - 编程语言 * @param {string} [options.theme='aurora'] - 主题 * @param {string} [options.title] - 标题 * @param {number} [options.lineNumbers=1] - 是否显示行号 * @param {number} [options.scale=2] - 缩放倍数 * @param {'json'|'svg'|'png'} [options.output='json'] - 输出格式 * @returns {Promise<Object>} 包含图片数据的对象 */ export async function beautifyCode(options) { const { code, language = 'auto', theme = 'aurora', title, lineNumbers = 1, scale = 2, output = 'json' } = options; const response = await axios.post(API_URL, { code, language, theme, title, line_numbers: lineNumbers, scale, output }, { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' } }); if (response.data.code !== 0) { throw new Error(`API error: ${response.data.msg}`); } return response.data.data; }2. 错误重试与退避
对于网络波动或瞬时的 429 限流，建议实现指数退避重试。重试次数不宜过多（2-3次即可），且应记录日志以便后续排查。
3. 缓存策略
对于相同代码内容、相同参数的请求，输出结果通常是确定的（SVG 内容一致，PNG 由于缩放可能相同）。可以在客户端建立缓存，key 为代码内容的哈希值加上参数组合，有效期视业务需求而定。这能显著降低 API 调用量，同时提升响应速度。
4. 处理大代码段
接口对代码长度有一定限制（具体以文档为准）。如果代码超过 500 行，建议拆分为多个片段分别生成，或只选取关键部分。另外，过长的代码会增加图片宽度和高度，可能导致生成的图片在社交媒体上展示不全，可以通过限制输出尺寸或使用缩放参数来优化。
5. 环境变量管理
API Key 不应硬编码在代码中，应通过环境变量或配置中心注入。在 Node.js 中可以使用process.env，在 Python 中可以使用os.environ。对于本地开发，可使用.env文件管理，但不要将其提交到版本控制。
6. 输出格式选择
- 若需要后续编辑（如修改字体、添加水印），推荐使用 SVG，因为 SVG 是纯文本格式，可用 DOM 操作或字符串替换进行处理。
- 若需要直接嵌入到 Markdown 或 HTML 中展示，PNG 的 Base64 数据 URI 格式非常方便：
<img src="data:image/png;base64,..." />。 - 若需要同时保存多个信息（如代码行数、语言等），JSON 格式可以一并返回元数据。
参考文档
- 官方文档：https://apizero.cn/aidocs/code-beautify
- 原始文档（Markdown）：https://apizero.cn/aidocs/code-beautify/raw.md