一、这个接口解决什么问题
在日常开发中，代码片段往往需要以图片形式出现在技术文档、设计稿、演示文稿或社交分享中。直接截图受限于编辑器背景、字体大小和窗口尺寸，切出来的图片风格参差不齐。代码美化图片接口（POST https://v1.apizero.cn/api/code-beautify）的作用，就是接收一段纯文本代码，返回渲染好的 SVG 或 PNG 卡片图。由服务端统一完成语法高亮、主题配色、行号和标题排版，调用方只需要关心参数与结果的使用。
使用场景大致包括：
- 技术博客配图：将关键代码段渲染成统一风格的插图，提高文章可读性。
- 内部文档系统：团队 Wiki 中的示例代码以图片形式嵌入，避免复制粘贴导致的样式错乱。
- 自动化流水线：在 CI 流程中生成代码海报，用于发布会资料或对外分享材料。
- 课件与演示文稿：讲师批量生成风格一致的代码卡片，提升课件美观度。
二、接口能力边界
在接入之前，需要明确该接口的能力范围与限制：
- 协议与请求方式：仅支持 HTTP POST，请求地址为 https://v1.apizero.cn/api/code-beautify。
- 数据格式：请求体使用 application/json 传输；响应默认也是 JSON。
- 语言支持：内置 16 种语言的高亮规则，包含 auto、python、javascript、typescript、json、bash、go、rust、java、c、cpp、html、css、sql、yaml、markdown。language 参数不传时默认 auto，由服务端自动识别。
- 主题支持：aurora、sunset、forest、midnight、rose、ocean、volcano、mono 共八套主题。
- 输出格式：svc 可直接输出 SVG 文本；png 输出 Base64 编码的 PNG 数据；json 同时返回 SVG 和 PNG 的 Base64、宽高、行数等信息。
- 流量限制：单接口 QPS 为 3，即每秒最多接受 3 次请求。批量场景需要做本地限速或串行排队。
- 请求体大小：素材中没有给出明确上限，建议代码内容控制在常规片段级别，以文档为准。
三、参数详解与鉴权
3.1 Header 参数
根据官方 curl 示例，请求需要携带X-API-Key请求头，值为你的 API Key。接口文档的 Header 参数列为Authorization，类型为 string、必填。两种请求头的具体映射规则以文档页为准，建议接入前先对照 https://apizero.cn/aidocs/code-beautify 确认。
实际开发中，密钥应配置在环境变量或配置中心，避免硬编码进代码仓库。
3.2 请求体字段逐一说明
请求体是一个 JSON 对象，核心字段如下：
| 字段名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| code | string | 是 | 无 | 要渲染的代码原文 |
| language | string | 否 | auto | 语言类型，可选值见上文列表 |
| theme | string | 否 | 由服务端决定 | 主题名，8 选 1 |
| title | string | 否 | 空 | 卡片顶部标题 |
| line_numbers | number | 否 | 以文档为准 | 1 显示行号，0 不显示 |
| scale | number | 否 | 以文档为准 | PNG 放大倍数，取值 1 到 4，仅对 PNG 生效 |
| output | string | 否 | 以文档为准 | svg / png / json |
逐个拆解：
code（必填）：需要渲染的代码字符串。注意在 JSON 中传输时要做好转义，尤其是换行符和双引号。建议使用原始字符串或模板字符串拼接，避免手工拼接多层转义导致语法错误。
language（选填）：明确指定语言可以避免 auto 识别偏差，尤其是在代码较短、关键字不明显的时候。例如一行const x = 1在 auto 模式下可能被识别成 JavaScript，而指定typescript后高亮规则更精确。如果你传了"java"但代码实际是 Kotlin，高亮效果也会打折扣，所以尽量保证语言参数与代码内容一致。
theme（选填）：8 套主题的视觉差异比较大，建议团队内部选定一套固定值，保持输出图片风格统一。素材中给出了示例主题 aurora，响应中对应 theme_name 为“极光”。
title（选填）：显示在卡片顶部的标题，一般传入文件名，如snippet.ts、main.go。如果不需要标题，可以不传或传空字符串。
line_numbers（选填）：值为数字 1 或 0。素材示例里传的是字符串"1"，但字段类型标注为 number。这里需要留意：如果服务端按严格 JSON Schema 校验，应传数字 1；如果做了宽松解析，传字符串也能工作。建议按文档声明的 number 类型传数字，减少歧义。
scale（选填）：PNG 放大倍数，范围 1-4。SVG 是矢量格式，不存在分辨率问题，因此该参数主要影响 PNG 输出的像素密度。在 Retina 屏或高清打印场景下可以设 2 或 3。假设一行代码在 1 倍缩放下渲染高度只有 20px，设 2 倍后输出图片高度会随之翻倍，适合直接用于 PPT 或印刷材料。
output（选填）：三个可选值 svg、png、json。选 json 可以同时拿到 SVG 文本、PNG 的 Base64 与元信息，适合需要二次处理的场景。
四、curl 接入示例
下面是一个完整的 curl 请求，使用 json 输出格式，方便同时观察 SVG 与 PNG 数据：
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"注意：
$APIZERO_API_KEY需要替换为你自己的有效密钥，建议在 shell 中先执行export APIZERO_API_KEY=xxx。- 示例中
line_numbers传的是数字 1，没有加引号。 - 如果代码内容中包含单引号，建议将请求体写入临时文件，使用
-d @payload.json方式提交，避免 shell 转义问题。
需要 PNG 时，将响应中的png_base64字段解码后写入文件即可。需要 SVG 时，直接用data.svg字段即可。
五、返回值解读
一个成功的响应示例（output=json）：
{ "code": 0, "data": { "height": 180, "language": "typescript", "line_count": 3, "png_base64": "iVBORw0...", "svg": "<svg>...</svg>", "theme": "aurora", "theme_name": "极光", "title": "snippet.ts", "width": 680 }, "msg": "成功", "request_id": "req_abc123" }字段解读：
| 字段 | 类型 | 说明 |
|---|---|---|
| code | number | 业务状态码，0 表示成功 |
| msg | string | 状态描述 |
| request_id | string | 本次请求的唯一标识，排查问题时带上它 |
| data.width / data.height | number | 生成图片的像素宽高 |
| data.line_count | number | 渲染出的代码行数 |
| data.language | string | 实际使用的语言 |
| data.theme | string | 实际使用的主题 key |
| data.theme_name | string | 主题中文名称 |
| data.svg | string | SVG 的 XML 文本 |
| data.png_base64 | string | PNG 图片的 Base64 编码 |
| data.title | string | 卡片标题 |
当 output 为 svg 时，data.png_base64 可能为空；当 output 为 png 时，data.svg 可能为空。需要根据请求参数组合做相应的判空处理。
六、常见错误与排查
结合接口特性，以下几类问题比较常见：
- 401/403 鉴权失败：
X-API-Key头缺失、密钥无效或格式不对。先打印请求头确认是否带上了对应字段。 - 400 参数校验失败：code 为空、language 不在枚举内、scale 超出 1-4 范围、output 不是 svg/png/json。逐一核对字段类型，特别注意
line_numbers的 number 类型。 - 代码内容转义错误：JSON 中的换行、引号处理不当导致请求体非法。建议用 Python 的
json.dumps或 JavaScript 的JSON.stringify生成请求体。 - 超时或限流：QPS 为 3，如果循环调用速度过快，可能触发限流。增加本地重试与退避逻辑，每次调用间隔建议不低于 350ms。
- base64 转图片失败：部分语言库在解码 Base64 时要求无换行，可以先过滤掉字符串中的换行符再解码。
七、工程化注意事项
7.1 批量生成时的限速
QPS 上限 3，意味着连续请求必须串行化控制。简单做法是使用信号量或队列，每个请求之间 sleep 400ms；也可以引入令牌桶，按每秒 3 个令牌的速率放行。不要在无限速的情况下用 for 循环直接打满，避免触发限流。
7.2 缓存设计
同一段代码、同一个参数组合，渲染结果是确定性的。建议以请求参数的哈希值作为缓存 key，把 svg/png 结果缓存到本地文件或 Redis。相同内容的渲染请求可以直接命中缓存，减少 API 调用量。例如：
import hashlib import json def cache_key(payload: dict) -> str: raw = json.dumps(payload, sort_keys=True, ensure_ascii=False) return hashlib.sha256(raw.encode("utf-8")).hexdigest()7.3 密钥管理
API Key 属于敏感信息，不要写进前端代码或公开仓库。建议放在环境变量、KMS 或配置中心，服务端调用时再从环境读取。
7.4 代码内容长度
素材未给出请求体大小上限。为了避免请求失败，典型代码片段建议控制在几十行到一两百行以内。若有超长内容的需求，可联系服务方确认上限，或拆分成多个片段分别渲染。
7.5 图片落盘
对于 PNG 输出，拿到的 base64 需要解码后写文件：
import base64 def save_png(b64_text: str, path: str) -> None: data = base64.b64decode(b64_text.replace("\n", "")) with open(path, "wb") as f: f.write(data)参考文档
- 接口文档页: https://apizero.cn/aidocs/code-beautify
- 原始文档 Markdown: https://apizero.cn/aidocs/code-beautify/raw.md
