# 技术支持 (/docs/contact-us) 为了能更好地与客户交流，同时更高效地优化我们的产品，我们建立了客户交流群，如果您有任何使用上的问题障碍或者建议，欢迎扫码和我们交流。在线客服 [#在线客服] 你也可以点击网站右下角的聊天窗口，或下面的按钮，直接与我们对话。工作时间内我们会尽快回复。微信 [#微信] 请添加微信，并备注：“imgrender” hacker neo

# 接入必读 (/docs/api/basic) 基础 URL [#基础-url] Imgrender 的 API 是围绕 REST 组织的。我们的 API 具有可预测、面向资源的 URL。 imgrender 所有 API 都以以下 URL 作为基础： ```bash https://api.imgrender.net/open/ ``` 推荐接口 [#推荐接口] 生产环境推荐使用 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")：先在 [模板编辑器](/playground "打开模板编辑器") 中设计并发布模板，再传入变量生成图片。如需每次传入完整 JSX/HTML、不使用已保存模板，可使用 [基于 JSX/HTML 生成图片 API](/docs/api/generate-image "基于 JSX/HTML 生成图片 API")。需要生成静态二维码时，可使用 [二维码 API](/qrcode-api "二维码 API")：通过 URL query 直接返回 PNG / SVG / Base64，无需鉴权。数据格式 [#数据格式] 所有 HTTP 请求头部的 `Content-Type` 类型为 `application/json`。所有请求和响应内容的格式均为 `JSON`。所有的请求 URL 和请求包体内容都区分大小写。认证方式 [#认证方式] imgrender 使用 `API Key` 对请求进行鉴权。请在所有请求的请求头中添加鉴权字段： ``` X-API-Key: 你的 API Key ``` API Key 的获取方式请参考 [API Keys 管理](/docs/dashboard/api-key "查看 API Keys 管理文档") 版本控制 [#版本控制] imgrender 采用语义化版本号表示 API 的版本，例如 `v1`、`v2`。版本号位于 URL Path 中，包含版本号的完整 URL 示例： ``` https://api.imgrender.net/open/v1/ ``` imgrender 会尽力保证 API 的兼容性： * API 变更是兼容的，则 API 版本号不变。 * API 变更无法兼容时，则会新增版本号，并在一定时间范围内保留旧版本 API。例如：`v1 -> v2` # 基于模板生成图片（推荐） (/docs/api/generate-image-by-template) 通过该接口，你可以使用在 imgrender 控制台或 [模板编辑器](/playground "打开模板编辑器") 中创建并发布的模板，传入变量值后同步生成图片。服务端会加载模板内容，校验变量并完成渲染，最终返回图片的 CDN 访问链接。这是生产环境推荐的调用方式：在模板编辑器中完成模板设计并发布后，请求时只需传入变量，不必每次提交完整 JSX/HTML。尚未创建模板时，请先阅读 [快速开始](/docs "快速开始") 和 [模板开发指南](/docs/template-guide/overview "模板开发指南")。变量写法见 [变量](/docs/template-guide/variables "变量")。请求 [#请求] 请求方法与 URL [#请求方法与-url] ``` POST https://api.imgrender.net/open/v1/images/templates/{id}/render ``` 其中 `{id}` 为模板 ID，可在控制台模板详情页获取。请求头参数 [#请求头参数] | 字段 | 数据类型 | 必填 | 描述 | | :----------: | :----: | :-: | -------------------------------------------------- | | X-API-Key | string | yes | 用于请求授权，请参考 [请求认证方式](/docs/api/basic "查看 API 认证方式") | | Content-Type | string | yes | **固定值**："application/json; charset=utf-8" | 路径参数 [#路径参数] | 字段名 | 类型 | 必填 | 描述 | | ---- | :----: | :---: | ------------ | | `id` | string | **是** | 模板 ID（路径中填写） | 请求体参数 [#请求体参数] | 字段名 | 类型 | 必填 | 描述 | 默认值 | | ----------- | --------- | ----- | -------------------------------------- | ------- | | `variables` | `object` | **是** | 变量名到值的映射。模板中定义的变量会按名称替换，未命中定义的变量会被忽略。 | - | | `width` | `number` | 否 | 覆盖模板默认输出宽度（像素） | - | | `height` | `number` | 否 | 覆盖模板默认输出高度（像素） | - | | `format` | `string` | 否 | 覆盖模板默认输出格式，可选值 `png`、`jpeg`、`webp` | - | | `quality` | `number` | 否 | 覆盖模板默认图片质量（0-100），仅 `jpeg`、`webp` 格式有效 | - | | `useDraft` | `boolean` | 否 | 是否使用草稿内容渲染。默认使用已发布内容。建议仅在调试时使用草稿内容。 | `false` | * 模板必须先完成发布；若模板未发布或已归档，接口会返回 `409`。 * 如需每次传入完整 JSX/HTML、不使用已保存模板，请使用 [基于 JSX/HTML 生成图片 API](/docs/api/generate-image "基于 JSX/HTML 生成图片 API")。响应 [#响应] 当请求成功时，HTTP 状态码为 `200`，并且会以 JSON 格式返回数据： ```json { "code": 0, "message": "ok", "data": { "url": "https://res.imgrender.net/6e31cfcd683a36d0522a8cc34e244379.jpg?sign=xxx" } } ``` * `code`：错误码，当错误码为 `0` 时，表示处理成功，其他值表示存在一定的问题。 * `message`：提示信息，与 `code` 相对应，更多提示信息可查看 [状态码与错误码](/docs/api/status-code "状态码与错误码")。 * `data`：返回的数据。当 `code` 为 `0` 时返回，其中 `url` 为图片链接。图片链接的**有效期为 5 分钟**，请及时下载或展示图片。超时后，重新请求即可获取新的访问链接。示例 [#示例] 下面是一个完整的请求示例，展示了如何基于模板 ID 传入变量并生成图片： ```bash curl -X POST https://api.imgrender.net/open/v1/images/templates/tpl_xxx/render \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "variables": { "title": "周末抽奖活动", "nickname": "Davinci", "avatar": "https://example.com/avatar.jpg" }, "format": "png", "quality": 90 }' ``` ```javascript const payload = { variables: { title: '周末抽奖活动', nickname: 'Davinci', avatar: 'https://example.com/avatar.jpg', }, format: 'png', quality: 90, } fetch('https://api.imgrender.net/open/v1/images/templates/tpl_xxx/render', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY', }, body: JSON.stringify(payload), }) .then((res) => res.json()) .then((result) => console.log('图片链接：', result.data.url)) ``` 错误码 [#错误码] | 错误码 | HTTP 状态码 | 说明 | 排查建议 | | ------- | -------- | --------------- | ------------------------------- | | `10103` | `400` | 参数错误或变量校验失败 | 请根据提示信息检查 `variables` 等请求参数 | | `10104` | `401` | API Key 认证失败 | 检查 API Key 是否设置正确或 API Key 是否有效 | | `20105` | `403` | 图片生成失败 | 请根据提示信息处理；常见为模板渲染异常 | | `30101` | `403` | 无有效资源包 | 请检查资源包是否充足或已过期 | | - | `409` | 模板未发布、已归档或草稿不可用 | 请确认模板已发布，或关闭 `useDraft` 后重试 | 更多通用错误码见：[状态码与错误码](/docs/api/status-code "状态码与错误码") # 蓝图 - 描述图片内容 (/docs/api/generate-image-v1/blueprint) “蓝图”是旧版接口专用的内容协议，不再新增功能。我们强烈建议您迁移至 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")。推荐在 [模板编辑器](/playground "打开模板编辑器") 中用 JSX/HTML 设计模板并定义变量，发布后只需传入变量即可生成图片： * **基于 JSX/HTML 编写模板**：直接使用前端熟悉的标签结构，告别复杂的“蓝图” JSON 协议。 * **现代样式支持**：全面支持内联样式（`style`）和 Tailwind CSS 类名快速排版。 * **支持变量和条件渲染**：可简化请求时需要传入的数据。 * **多格式导出**：支持灵活导出高质量的 WebP、PNG 和 JPEG 图片格式。 imgrender 可通过特定的 JSON 数据描述图片内容，我们称之为“蓝图”。蓝图决定了如何渲染图片与图片有什么内容。下面将详细介绍“蓝图”的属性与组成。蓝图 [#蓝图] 蓝图完整描述了图片的规格与图片中的内容。具体属性如下： | 字段名 | 数据类型 | 默认值 | 必需 | 描述 | | :---------------------: | :------------: | :-----: | :-: | ------------------------------------------------------------------------------------ | | width | int | | yes | 图片宽度，内容不能超过此宽度，**最大值 1100**。 | | height | int | | yes | 图片高度，内容不能超过此高度，**最大值 2480**。 | | backgroundColor | Hex Color Code | | yes | 图片背景颜色，须为十六进制颜色代码 | | borderColor | Hex Color Code | #000000 | | 四条边框颜色 | | borderWidth | int | 0 | | 四条边框宽度。边框宽度一半在内部，一半在外，暂不支持调整。 | | borderRadius | int | 0 | | 边框四个顶点圆角半径 | | borderTopLeftRadius | int | 0 | | 边框左上角顶点圆角半径，优先级高于 `borderRadius` | | borderTopRightRadius | int | 0 | | 边框右上角顶点圆角半径，优先级高于 `borderRadius` | | borderBottomLeftRadius | int | 0 | | 边框左下角顶点圆角半径，优先级高于 `borderRadius` | | borderBottomRightRadius | int | 0 | | 边框右下角顶点圆角半径，优先级高于 `borderRadius` | | texts | Array | \[] | | 图片中的文字内容，详见 [文本组件](/docs/api/generate-image-v1/blueprint#文本 "文本组件") | | images | Array | \[] | | 图片中的图像内容，可以将外部图片渲染到新图片上，详见[图片组件](/docs/api/generate-image-v1/blueprint#图片 "图片组件") | | lines | Array | \[] | | 图片中的线段，可用于渲染一些分界线，详见[线段组件](/docs/api/generate-image-v1/blueprint#线段 "线段组件") | | qrcodes | Array | \[] | | 图片中的二维码内容，可以在图片上渲染二维码内容，详见[二维码组件](/docs/api/generate-image-v1/blueprint#二维码 "二维码组件") | | blocks | Array | \[] | | 图片中的矩形，详见[矩形组件](/docs/api/generate-image-v1/blueprint#矩形 "矩形组件") | 示例 [#示例] ``` { "width": 640, "height": 1050, "backgroundColor": "#d75650", "blocks": [ { "x": 15, "y": 268, "width": 610, "height": 770, "backgroundColor": "#fff", "borderColor": "#fff" } ], "texts": [ { "x": 320, "y": 185, "text": "Davinci Li", "font": "jiangxizhuokai", "fontSize": 22, "color": "#fff", "width": 320, "textAlign": "center", "zIndex": 1 }, { "x": 320, "y": 220, "text": "邀请你来参加抽奖", "font": "jiangxizhuokai", "fontSize": 22, "color": "#fff", "width": 320, "textAlign": "center", "zIndex": 1 }, { "x": 30, "y": 640, "text": "奖品: 本田-CB650R 摩托车", "font": "jiangxizhuokai", "fontSize": 22, "color": "#000", "width": 580, "textAlign": "left", "zIndex": 1 }, { "x": 30, "y": 676, "text": "01 月 31 日 18:00 自动开奖", "font": "jiangxizhuokai", "fontSize": 18, "color": "#9a9a9a", "width": 580, "textAlign": "left", "zIndex": 1 }, { "x": 320, "y": 960, "text": "长按识别二维码，参与抽奖", "font": "jiangxizhuokai", "fontSize": 22, "color": "#9a9a9a", "width": 580, "textAlign": "center", "zIndex": 1 } ], "lines": [ { "startX": 30, "startY": 720, "endX": 610, "endY": 720, "width": 1, "color": "#E1E1E1", "zIndex": 1 } ], "images": [ { "x": 248, "y": 25, "width": 120, "height": 120, "url": "https://img-chengxiaoli-1253325493.cos.ap-beijing.myqcloud.com/bikers_327390-13.jpg", "borderRadius": 60, "zIndex": 1 }, { "x": 108, "y": 285, "width": 400, "height": 300, "url": "https://img-chengxiaoli-1253325493.cos.ap-beijing.myqcloud.com/cb650R.jpeg", "zIndex": 1 } ], "qrcodes": [ { "x": 208, "y": 726, "size": 200, "content": "http://weixin.qq.com/r/yRzk-JbEbMsTrdKf90nb", "foregroundColor": "#000", "backgroundColor": "#fff", "zIndex": 1 } ] } ``` 下面将详细介绍描述图片内容的各类组件。坐标系 [#坐标系] 在学习各类组件之前，需要先了解与图片元素的位置有关的重要概念：坐标系。 imgrender 采用的坐标系为： * 左上角为`全局坐标原点(0,0)`。 * 从左至右为 X 轴，从上至下为 Y 轴 * 单位为像素（px）。 imgrender-坐标系示意

