代码美化图片接口实践：让代码段快速变成风格统一的文档配图

业务背景：为什么需要“代码美化图片”接口

技术文档和知识库中，代码示例往往以截图形式出现。直接对编辑器截图有几个常见问题：背景带有编辑器主题色，图标和行号混杂，不同作者截出的深浅不一；放大后在 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 对象，常用字段如下：

需要说明的是，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