代码美化图片接口实践：让代码段快速变成风格统一的文档配图
业务背景：为什么需要“代码美化图片”接口
技术文档和知识库中，代码示例往往以截图形式出现。直接对编辑器截图有几个常见问题：背景带有编辑器主题色，图标和行号混杂，不同作者截出的深浅不一；放大后在 Retina 屏上容易模糊；后续如果代码有改动，重新截图的维护复杂度也不低。
如果团队内部对配图风格没有统一要求，散落在文档里的代码图会显得凌乱。一种可行的方案是：在文档构建阶段，从源码片段生成统一风格的 SVG/PNG 图片，再插入 Markdown 页面。这样既能保证视觉一致性，也方便批量更新。
“代码美化图片”接口就是为解决这类需求提供的：提交一段代码和渲染参数，返回对应的 SVG 或 PNG 数据。本文记录该接口的接入要点和工程化注意事项。
接口能力边界
接口定义：
- 请求方法：POST
- 请求地址：https://v1.apizero.cn/api/code-beautify
- 分类：开发工具
- QPS：3 / s
从文档节选可以看到，它支持 16 种语言的语法高亮，包括 auto、python、javascript、typescript、json、bash、go、rust、java、c、cpp、html、css、sql、yaml、markdown。主题有 aurora、sunset、forest、midnight、rose、ocean、volcano、mono 共 8 套。
输出格式支持 svg、png、json 三种。其中 svg 返回矢量图字符串；png 返回 base64 编码的位图数据；json 则会返回一个包含元数据、svg 和 png_base64 的复合结构。scale 参数控制 PNG 放大倍数，取值 1 到 4。
需要明确的是，该接口单实例 QPS 为 3/s，适合低频的内部工具和文档生成流程，不适合直接暴露给高并发在线服务。如果确有高并发场景，需要在前面增加缓存和队列。
鉴权与请求头
根据事实卡，Header 中需要携带 Authorization，类型为 string。官方文档的 curl 示例使用了 X-API-Key 头，这可能是不同版本的接入方式。建议正式接入时以文档页中的最新说明为准，并注意不要把密钥硬编码到前端页面或公开仓库。
每次请求需要将 API Key 放在请求头中，示例：
-H "X-API-Key: $APIZERO_API_KEY"如果服务端要求 Authorization，则需要改成：
-H "Authorization: Bearer $APIZERO_API_KEY"具体以官方文档为准。
请求参数详解
请求体是一个 JSON 对象，常用字段如下：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 是 | 要渲染的代码内容 |
| language | string | 否 | 代码语言，默认 auto |
| theme | string | 否 | 主题，默认 aurora |
| title | string | 否 | 卡片顶部标题 |
| line_numbers | number | 否 | 是否显示行号，1 或 0 |
| scale | number | 否 | PNG 放大倍数，1 到 4 |
| output | string | 否 | 输出格式 svg/png/json |
需要说明的是，line_numbers 在示例中使用了字符串 "1"，实际类型为 number。接入时建议先按文档示例传字符串或数字，如果收到参数类型错误，再根据返回信息调整。
使用 curl 快速接入
下面是官方示例的 curl 命令。执行前，请将环境变量APIZERO_API_KEY设置为你自己的密钥。
curl -sS \ -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"code": "const sum = (a, b) => a + b;", "language": "typescript", "theme": "aurora", "title": "snippet.ts", "line_numbers": "1", "scale": "2", "output": "json"}' \ "https://v1.apizero.cn/api/code-beautify"命令解析：
-X POST指定请求方法。-H增加请求头，其中 Authorization 或 X-API-Key 用于鉴权。-d是请求体，注意 JSON 内部使用双引号。-sS表示静默模式但显示错误，避免进度条干扰输出。
如果一切正常，接口会返回一个 JSON 对象。若想直接保存 PNG 图片，可以结合jq和base64命令：
curl ... | jq -r '.data.png_base64' | base64 -d > output.png不过这一步依赖返回结构，后续会说明。
响应字段解读
成功时返回 HTTP 200，body 示例：
{ "code": 0, "msg": "成功", "request_id": "req_abc123", "data": { "title": "snippet.ts", "language": "typescript", "theme": "aurora", "theme_name": "极光", "line_count": 3, "width": 680, "height": 180, "svg": "<svg>...</svg>", "png_base64": "iVBORw0..." } }各字段含义：
- code：业务状态码，0 表示成功。
- msg：状态描述。
- request_id：请求 ID，排查问题时回传该值。
- data.title / language / theme：回显输入参数。
- theme_name：主题的中文名称，便于展示。
- line_count：代码行数。
- width / height：生成图片的宽高。
- svg：SVG 源码，可直接写入 .svg 文件。
- png_base64：PNG 图片的 base64 字符串，需要解码后保存。
注意，png_base64中的内容是不含data:image/png;base64,前缀的纯 base64 数据。如果项目中使用<img>标签，需要自行拼接 Data URL。
常见错误排查
这里列出接入过程中可能遇到的问题：
- HTTP 401 / 403：密钥缺失或无效。先检查请求头中是否携带正确密钥，再确认环境变量是否已导出。
- HTTP 400：请求体格式错误。常见原因是 JSON 内缺少
code字段，或语言名不在支持列表内。 - code 非 0：业务侧错误。根据 msg 和 request_id 到文档中匹配错误码。
- QPS 超限：可能收到 429 或限流提示。此时应放慢请求频率，或对相同内容增加缓存。
由于文档节选未给出完整错误码表，具体错误码对应的 HTTP 状态以官方文档页为准。
工程化注意事项
将 base64 保存为图片
在 Python 中，可以这样处理后端返回的 base64 数据：
import base64 import json resp = json.loads(response_text) png_bytes = base64.b64decode(resp["data"]["png_base64"]) with open("snippet.png", "wb") as f: f.write(png_bytes)增加缓存层
由于同一段代码通常会被重复渲染，建议以code + language + theme + scale的哈希作为 key，将图片存入本地磁盘或对象存储。这样能显著减少 API 调用量，也能规避 QPS 限制。
重试与退避
当收到限流或临时错误时，可以使用指数退避。第一次失败后等 1 秒，第二次等待 2 秒，最多重试 3 次。注意不要对 4xx 参数错误做无意义重试。
安全与隐私
代码片段可能包含密钥、内网地址等敏感信息。在发送给外部 API 前，应做脱敏处理，或使用内部私有化部署方案。同时，不要在团队文档中输出未经处理的真实凭据。
参考文档
- 文档页：https://apizero.cn/aidocs/code-beautify
- 原始文档：https://apizero.cn/aidocs/code-beautify/raw.md