业务背景为什么需要“代码美化图片”接口技术文档和知识库中代码示例往往以截图形式出现。直接对编辑器截图有几个常见问题背景带有编辑器主题色图标和行号混杂不同作者截出的深浅不一放大后在 Retina 屏上容易模糊后续如果代码有改动重新截图的维护复杂度也不低。如果团队内部对配图风格没有统一要求散落在文档里的代码图会显得凌乱。一种可行的方案是在文档构建阶段从源码片段生成统一风格的 SVG/PNG 图片再插入 Markdown 页面。这样既能保证视觉一致性也方便批量更新。“代码美化图片”接口就是为解决这类需求提供的提交一段代码和渲染参数返回对应的 SVG 或 PNG 数据。本文记录该接口的接入要点和工程化注意事项。接口能力边界接口定义请求方法POST请求地址https://v1.apizero.cn/api/code-beautify分类开发工具QPS3 / 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 对象常用字段如下参数类型必填说明codestring是要渲染的代码内容languagestring否代码语言默认 autothemestring否主题默认 auroratitlestring否卡片顶部标题line_numbersnumber否是否显示行号1 或 0scalenumber否PNG 放大倍数1 到 4outputstring否输出格式 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 200body 示例{ 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生成图片的宽高。svgSVG 源码可直接写入 .svg 文件。png_base64PNG 图片的 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