当前位置：首页 > news >正文

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

news 2026/8/1 12:15:03

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

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