文本 [#文本] 文本组件可以向图片中添加文字内容。具体属性如下：属性 [#属性] | 字段名 | 数据类型 | 默认值 | 必需 | 描述 | | :---------: | :----: | :--------------------: | :-: | ------------------------------------------ | | x | int | | yes | 文本 X 坐标 | | y | int | | yes | 文本 Y 坐标 | | text | string | | yes | 文本内容 | | width | int | | yes | 文本宽度，决定了文本的最大显示宽度，当文字内容超过宽度，会自动换行 | | font | string | SourceHanSansSC-Normal | | 选择文本渲染使用的字体，参考 [字体](#字体 "字体") | | fontSize | int | 18 | | 文字大小，单位为 pt | | lineHeight | int | 字体基础高度 | | 文本行高，不能小于`fontSize` | | lineSpacing | float | 1 | | 行距倍数，`lineSpacing * fontSize = lineHeight` | | color | Array | #000000 | | 文本颜色 | | textAlign | string | `left` | | 文本水平对齐方式，可选值有：`left`、`center`、`right` | | zIndex | int | 0 | | 渲染层级，会影响同一位置不同内容的覆盖情况 | 定位锚点 [#定位锚点] 属性`textAlign`会影响文本的定位锚点。 imgrender 文本组件

如上图所示，虚线框为文字展示宽与行高。文本`奖品：本田-CB650R`的 `textAlign` 属性值为`left`，则锚点在文本的「左上角」。文本 `长按识别二维码，参与抽奖` 的 `textAlign` 属性值为 `center`，则锚点在文本「中上」位置。文本 `Davinci Li` 的 `textAlign` 属性值为 `right`，则锚点在文本「右上角」。字体 [#字体] 目前暂不支持使用自定义字体。imgrender 目前提供以下可免费商用的字体：若想新增更多可免费商用的字体，请联系开发者。 hacker neo

| 字体名 | 中文名 | | --------------------------- | :--------: | | jiangxizhuokai | 江西拙楷 | | slideyouran | 演示悠然小楷 | | SourceHanSansSC-Heavy | 思源黑体-特粗 | | SourceHanSansSC-Bold | 思源黑体-粗 | | SourceHanSansSC-Medium | 思源黑体-中等 | | SourceHanSansSC-Regular | 思源黑体-常规 | | SourceHanSansSC-Normal | 思源黑体-标准 | | SourceHanSansSC-Light | 思源黑体-细 | | SourceHanSansSC-ExtraLight | 思源黑体-特细 | | SourceHanSerifCN-Heavy | 思源宋体-特粗 | | SourceHanSerifCN-Bold | 思源宋体-粗 | | SourceHanSerifCN-SemiBold | 思源宋体-半粗 | | SourceHanSerifCN-Medium | 思源宋体-中等 | | SourceHanSerifCN-Regular | 思源宋体-常规 | | SourceHanSerifCN-Light | 思源宋体-细 | | SourceHanSerifCN-ExtraLight | 思源宋体-特细 | | Alibaba-PuHuiTi-Heavy | 阿里巴巴普惠体-特粗 | | Alibaba-PuHuiTi-Bold | 阿里巴巴普惠体-粗 | | Alibaba-PuHuiTi-Medium | 阿里巴巴普惠体-中等 | | Alibaba-PuHuiTi-Regular | 阿里巴巴普惠体-常规 | | Alibaba-PuHuiTi-Light | 阿里巴巴普惠体-细 | 示例 [#示例-1] ```json { "x": 320, "y": 185, "text": "Davinci Li", "font": "SourceHanSansSC-Normal", "fontSize": 22, "color": "#fff", "width": 320, "textAlign": "center" } ``` 图片 [#图片] 图片组件可以向图片中添加图片内容，例如添加自定义的背景图。图片链接需要保证能够正常访问下载。支持的图片格式有：gif、jpeg、png、bmp、tiff、webp 属性 [#属性-1] | 字段名 | 数据类型 | 默认值 | 必需 | 描述 | | :---------------------: | :------------: | :------: | :-: | ------------------------------------------------------ | | x | int | | yes | 图片 X 坐标 | | y | int | | yes | 图片 Y 坐标 | | url | url | | yes | 图片链接，需要保证图片能够正常访问下载。支持的图片格式：gif、jpeg、png、bmp、tiff、webp | | width | int | | yes | 图片渲染宽度，用于缩放图片 | | height | int | | yes | 图片渲染高度，用于缩放图片 | | borderColor | Hex Color Code | #000000 | | 四条边框颜色 | | borderWidth | int | 0 | | 四条边框宽度 | | strokeAlign | string | `CENTER` | | 边框对齐方式，可选值：`CENTER`- 居中、`INSIDE` - 内部、`OUTSIDE` - 外部 | | borderRadius | int | 0 | | 边框四个顶点圆角半径 | | borderTopLeftRadius | int | 0 | | 边框左上角顶点圆角半径，优先级高于 `borderRadius` | | borderTopRightRadius | int | 0 | | 边框右上角顶点圆角半径，优先级高于 `borderRadius` | | borderBottomLeftRadius | int | 0 | | 边框左下角顶点圆角半径，优先级高于 `borderRadius` | | borderBottomRightRadius | int | 0 | | 边框右下角顶点圆角半径，优先级高于 `borderRadius` | | zIndex | int | 0 | | 渲染层级，会影响同一位置不同内容的覆盖情况 | imgrender 图片组件

示例 [#示例-2] ```json { "x": 248, "y": 25, "width": 120, "height": 120, "url": "https://img-chengxiaoli-1253325493.cos.ap-beijing.myqcloud.com/bikers_327390-13.jpg", "borderRadius": 60, "zIndex": 1 } ``` 线段 [#线段] 线段组件可以向图片中添加线段，可用于绘制分割线、下划线等。属性 [#属性-2] | 字段名 | 数据类型 | 默认值 | 必需 | 字段描述 | | :----: | :------------: | :-----: | :-: | ------- | | startX | int | | yes | 起点 X 坐标 | | startY | int | | yes | 起点 Y 坐标 | | endX | int | | yes | 终点 X 坐标 | | endY | int | | yes | 终点 Y 坐标 | | width | int | | yes | 线段宽度 | | color | Hex Color Code | #000000 | | 线段颜色 | | zIndex | int | 0 | | 渲染层级 | 示例 [#示例-3] ```json { "startX": 30, "startY": 696, "endX": 610, "endY": 696, "width": 1, "color": "#E1E1E1", "zIndex": 1 } ``` 矩形 [#矩形] 矩形组件可以向图片中添加矩形。属性 [#属性-3] | 字段名 | 数据类型 | 默认值 | 必需 | 描述 | | :---------------------: | :------------: | :------: | :-: | ---------------------------------------------------- | | x | int | | yes | 矩形 X 坐标 | | y | int | | yes | 矩形 Y 坐标 | | width | int | | yes | 矩形宽度 | | height | int | | yes | 矩形高度 | | backgroundColor | Hex Color Code | #000000 | | 背景颜色 | | borderColor | Hex Color Code | #000000 | | 四条边框颜色 | | borderWidth | int | 0 | | 四条边框宽度 | | strokeAlign | string | `CENTER` | | 边框对齐方式，可选值：`CENTER`- 居中、`INSIDE` - 内部、`OUTSIDE` - 外部 | | borderRadius | int | 0 | | 边框四个顶点圆角半径 | | borderTopLeftRadius | int | 0 | | 边框左上角顶点圆角半径，优先级高于 `borderRadius` | | borderTopRightRadius | int | 0 | | 边框右上角顶点圆角半径，优先级高于 `borderRadius` | | borderBottomLeftRadius | int | 0 | | 边框左下角顶点圆角半径，优先级高于 `borderRadius` | | borderBottomRightRadius | int | 0 | | 边框右下角顶点圆角半径，优先级高于 `borderRadius` | | zIndex | int | 0 | | 渲染层级，会影响同一位置不同内容的覆盖情况 | imgrender 矩形组件

示例 [#示例-4] ```json { "x": 220, "y": 100, "width": 380, "height": 200, "backgroundColor": "#fff", "borderColor": "#fff" } ``` 二维码 [#二维码] 二维码组件可以向图片中添加二维码内容，可以用于添加分享链接二维码。参数 [#参数] | 字段名 | 数据类型 | 默认值 | 必需 | 描述 | | :-------------: | :------------: | :-----: | :-: | --------------------- | | x | int | | yes | 二维码 X 坐标 | | y | int | | yes | 二维码 Y 坐标 | | size | int | | yes | 正方形二维码尺寸大小 | | content | string | | yes | 二维码内容 | | foregroundColor | Hex Color Code | #000000 | | 二维码前景色 | | backgroundColor | Hex Color Code | #ffffff | | 二维码背景色 | | zIndex | int | 0 | | 渲染层级，会影响同一位置不同内容的覆盖情况 | imgrender 二维码组件

二维码组件存在背景色边框，例如上图中二维码的白色边框。边框的粗细由二维码尺寸与编码内容长度共同决定，例如当 `size` 为 200px 时，但仅编码一个字符 `a`，则边框就会比上图更宽。通过设置与环境色相同的二维码背景色，可消除二维码边框的影响。示例 [#示例-5] ```json { "x": 208, "y": 726, "size": 200, "content": "http://weixin.qq.com/r/yRzk-JbEbMsTrdKf90nb", "foregroundColor": "#000", "backgroundColor": "#fff", "zIndex": 1 } ``` # 通过 Figma 设计图片 (/docs/api/generate-image-v1/figma-plugin) 此插件是旧版接口专用的，不再新增功能。我们强烈建议您迁移至 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")。推荐在 [模板编辑器](/playground "打开模板编辑器") 中用 JSX/HTML 设计模板并定义变量，发布后只需传入变量即可生成图片： * **基于 JSX/HTML 编写模板**：直接使用前端熟悉的标签结构，告别复杂的“蓝图” JSON 协议。 * **现代样式支持**：全面支持内联样式（`style`）和 Tailwind CSS 类名快速排版。 * **支持变量和条件渲染**：可简化请求时需要传入的数据。 * **多格式导出**：支持灵活导出高质量的 WebP、PNG 和 JPEG 图片格式。由于 imgrender 蓝图参数较多，设置时较为复杂。因此，我们提供了 Figma 插件，你可以在 Figma 中设计图片，然后通过插件将设计稿一键导出为 imgrender 蓝图。

如何安装插件 [#如何安装插件] 要使用 Figma 插件，你需要[创建一个 Figma 帐户](https://help.figma.com/hc/en-us/articles/360039811114 "Figma 帮助文档")。然后，你可以安装插件： 1. 打开 [imgrender Figma 插件页](https://www.figma.com/community/plugin/1273461051550664878 "imgrender Figma 插件页") 2. 单击 Try it out，这会将你重定向到新的 Figma 设计文件页面，并会打开插件预览弹窗。 3. 单击 “Save” 图标，即可保存插件。 4. 单击 "Run" 按钮，即可运行插件。运行 Figma 插件

如何使用插件 [#如何使用插件] 1. 点击插件后，会展示插件的 UI 界面 2. 在 Figma 中设计好图片 3. 选中设计稿 4. 点击插件界面中的 “Output” 按钮，就会将设计稿转换为 imgrender 蓝图，并自动复制到粘贴板中。 Figma 插件

注意事项 [#注意事项] 1. 插件要求选中的内容为单个图层。导出前，请将设计稿中的元素设置为一个组。 2. 插件目前支持的 Figma 元素有：矩形、线段、文本、图片。二维码元素，仍需要手动添加到蓝图中。 3. 矩形和图片的边框仅支持尖角折点。 4. 目前无法直接获取 Figma 中的图片。插件导出时， image 元素的 url 的值固定为：`Please replace with accessible image url`。导出后，请自行替换为对应的图片链接。 5. 文本字体目前只支持 Source Han Sans SC (思源黑体)系列字体。若你选择了其他字体，插件导出时，字体将固定为 `SourceHanSansSC-Normal`。导出后，请自行替换为相应的字体。 # 基于JSON 生成图片 - 旧版 (/docs/api/generate-image-v1) 此接口（旧版蓝图 API）不再新增功能。我们强烈建议您迁移至 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")。推荐在 [模板编辑器](/playground "打开模板编辑器") 中用 JSX/HTML 设计模板并定义变量，发布后只需传入变量即可生成图片： * **基于 JSX/HTML 编写模板**：直接使用前端熟悉的标签结构，告别复杂的“蓝图” JSON 协议。 * **现代样式支持**：全面支持内联样式（`style`）和 Tailwind CSS 类名快速排版。 * **支持变量和条件渲染**：可简化请求时需要传入的数据。 * **多格式导出**：支持灵活导出高质量的 WebP、PNG 和 JPEG 图片格式。根据传入的[蓝图](/docs/api/generate-image-v1/blueprint "蓝图")，同步生成图片，返回**图片的访问链接**。在此接口中，调用者可以实时控制蓝图，具有最高的灵活性。点此 [在线调试和查看交互式 API 文档](https://apifox.com/apidoc/project-2058619/api-81628036 "打开 Apifox API 文档") 请求 [#请求] * **HTTP URL**: `https://api.imgrender.net/open/v1/pics` * **HTTP Method**: POST * **版本**: v1 请求参数 [#请求参数] Header 参数 [#header-参数] | 字段 | 数据类型 | 必填 | 描述 | | :----------: | :----: | :-: | -------------------------------------------------- | | X-API-Key | string | yes | 用于请求授权，请参考 [请求认证方式](/docs/api/basic "查看 API 认证方式") | | Content-Type | string | yes | **固定值**："application/json; charset=utf-8" | Body 参数 [#body-参数] Body 必须且只能传入 [蓝图](/docs/api/generate-image-v1/blueprint "查看蓝图文档") 数据。响应 [#响应] 当请求成功时，HTTP 状态码为 `200`，并且会以 JSON 格式返回数据： ```json { "code": 0, "message": "ok", "data": { "url": "https://davinci.imgrender.cn/6e31cfcd683a36d0522a8cc34e244379.jpg?sign=xxx" } } ``` * `code`：错误码，当错误码为 `0` 时，表示处理成功，其他值表示存在一定的问题。 * `message`：提示信息，与`code`相对应，更多提示信息可查看[状态码与错误码](/docs/api/status-code "状态码与错误码")。 * `data` ：返回的数据。当 `code` 为 `0` 时返回，其中 `url` 为图片链接。图片链接的**有效期为 5 分钟**，请及时下载或展示图片。超时后，重新请求即可获取新的访问链接。错误码 [#错误码] | 错误码 | HTTP 状态码 | 说明 | 排查建议 | | ------- | -------- | ------ | --------- | | `20105` | `403` | 图片生成失败 | 请根据提示信息处理 | 更多通用错误码见：[状态码与错误码](/docs/api/status-code "状态码与错误码") # 自定义字体 (/docs/api/generate-image/custom-fonts) imgrender 内置了可免费商用的字体，推荐优先使用[内置字体](/docs/template-guide/typography-and-fonts "查看内置字体列表")，渲染速度更快。本文说明如何在 [基于 JSX/HTML 生成图片 API](/docs/api/generate-image "基于 JSX/HTML 生成图片 API") 的请求体中传入自定义字体。若使用推荐的 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")，请在 [模板编辑器](/playground "打开模板编辑器") 中为模板配置字体，无需在请求时传入 `fonts`。下面将介绍如何在请求时使用自定义字体。加载自定义网络字体 [#加载自定义网络字体] 如果你的设计需要特殊的字体文件，可以通过[请求体](/docs/api/generate-image#请求体参数 "查看请求体参数")中的 `fonts` 数组字段来动态注册自定义字体。在 `fonts` 数组中，你可以传入以下结构的对象： | 字段名 | 类型 | 必填 | 描述 | | ------------ | ---------- | ----- | --------------------------------------------------------------- | | `familyName` | `string` | **是** | 字体族名称。只支持大小写英文字母、数字。你需要在 `content` 中通过 `fontFamily` 严格匹配并引用该名称。 | | `fontUrls` | `string[]` | **是** | 字体文件的网络下载地址列表（URL）。支持 TTF、OTF、WOFF 等常见格式。 | 注意事项： familyName 属性会覆盖字体文件元数据中的字体名，但 weight、style 等属性仍是直接使用字体文件元数据。因此每个对象对应一个字体族，其 fontUrls 内指定的字体文件应该都属于该字体族，并且保持 weight、style 唯一。示例： ``` { "content": , fonts: [ { "fontFamily": "MyFont1", "fontUrls": [ "https://example.com/MyFont1/Regular.ttf", "https://example.com/MyFont1/Medium.ttf", "https://example.com/MyFont1/SemiBold.ttf", ... ] }, { "fontFamily": "MyFont2", "fontUrls": [ "https://example.com/MyFont2/Regular.ttf", "https://example.com/MyFont2/Medium.ttf", "https://example.com/MyFont2/SemiBold.ttf", ... ] } ] } ``` 字体按需加载机制 [#字体按需加载机制] 仅当你在 `content` 中实际通过 `fontFamily` 引用了某款自定义字体的 `familyName` 时，imgrender 才会去发起网络请求下载并加载该字体。未被引用的字体不会被加载。查看[如何使用字体](/docs/template-guide/typography-and-fonts#使用字体 "查看字体使用方法") 1. 字体文件尽可能小，最大不能超过 10 MB。超过 10 MB 会加载失败。 2. 保证链接可公网访问。若托管你字体的服务开启了鉴权措施（如私有访问的对象存储服务），则提供的字体 URL 一定要包含鉴权信息。 3. 链接公网访问速度足够快。 # 基于 JSX/HTML 生成图片 (/docs/api/generate-image) 大多数业务场景请使用 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")：在模板编辑器中保存并发布模板后，请求时只需传入变量。本接口适用于不保存模板、每次传入完整 JSX/HTML 的一次性渲染。通过该接口，你可以将 JSX/HTML 代码片段直接生成并导出为高质量的图片（支持 WebP、PNG、JPEG）。请求 [#请求] 请求方法与 URL [#请求方法与-url] ``` POST https://api.imgrender.net/open/v1/images/render ``` 请求头参数 [#请求头参数] | 字段 | 数据类型 | 必填 | 描述 | | :----------: | :----: | :-: | -------------------------------------------------- | | X-API-Key | string | yes | 用于请求授权，请参考 [请求认证方式](/docs/api/basic "查看 API 认证方式") | | Content-Type | string | yes | **固定值**："application/json; charset=utf-8" | 请求体参数 [#请求体参数] | 字段名 | 类型 | 必填 | 描述 | 默认值 | | --------- | -------- | ----- | ------------------------------------------------------------------------------------ | ------ | | `content` | `string` | **是** | 描述图片布局和内容的 JSX/HTML 字符串。写法见 [模板开发指南](/docs/template-guide/overview "模板开发指南") | - | | `width` | `number` | 否 | 输出图片的宽度（像素）。不传则根据内容自适应。 | - | | `height` | `number` | 否 | 输出图片的高度（像素）。不传则根据内容自适应。 | - | | `format` | `string` | 否 | 输出图片的格式。支持 `png`、`jpeg`、`webp`。 | `webp` | | `quality` | `number` | 否 | 图片质量（0-100），仅对 `jpeg` 和 `webp` 格式有效。 | - | | `fonts` | `array` | 否 | 自定义字体配置列表，用于在内容中加载和渲染外部字体。详情见 [自定义字体](/docs/api/generate-image/custom-fonts "自定义字体") | `[]` | 响应 [#响应] 当请求成功时，HTTP 状态码为 `200`，并且会以 JSON 格式返回数据： ```json { "code": 0, "message": "ok", "data": { "url": "https://res.imgrender.net/6e31cfcd683a36d0522a8cc34e244379.jpg?sign=xxx" } } ``` * `code`：错误码，当错误码为 `0` 时，表示处理成功，其他值表示存在一定的问题。 * `message`：提示信息，与`code`相对应，更多提示信息可查看[状态码与错误码](/docs/api/status-code "状态码与错误码")。 * `data` ：返回的数据。当 `code` 为 `0` 时返回，其中 `url` 为图片链接。图片链接的**有效期为 5 分钟**，请及时下载或展示图片。超时后，重新请求即可获取新的访问链接。示例 [#示例] 下面是一个完整的请求示例，展示如何传入 JSX/HTML 并生成图片： ```bash curl -X POST https://api.imgrender.net/open/v1/images/render \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "content": "

Hello imgrender!

", "width": 800, "height": 400, "format": "png" }' ``` ```javascript const payload = { content: '

Hello imgrender!

', width: 800, height: 400, format: 'png', } fetch('https://api.imgrender.net/open/v1/images/render', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY', }, body: JSON.stringify(payload), }) .then((res) => res.json()) .then((result) => console.log('图片链接：', result.data.url)) ``` 如需在请求中注册自定义网络字体，见 [自定义字体](/docs/api/generate-image/custom-fonts "自定义字体")。 # 状态码与错误码 (/docs/api/status-code) HTTP 状态码 [#http-状态码] | HTTP 状态码 | 说明 | 排查建议 | | -------- | ------ | --------------------------------- | | `200` | 处理成功 | | | `400` | 请求失败 | 通常是因为请求参数不符合要求，请根据提示信息检查请求参数 | | `401` | 请求认证失败 | 检查 API Key 是否设置正确 | | `403` | 请求被拒 | 请求正常被服务端接收了，但因为业务限制而被拒绝，请根据提示信息处理 | | `404` | 资源不存在 | 请检查请求参数 | | `429` | 请求限流 | 请降低请求频率 | | `500` | 系统错误 | 服务端出错了，请反馈给客服处理 | 通用错误码 [#通用错误码] 以下为常见错误码，API 专有的错误码可以在具体 API 接口文档中查看。 | 错误码 | HTTP 状态码 | 说明 | 排查建议 | | ------- | -------- | ----- | ------------------------------- | | `0` | `200` | 处理成功 | | | `10101` | `500` | 系统错误 | 服务端出错了，请反馈给客服处理 | | `10102` | `429` | 请求限流 | QPS 过高，请降低请求频率 | | `10103` | `400` | 参数错误 | 请根据提示信息检查请求参数 | | `10104` | `401` | 认证失败 | 检查 API Key 是否设置正确或 API Key 是否有效 | | `10105` | `403` | 禁止操作 | 请求因业务限制而被拒绝，请根据提示信息处理 | | `10106` | `403` | 重复操作 | 请求重复，稍后重试即可 | | `10107` | `404` | 资源不存在 | 请检查请求参数 | | `30101` | `403` | 资源不足 | 请检查请求对应的资源包是否充足 | # API Keys 管理 (/docs/dashboard/api-key) 调用 imgrender 的服务时，要求通过 API Key 对请求进行认证。本文将介绍如何管理 API Key。创建 API Key [#创建-api-key] 登录imgrender 控制台后，单击左侧导航栏**API Keys**，即可进入 API Keys 管理页面。点击 **"创建 API Key"** 按钮，系统将会自动生成密钥。 API Key 的格式为：`数字.随机字符串`。创建完成后，即可调用 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")。完整接入步骤见 [快速开始](/docs "快速开始")。禁用与删除 [#禁用与删除] 禁用 API Key 后，你将无法使用该 API Key 调用 imgrender 的服务。在禁用前，请确保该 API Key 在你的应用中不再使用。删除 API Key 前，要求先禁用 API Key。删除 API Key 后，你将无法再管理该 API Key，请谨慎操作。 API Key 轮换实践 [#api-key-轮换实践] 为了防止 API Key 泄漏，导致资源被盗用，推荐每年更换一次 API Key。下面介绍 API Key 更换流程： 1. 新建 API Key 2. 在你的应用中，使用新 API Key 替换旧 API Key 3. 确保旧 API Key 没有任何地方使用 4. 禁用旧 API Key，这时该 API Key 将无法调用服务 5. 删除旧 API Key # 资源包管理 (/docs/dashboard/resource-packages) 登录imgrender 控制台后，单击左侧导航栏**资源包**，即可进入资源管理页面。资源是账号维度的，即同一个账号下的开放应用都可使用这些资源。查看免费额度余额 [#查看免费额度余额] 在资源管理页顶部会展示免费额度相关信息。查看资源包 [#查看资源包] 资源包状态列表： | 状态 | 说明 | | --- | :-------------: | | 待支付 | 发起购买后，未完成支付 | | 已取消 | 发起购买后，未支付的情况下取消 | | 正常 | 完整支付后，可正常使用该资源 | | 已耗尽 | 资源未过期，但已用尽 | | 已过期 | 资源未用尽，但已过期 | 发起购买后 15 天内，未支付的资源包会出现在 **待支付** Tab 下，15 天后会自动取消，你也可以主动取消。 # 快速开始 (/docs) 介绍 [#介绍] imgrender 提供的高性能图片生成服务，可以使你的应用快速拥有图片生成能力，可用于自动生成海报、证书、商品封面图、博客封面、个性化广告图... 推荐工作流：在 [模板编辑器](/playground "打开模板编辑器") 中用 JSX/HTML 设计模板并定义变量，发布后调用 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")，只需传入变量值即可生成图片。核心功能 [#核心功能] 在模板编辑器中用 JSX/HTML 设计模板并定义变量。业务侧调用 API 时只需传入模板 ID 和变量值，即可渲染输出高质量图片（支持 WebP、PNG、JPEG 格式）。支持内联样式和 Tailwind CSS 类名，前端开发者零学习成本上手。 | 特性 | 说明 | | -------- | --------------------------------------- | | **模板复用** | 设计一次模板，业务侧只传变量，不必每次提交完整 JSX/HTML | | **简单易用** | 传入模板 ID 和变量，返回图片链接，无需搭建渲染服务 | | **高性能** | 服务端渲染，毫秒级响应，无需担心浏览器环境开销 | | **灵活定制** | 支持按请求覆盖尺寸、格式、质量；模板内可使用变量、条件与循环 | | **样式丰富** | 模板支持内联 style 和 Tailwind CSS 类名，轻松实现复杂布局 | *** 快速上手 [#快速上手] 只需 3 步，即可开始使用 imgrender： 1\. 注册并获取 API Key [#1-注册并获取-api-key] 访问 imgrender 控制台，注册账号并登录。登录后，进入 **API Keys** 页面，点击 "创建 API Key" 即可生成 API Key。API Key 格式为：`数字.随机字符串`。 API Key 是调用服务的凭证，请妥善保管，不要提交到公开代码仓库或泄露给他人。 2\. 创建并发布模板 [#2-创建并发布模板] 打开 [模板编辑器](/playground "打开模板编辑器")，用 JSX/HTML 编写模板，并用 `{$ 变量名 $}` 把需要动态替换的内容参数化。保存并**发布**后，在控制台模板详情页获取**模板 ID**。模板编写与变量用法见 [模板开发指南](/docs/template-guide/overview "模板开发指南") 和 [变量](/docs/template-guide/variables "变量")。线上接口默认使用已发布内容。模板未发布或已归档时，调用会返回 `409`。调试草稿时可在请求中设置 `useDraft: true`。 3\. 调用 API [#3-调用-api] 将下面示例中的 `YOUR_API_KEY` 和 `tpl_xxx` 替换为你的 API Key 与模板 ID，即可生成图片： ```javascript const response = await fetch( 'https://api.imgrender.net/open/v1/images/templates/tpl_xxx/render', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY', }, body: JSON.stringify({ variables: { title: 'Hello imgrender!', }, format: 'png', }), }, ) const result = await response.json() console.log('图片链接：', result.data.url) ``` ```bash curl -X POST 'https://api.imgrender.net/open/v1/images/templates/tpl_xxx/render' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ -d '{ "variables": { "title": "Hello imgrender!" }, "format": "png" }' ``` 请求成功后，响应示例： ```json { "code": 0, "message": "ok", "data": { "url": "https://res.imgrender.net/xxx.jpg?sign=xxx" } } ``` 返回的图片链接有效期为 5 分钟，请及时下载或展示图片。超时后重新请求即可获取新的链接。若不想保存模板、希望每次请求传入完整 JSX/HTML，可使用 [基于 JSX/HTML 生成图片 API](/docs/api/generate-image "基于 JSX/HTML 生成图片 API")。生产环境更推荐基于模板的接口。 *** 接下来 [#接下来] 深入学习布局、样式、变量、字体、图片加载等了解完整的请求参数、变量传入方式和错误码 # 价格 (/docs/pricing) 免费额度 [#免费额度] imgrender 向所有用户提供一定量的免费资源，免费额度明细请参见下表 | 资源类型 | 免费额度 | 重置时间 | | -------- | :-------: | :----------: | | 图片生成同步请求 | 每月 1000 次 | 每月 1 号 00:00 | 购买资源包 [#购买资源包] imgrender 使用资源包对付费资源进行管理，详见[资源包管理](/docs/dashboard/resource-packages "查看资源包管理文档")。 | 资源类型 | 计费方式 | 定价 | 有效期 | 计费说明 | | -------- | :--: | :--------: | :---: | :-------------------: | | 图片生成同步请求 | 按次计费 | 0.005 元/每次 | 365 天 | 只有请求成功时才计费，若请求失败则不计费。 | 假设购买 20000 次图片生成同步请求： * 总价为 0.005 \* 20000 = 100 元。 * 自完成支付开始，365 天内可使用。资源抵扣说明 [#资源抵扣说明] 资源将按照以下规则进行抵扣： 1. 若用户存在免费资源，优先使用免费资源。免费资源用尽后，开始从资源包中抵扣。 2. 优先抵扣临近到期的资源包，到期时间相同时，优先抵扣较早生效的资源包。 3. 若没有资源包，服务将会立即失败，请及时购买资源包。退款规则 [#退款规则] * 对于单个账号而言，**未过期且未使用**的资源包支持退款。 * 一经使用，不支持退款、不支持延期。 * 如出现疑似异常或恶意退款，imgrender 有权拒绝您的退款申请。 > 目前暂不能自助退款，若需要退款，请联系客服。常见问题 [#常见问题] 1. 是否提供发票？ > 提供电子发票。若需要发票，请联系客服。 # 布局 (/docs/template-guide/layout) imgrender 支持 CSS Flexbox 和 Grid 布局。 Box Model [#box-model] imgrender 中每个元素都遵循标准的 CSS Box Model，每个元素的总大小是根据内容、padding、border、margin 计算得出的。自适应宽高 [#自适应宽高] imgrender 可以根据内容自适应宽高。你也可以在模板编辑器中指定模板的 width 和 height，或在调用 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API") 时通过请求参数覆盖，从而约束生成图片的宽高。图像尺寸 [#图像尺寸] 默认情况下，image 将按照原始尺寸进行渲染。你可以通过指定 width 和 height 来指定图像的宽高 ```jsx

``` # 加载图片 (/docs/template-guide/load-images) 网络图片 [#网络图片] imgrender 支持通过 `img` 标签、CSS 属性 `background-image` 和 `mask-image` 引用网络图片。支持的图片格式有：`jpeg`、`png`、`webp`、`svg`。 1. 图片文件尽可能小，最大不能超过 10 MB。超过 10 MB 会加载失败。 2. 保证图片链接可公网访问。若托管你图片的服务开启了鉴权措施（如私有访问的对象存储服务），则提供的图片 URL 一定要包含鉴权信息。 3. 图片链接公网访问速度足够快。 ```jsx

``` ```jsx

...

``` ```jsx

...

``` 缓存 [#缓存] 为提升渲染性能，imgrender 会以图片 url 为 key 缓存图片。加载图片时，若图片命中缓存，则会优先使用缓存数据，不再从网络上下载图片。在 url 对应的图片已被 imgrender 缓存地情况下，图片内容改变了，但 url 未改变，imgrender 仍会使用已缓存的旧图片内容。为了避免这种情况发生，可在 url 上增加或修改 query 参数。如下所示。旧 url: ```bash https://www.imgrender.net/images/example.png ``` 新 url： ```bash https://www.imgrender.net/images/example.png?v=1 ``` # 概览 (/docs/template-guide/overview) 工作原理 [#工作原理] imgrender 采用 **声明式图片生成** 的方式：你使用熟悉的 HTML / JSX 和 CSS 描述模板内容，发布后通过 API 传入变量，imgrender 负责将其渲染为高质量的图片。 ```jsx

Hello imgrender

``` 上述代码将生成一张 400×200 像素的渐变背景图片，居中显示白色文字。模板编辑器 [#模板编辑器] [模板编辑器](/playground "打开模板编辑器")是 imgrender 提供的在线编辑环境，适合在编写文档或调用 API 之前快速验证模板效果。你可以在模板编辑器中： * 编辑 HTML / JSX，实时预览渲染结果 * 配置图片尺寸、格式等输出参数 * 管理并预览所用字体 * 从内置模板起步，快速改造成自己的样式 * 使用变量将模板内容参数化，同一模板生成不同图片 * 一键打开 API 调试面板，基于当前已保存模板生成可调用的渲染请求 * 通过 URL 分享当前编辑状态，方便协作与复现开发模板时，建议先在 [模板编辑器](/playground "打开模板编辑器") 中完成布局与样式调试，确认效果后再接入 [基于模板生成图片 API](/docs/api/generate-image-by-template "基于模板生成图片 API")。核心概念 [#核心概念] imgrender 的图片生成过程可以理解为： 1. **结构描述** - 使用 HTML/JSX 定义元素的层级结构 2. **样式控制** - 通过 CSS 属性或 Tailwind CSS 控制外观 3. **变量替换** - 使用 `{$ name $}` 占位符将内容参数化，渲染时替换为实际值 4. **渲染输出** - imgrender 渲染并导出为指定格式的图片与传统图片生成的对比 [#与传统图片生成的对比] | 方式 | 优点 | 缺点 | | ---------- | ------------------------- | --------------------- | | imgrender | 代码即图片，易于维护、调用简单、版本控制、动态生成 | 需要学习成本 | | 设计工具导出 | 所见即所得，无需编码 | 难以批量生成，不易修改 | | Canvas API | 灵活度高 | 代码复杂，维护成本高，依赖 JS 运行环境 | HTML 与 CSS 支持度 [#html-与-css-支持度] imgrender 的渲染引擎，**并非完全遵循浏览器标准**，只支持 HTML 和 CSS 的一个子集。 imgrender 不保证渲染结果与浏览器 100% 一致，建议在 [模板编辑器](/playground "打开模板编辑器") 中进行测试验证。 JSX / HTML 元素限制 [#jsx--html-元素限制] imgrender 仅接受纯净（无运算）且无状态的 JSX / HTML 元素。不支持如 `useState`、`useEffect`、`dangerouslySetInnerHTML` 等 React API。仅支持有限的静态、可见元素： * ✅ 支持：`div`、`span`、`p`、`img` 等基础元素 * ❌ 不支持：``、`