通过该接口，你可以使用在 imgrender 控制台或 Playground 中创建并发布的模板，传入变量值后同步生成图片。服务端会加载模板内容，校验变量并完成渲染，最终返回图片的 CDN 访问链接。

推荐用法

这是生产环境推荐的调用方式：在 Playground 中完成模板设计并发布后，请求时只需传入变量，不必每次提交完整 JSX/HTML。

尚未创建模板时，请先阅读快速开始和模板开发指南。变量写法见变量。

请求

请求方法与 URL

POST https://api.imgrender.net/open/v1/images/templates/{id}/render

其中 {id} 为模板 ID，可在控制台模板详情页获取。

请求头参数

字段	数据类型	必填	描述
X-API-Key	string	yes	用于请求授权，请参考请求认证方式
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。

响应

当请求成功时，HTTP 状态码为 200，并且会以 JSON 格式返回数据：

{
  "code": 0,
  "message": "ok",
  "data": {
    "url": "https://res.imgrender.net/6e31cfcd683a36d0522a8cc34e244379.jpg?sign=xxx"
  }
}

code：错误码，当错误码为 0 时，表示处理成功，其他值表示存在一定的问题。
message：提示信息，与 code 相对应，更多提示信息可查看状态码与错误码。
data：返回的数据。当 code 为 0 时返回，其中 url 为图片链接。图片链接的有效期为 5 分钟，请及时下载或展示图片。超时后，重新请求即可获取新的访问链接。

示例

下面是一个完整的请求示例，展示了如何基于模板 ID 传入变量并生成图片：

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
  }'

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` 后重试

更多通用错误码见：状态码与错误码

基于模板生成图片（推荐）

请求

请求方法与 URL

请求头参数

路径参数

请求体参数

响应

示例

错误码

On this page