适用场景
在日常开发与社区写作中，将代码片段以美观的卡片样式分享出去，比纯文本或截图更专业。无论是技术博客配图、社交平台分享，还是团队内部文档，一张带有语法高亮、行号和主题配色的代码卡片都能显著提升可读性。手动制作这类卡片费时费力，而通过API自动化生成则是高效方案。
接口能力边界
本接口接受一段代码文本，返回对应的 SVG 或 PNG 图片（Base64 编码）以及 JSON 元数据。支持的编程语言包括 Python、JavaScript、TypeScript、Rust、Go、Java、C/C++、HTML、CSS、SQL、YAML、Markdown 等 16 种，并内置 8 套视觉主题（极光、日落、森林、午夜、玫瑰、海洋、火山、单色）。输出尺寸和缩放倍数可调，还能选择是否显示行号。注意，单次请求只能处理一段代码，QPS 限制为 3 次/秒，批量场景需控制并发。
鉴权方式
请求头中必须携带Authorization字段，值为 API Key。具体格式为：
Authorization: Bearer <your_api_key>API Key 需要在控制台申请，并妥善保管。每次请求都会校验该参数，缺少或无效时会返回鉴权失败。
curl 接入：快速验证
拿到 API Key 后，最直接的验证方式是用 curl 发送 POST 请求。以下示例将一段 TypeScript 代码渲染为 JSON 格式的卡片元数据（内含 SVG 和 PNG Base64）：
curl -sS \ -X POST \ -H "Authorization: Bearer YOUR_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"请将YOUR_API_KEY替换为实际密钥。如果希望直接获取 SVG，可将output设为"svg"（此时响应 body 就是纯 SVG 字符串）。返回的 JSON 结构包含请求 ID、状态码和数据字段（详见下一节）。
请求参数详解
请求体为 JSON 对象，各字段说明如下：
| 参数名 | 类型 | 必需 | 描述 |
|---|---|---|---|
code | string | 是 | 要美化的代码内容 |
language | string | 否 | 语言标识。可选值：auto/python/javascript/typescript/json/bash/go/rust/java/c/cpp/html/css/sql/yaml/markdown。默认 auto 自动检测 |
theme | string | 否 | 主题名称：aurora/sunset/forest/midnight/rose/ocean/volcano/mono。默认 aurora |
title | string | 否 | 卡片顶部标题，会显示在代码上方 |
line_numbers | number | 否 | 是否显示行号：1 显示，0 不显示。默认 0 |
scale | number | 否 | PNG 缩放倍数，范围 1-4，用于生成高清图。默认 1 |
output | string | 否 | 输出格式：svg（直接返回 SVG 文本）、png（返回 PNG 的 Base64 编码，包含在 JSON 内）、json（返回包含 SVG 和 PNG 的 JSON）。默认 json |
注意：语言和主题的枚举值必须严格匹配，否则可能会 fallback 到默认值或报错。
响应数据结构
成功的 HTTP 状态码为 200，Content-Type 根据output参数不同而变化：
- 当
output=json时，返回 JSON； - 当
output=svg时，直接返回 SVG 文本（Content-Type: image/svg+xml）； - 当
output=png时，返回 JSON，内含 PNG 的 Base64 编码。
以下以 JSON 输出为例，解析关键字段：
{ "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 | int | 状态码，0 表示成功，非 0 表示错误 |
msg | string | 提示信息 |
request_id | string | 请求唯一 ID，可用于排查问题 |
data.title | string | 请求时传入的标题 |
data.language | string | 实际使用的语言标识 |
data.theme | string | 实际使用的主题 key |
data.theme_name | string | 主题中文名称 |
data.line_count | int | 代码行数 |
data.width | int | 生成的图片宽度（像素） |
data.height | int | 生成的图片高度（像素） |
data.svg | string | SVG 源码（有可能被压缩） |
data.png_base64 | string | PNG 图片的 Base64 编码，可直接用于<img>的 src |
常见错误排查
| HTTP 状态码 | 常见原因 | 解决方法 |
|---|---|---|
| 401 | Authorization 头缺失或无效 | 检查 API Key 是否正确，并确保加了 Bearer 前缀 |
| 400 | 请求体 JSON 解析失败或code字段为空 | 验证 JSON 格式，确保code为字符串且非空 |
| 422 | 参数枚举值不合法（如 language 或 theme 拼写错误） | 对照文档中支持的枚举值 |
| 500 | 服务端内部错误 | 携带request_id联系支持团队 |
| 429 | 超过 QPS 限制（3 次/秒） | 降低请求频率，增加间隔或使用队列 |
工程化封装：Python 批量生成卡片
在真实项目中，我们需要将 API 调用封装成可复用的模块。下面给出一个 Python 封装示例，包含自动重试、超时处理和结果缓存：
import requests import time import base64 from typing import Optional class CodeBeautifier: def __init__(self, api_key: str, base_url: str = "https://v1.apizero.cn/api/code-beautify"): self.api_key = api_key self.base_url = base_url self.session = requests.Session() self.session.headers.update({ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" }) def beautify(self, code: str, language: str = "auto", theme: str = "aurora", title: str = "", line_numbers: bool = False, scale: int = 1, output: str = "json", max_retries: int = 3) -> dict: payload = { "code": code, "language": language, "theme": theme, "title": title, "line_numbers": 1 if line_numbers else 0, "scale": scale, "output": output } for attempt in range(max_retries): try: resp = self.session.post(self.base_url, json=payload, timeout=15) if resp.status_code == 200: if output == "svg": return {"success": True, "svg": resp.text} data = resp.json() if data.get("code") == 0: return {"success": True, "data": data["data"]} else: raise Exception(f"API error: {data.get('msg')}") elif resp.status_code == 429: time.sleep(1) continue else: resp.raise_for_status() except Exception as e: if attempt == max_retries - 1: raise time.sleep(0.5 * (attempt + 1)) return {"success": False, "error": "max retries exceeded"} def save_png(self, code: str, filepath: str, **kwargs): result = self.beautify(code, output="json", **kwargs) if not result["success"]: raise RuntimeError(result.get("error")) png_bytes = base64.b64decode(result["data"]["png_base64"]) with open(filepath, "wb") as f: f.write(png_bytes) # 使用示例 if __name__ == "__main__": beautifier = CodeBeautifier(api_key="YOUR_API_KEY") code_snippet = 'def hello():\n print("Hello, World!")\nhello()' # 保存为 PNG 文件 beautifier.save_png(code_snippet, "hello.png", language="python", theme="forest", title="hello.py")该封装类自动处理鉴权、重试、超时，并提供了save_png快捷方法。实际使用时，可以根据项目需求增加并发控制（如使用 asyncio 或线程池），但需注意 QPS 限制。
工程化注意事项
- API Key 安全：不要将密钥硬编码在仓库中，使用环境变量或密钥管理服务。例如在 Python 中读取
os.environ["CODE_BEAUTIFY_KEY"]。 - 错误处理：不仅要处理 HTTP 错误，还要检查接口返回的
code字段。对于 429 限流，采用指数退避重试。 - 输出格式选择：如果只需要 SVG 做渲染，直接使用
output=svg可以减少一次解析；如果需要 PNG 用于离线分享，选择output=json获取 Base64 再解码。 - 图片尺寸计算：返回的
width和height可以帮助定位或裁剪，但注意缩放倍数会影响实际像素（width * scale）。 - 缓存策略：对于相同代码和参数的结果，可以在本地缓存一段时间（例如以代码内容的哈希为 key），减少重复调用。
- 测试环境：建议在测试脚本中先用少量代码验证参数正确性，再批量生产。
参考文档
- 接口详情：https://apizero.cn/aidocs/code-beautify
- 原始技术文档：https://apizero.cn/aidocs/code-beautify/raw.md
（本文中所有接口地址和参数均基于公开文档，请以实际文档为准。）
