QR Code Batch API

The QR code batch API lets you render many QR codes in a single request and receive a ZIP archive of the generated images. This is useful when you need to produce QR codes in bulk without fanning out into hundreds of individual HTTP calls.

tip

The batch API renders static QR codes. To create codes whose destination you can change later and whose scans you can track, see dynamic QR bulk creation.

API Endpoint

POST https://quickchart.io/qr/batch

The endpoint accepts application/json and returns application/zip.

Request Body

The request body must be either a JSON array of QR configs, or an object with a qrCodes array:

[
  { "text": "https://example.com/1" },
  { "text": "https://example.com/2" }
]

Or equivalently:

{
  "qrCodes": [
    { "text": "https://example.com/1" },
    { "text": "https://example.com/2" }
  ],
  "zipFilename": "my-codes.zip"
}

Each entry in the array uses the same options as the single QR endpoint. In addition, the following batch-specific fields are supported:

Field	Description	Required?	Default
text	Content of the QR code (URL or any string)	Yes
filename	File name for this entry inside the ZIP (extension added automatically)		qr-N.<ext>
format	Image format: png, svg, or jpg		png
size	Width and height of the image in pixels		150
margin	Whitespace around the QR image		4
dark	Hex color for "dark" QR cells (e.g. 000)		000000
light	Hex color for "light" QR cells (e.g. fff)		ffffff
ecLevel	Error correction level (L, M, Q, H)		M (H with a center image)

Appearance options supported by the single QR endpoint — including dotStyle, finderStyle, finderDotStyle, finderColor, centerImageUrl, centerImageSizeRatio, centerImageWidth, centerImageHeight, caption, captionFontFamily, captionFontSize, and captionFontColor — may also be set per entry.

The top-level request body additionally accepts:

Field	Description	Default
zipFilename	File name of the returned ZIP archive	qr-codes.zip

note

format=base64 is not supported for batch generation. Use png, svg, or jpg.

Response

On success, the endpoint returns an HTTP 200 with Content-Type: application/zip. The ZIP contains one file per QR config, named according to each entry's filename (or qr-1.png, qr-2.png, … if no filename is provided). Duplicate file names are automatically disambiguated with a numeric suffix.

Example

curl -X POST https://quickchart.io/qr/batch \
  -H "Content-Type: application/json" \
  -o qr-codes.zip \
  -d '[
    { "text": "https://example.com/1", "filename": "first-code", "size": 300 },
    { "text": "https://example.com/2", "filename": "second-code", "dark": "f00", "light": "0ff" },
    { "text": "wifi-password", "format": "svg", "ecLevel": "H" }
  ]'

The resulting qr-codes.zip will contain first-code.png, second-code.png, and qr-3.svg.

Limits

• A single batch request is limited to 1000 QR codes.
• A single batch request is limited to 450,000,000 total output pixels (equivalent to 50 full-size 3000×3000 QR codes). The sum of size * size across all entries must stay under this cap.
• The maximum size of any single QR code is 3000 pixels.
• The request timeout for batch requests is 5 minutes.

Error Responses

Errors are returned as HTTP 400 (or 403 for invalid signatures) with a JSON body:

{
  "success": false,
  "error": "qrCodes[0]: Error: You are missing variable `text`"
}

Errors reference the zero-based index of the first problematic entry, so you can identify which config caused the failure.

Authentication

To authenticate the whole batch, send Authorization: Bearer YOUR_API_KEY, add key to the query string, or include key alongside qrCodes in the top-level JSON object.

You can also provide a key on individual entries. Signed entries must each include their own sig and accountId; the signature is calculated from that entry's text. A top-level signature does not sign the batch. See signing requests.

Each rendered QR code counts as one render against your account's usage. Batch requests are rate limited, so use a request-level key for an authenticated batch.

Web-based Bulk Generator

If you don't need a programmatic workflow, you can also use the web-based bulk QR code generator.