代码美化图片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字段需要包含完整的代码文本，如果代码中包含特殊字符（如双引号），请确保在 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。

data对象中的字段：

注意：当output为json时，data.svg和data.png_base64都会返回，方便开发者同时获取两种格式。

常见错误处理

工程化封装注意事项

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