生成二维码

接口说明

将文本或链接生成二维码图片。只需传入 content 字段即可，其他参数均为可选。

POST https://www.codebox.club/api/v1/qrcode/generate
Content-Type: application/json

快速开始

最简调用，只传 content：

curl -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -d '{"content": "https://example.com"}' \
  -o qrcode.png

返回 base64 格式：

curl -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -d '{"content": "https://example.com", "responseFormat": "json"}'

请求参数

必填

参数	类型	说明
`content`	string	要编码的内容（链接或文本），最大 4000 字符

可选 - 基础

参数	类型	默认值	说明
`size`	integer	`300`	图片尺寸（像素），50-2000
`format`	string	`png`	输出格式：`png` / `svg`
`margin`	integer	`10`	边距（像素），0-100
`errorCorrectionLevel`	string	`M`	纠错等级：`L` / `M` / `Q` / `H`
`responseFormat`	string	`binary`	响应格式：`json`（base64）/ `binary`（图片流）
`styleMode`	string	`normal`	`normal` 普通 / `image` 图片模式（支持背景图）

可选 - 样式

参数	类型	默认值	说明
`dotsStyle`	string	`rounded`	点阵形状：`square` / `dots` / `rounded` / `extra-rounded` / `classy` / `classy-rounded`
`dotsColor`	string	`#f59e0b`	点阵颜色，十六进制
`dotRadiusRatio`	number	`0.5`	点阵大小比例，0.1-0.5
`cornersSquareStyle`	string	`dot`	定位角外框：`square` / `extra-rounded` / `dot`
`cornersSquareColor`	string	同 dotsColor	定位角外框颜色
`cornersDotStyle`	string	`dot`	定位角内点：`square` / `dot` / `extra-rounded`
`cornersDotColor`	string	同 dotsColor	定位角内点颜色
`backgroundColor`	string	`#FFFFFF`	背景颜色

可选 - 渐变

参数	类型	说明
`dotsGradient.type`	string	`linear` 或 `radial`
`dotsGradient.rotation`	number	渐变角度（度）
`dotsGradient.colorStops`	array	色标数组，至少 2 个，含 `offset`(0-1) 和 `color`

可选 - Logo

参数	类型	默认值	说明
`logoUrl`	string	-	Logo 图片 URL
`logoSize`	number	`0.2`	Logo 大小比例，0.1-0.5
`logoMargin`	integer	`5`	Logo 留白（像素），0-50
`logoX`	number	`0.5`	Logo X 轴位置，0-1
`logoY`	number	`0.5`	Logo Y 轴位置，0-1

可选 - 背景图（image 模式）

参数	类型	默认值	说明
`backgroundImage`	string	-	背景图片 URL
`backgroundImageSize`	number	`1.0`	缩放比例，0.1-2.0
`backgroundImageOpacity`	number	`1.0`	透明度，0.1-1.0

请求示例

{
  "content": "https://www.codebox.club"
}

{
  "content": "https://www.codebox.club",
  "dotsStyle": "dots",
  "dotsColor": "#e94560",
  "cornersSquareStyle": "extra-rounded",
  "responseFormat": "json"
}

{
  "content": "https://www.codebox.club",
  "dotsGradient": {
    "type": "linear",
    "rotation": 45,
    "colorStops": [
      { "offset": 0, "color": "#e94560" },
      { "offset": 1, "color": "#0f3460" }
    ]
  },
  "responseFormat": "json"
}

{
  "content": "https://www.codebox.club",
  "styleMode": "image",
  "backgroundImage": "https://example.com/bg.jpg",
  "backgroundImageOpacity": 0.6,
  "responseFormat": "json"
}

代码示例

# 最简调用，下载 PNG
curl -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -d '{"content": "https://example.com"}' \
  -o qrcode.png

# 带 API Key + 自定义样式
curl -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cb_sk_xxxxxxxx" \
  -d '{
    "content": "https://example.com",
    "dotsStyle": "dots",
    "dotsColor": "#e94560",
    "responseFormat": "json"
  }'

async function generateQR(content, options = {}) {
  const res = await fetch('https://www.codebox.club/api/v1/qrcode/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ content, responseFormat: 'json', ...options }),
  });
  const data = await res.json();
  return data.data.image; // base64 图片
}

// 最简调用
const img = await generateQR('https://example.com');

// 自定义样式
const styledImg = await generateQR('https://example.com', {
  dotsStyle: 'dots',
  dotsColor: '#e94560',
});

import requests, base64

def generate_qr(content, **options):
    res = requests.post(
        'https://www.codebox.club/api/v1/qrcode/generate',
        json={'content': content, 'responseFormat': 'json', **options},
    )
    return res.json()['data']['image']

# 最简调用
image = generate_qr('https://example.com')

# 保存为文件
_, encoded = image.split(',', 1)
with open('qrcode.png', 'wb') as f:
    f.write(base64.b64decode(encoded))

响应格式

JSON 格式（`responseFormat: "json"`）

{
  "success": true,
  "data": {
    "image": "data:image/png;base64,iVBORw0KGgo...",
    "format": "png",
    "size": 300,
    "mimeType": "image/png"
  }
}

Binary 格式（默认）

直接返回图片二进制数据，Content-Type 为 image/png 或 image/svg+xml。

错误响应

{
  "error": "Validation error",
  "details": "Field \"content\" is required and must be a non-empty string."
}

状态码	说明
400	参数错误
429	频率超限
500	服务器错误

On this page