适用场景在日常开发中经常需要在技术博客、社交媒体或项目文档中展示代码片段。普通的文本复制粘贴往往缺乏视觉吸引力而使用截图工具手动截取又存在分辨率低、无法高亮语法、无法统一风格等问题。代码美化图片 API 可以将代码片段渲染为精美的 SVG 或 PNG 卡片图片支持多种编程语言语法高亮和多套主题非常适合用于社交分享和文档配图。接口能力边界请求方法POST请求地址https://v1.apizero.cn/api/code-beautifyQPS 限制3 次/秒输出格式SVG、PNG通过 base64 返回、JSON包含元数据支持语言auto、python、javascript、typescript、json、bash、go、rust、java、c、cpp、html、css、sql、yaml、markdown共 16 种主题aurora极光、sunset日落、forest森林、midnight午夜、rose玫瑰、ocean海洋、volcano火山、mono单色附加功能可选行号、自定义标题、PNG 缩放倍数1~4需要注意的是该接口仅接受 JSON 格式的请求体且必须提供有效的 API Key 用于鉴权。由于 QPS 只有 3不适合高频大量调用建议在应用层做好请求频率控制或批量任务排队。请求参数详解Header 鉴权参数名类型必填说明Authorizationstring是用于身份验证的 API Key通常格式为Bearer YOUR_API_KEY或直接传递密钥值具体以提供方要求为准在 curl 中可通过-H Authorization: Bearer YOUR_API_KEY设置。请求体JSON Object字段名类型必填说明codestring是需要美化的代码内容支持多行字符串languagestring否编程语言标识默认 auto自动检测。支持列表见上文themestring否主题名称默认为 auroratitlestring否卡片顶部显示的标题通常为文件名line_numbersnumber否是否显示行号1 显示0 隐藏默认 1scalenumber否PNG 输出时的缩放倍数范围 1~4默认 2。仅 output 为 png 或 json 时生效outputstring否返回格式svg、png、json默认为 svg请求体示例{ code: const sum (a, b) a b;, language: typescript, theme: aurora, title: snippet.ts, line_numbers: 1, scale: 2, output: json }curl 接入示例以下 curl 命令展示了如何调用接口并获取返回的 JSON 元数据包含 SVG 和 PNG base64。记得将YOUR_API_KEY替换为实际的密钥。curl -sS \ -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { code: def hello(name):\n print(f\Hello, {name}!\), language: python, theme: ocean, title: hello.py, line_numbers: 1, scale: 2, output: json } \ https://v1.apizero.cn/api/code-beautify成功时返回的 JSON 中data.svg字段包含完整的 SVG 字符串可直接插入 HTML 页面data.png_base64字段包含 PNG 图片的 base64 编码数据不含 data:image/png;base64, 前缀可用于直接显示或保存。如果需要只获取 SVG可将output设为svg此时响应头Content-Type为image/svgxml响应体直接是 SVG 源代码。Python 代码接入在实际工程中使用 Python 发起请求更为便捷。以下是一个封装函数示例import requests import json def beautify_code(code, languageauto, themeaurora, title, line_numbers1, scale2, outputjson, api_keyYOUR_API_KEY): url https://v1.apizero.cn/api/code-beautify headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { code: code, language: language, theme: theme, title: title, line_numbers: line_numbers, scale: scale, output: output } resp requests.post(url, headersheaders, jsonpayload) resp.raise_for_status() if output svg: return resp.text else: return resp.json() # 使用示例 code_snippet import React from react; const App () divHello/div; export default App; result beautify_code(code_snippet, languagejavascript, thememidnight, titleApp.jsx) if result[code] 0: svg_content result[data][svg] # 保存为 SVG 文件 with open(code_card.svg, w, encodingutf-8) as f: f.write(svg_content) print(SVG 卡片已保存到 code_card.svg) else: print(错误, result[msg])返回字段解读当output为json时成功响应体结构如下{ code: 0, msg: 成功, request_id: req_abc123, data: { svg: svg.../svg, png_base64: iVBORw0..., width: 680, height: 180, language: typescript, theme: aurora, theme_name: 极光, line_count: 3, title: snippet.ts } }字段类型说明codenumber业务状态码0 表示成功非 0 表示错误msgstring状态描述信息request_idstring请求唯一标识可用于问题排查data.svgstring渲染后的 SVG 字符串data.png_base64stringPNG 图片的 base64 编码不含 data URI 前缀data.widthnumber卡片宽度像素data.heightnumber卡片高度像素data.languagestring实际使用的语言标识data.themestring使用的主题名称data.theme_namestring主题中文名称data.line_countnumber代码行数data.titlestring卡片标题若output为svg则响应体直接为 SVG 源码不带 JSON 包裹。常见错误与处理错误场景可能原因排查建议HTTP 401API Key 无效或未传递检查Authorization头格式是否正确密钥是否过期HTTP 400请求体格式错误或缺少必填字段确认code字段已提供JSON 结构合法HTTP 429请求频率超过 QPS 限制降低请求速度增加间隔或使用队列code 非 0业务逻辑错误如语言不支持、代码过长检查返回的msg字段调整参数后重试此外若代码内容包含特殊字符或过长的行可能导致渲染异常。建议代码单行长度不超过 120 字符总行数控制在 100 行以内以保证卡片显示效果。工程化注意事项API Key 安全存储切勿将密钥硬编码在客户端代码或公开仓库中。推荐使用环境变量或密钥管理服务。频率控制QPS 为 3实际调用时应在客户端添加限流逻辑如令牌桶避免触发 429。缓存策略对于相同的代码内容如果主题、语言等参数不变可以缓存生成的 SVG/PNG减少重复请求。错误重试对于 429 或 5xx 错误可以实现指数退避重试机制但注意不要超过频率限制。输出选择若只需在 Web 页面展示推荐使用outputsvg直接获取矢量图缩放不失真且文件较小。若需要位图用于社交媒体则选择outputjson并提取png_base64转为文件。多语言支持接口支持 auto 自动检测但在特定场景下建议显式指定语言以避免误判。测试环境开发阶段可使用简单的 curl 命令快速验证参数效果稳定后再集成到正式项目。参考文档接口文档https://apizero.cn/aidocs/code-beautify原始 Markdownhttps://apizero.cn/aidocs/code-beautify/raw.md注意文档链接仅供参考接口细节以官方最新说明为准。
