QR Code API

QuickChart supports QR code generation. Generate a QR code like this:

https://quickchart.io/qr?text=Here's my text

QR code parameters

Build your customized QR code using the following query parameters. You may also use the web-based QR code builder.

Parameter Name	Description	Required?	Default value
text	Content of the QR code (can be a URL or any other string)	Yes
format	Format of QR code: png, svg, jpg, jpeg, or base64		png
margin	Whitespace around QR image, in modules		4
size	Width and height of the image in pixels (maximum 3000)		150
dark	Hex color code of "dark" QR grid cells		000000 (black)
light	Hex color code of "light" QR grid cells		ffffff (white)
finderColor	Hex color of the three finder patterns (corners). Defaults to dark.
dotStyle	Shape of data modules: square, dot (aka dots/round/circle), or rounded		square
finderStyle	Shape of finder patterns: square, rounded, or circle (aka dot/dots)		square
finderDotStyle	Shape of inner finder dots: square, rounded, or dot (aka dots/circle)		follows finderStyle
ecLevel	Error correction level (L, M, Q, H)		M (H if center image is present)
centerImageUrl	URL of image to show in the center. Must be URL-encoded.
centerImageSizeRatio	How much space to take up, between 0.0 and 1.0		0.3
centerImageWidth	Width of center image in pixels
centerImageHeight	Height of center image in pixels
caption	Caption text to display below the QR code.
captionFontFamily	Font family of the caption text		'Arial'
captionFontSize	Font size of the caption text in pixels.		12
captionFontColor	Color caption text, color names or hex code.		black

tip

Remember to URL-encode the text parameter. Otherwise special characters and symbols might not be included correctly (the QR builder takes care of this automatically).

Customizing QR code appearance

To customize the color of your QR code, use dark and light. The parameters must be hex color codes (e.g. dark=000000, light=ffffff). For a transparent background, set light to 0000.

Set the whitespace around QR image in modules with query parameter margin (defaults to 4), size determines the pixel dimensions of the image (defaults to 150), and error correction level with ecLevel (valid values: L, M, Q, H).

The QR endpoint produces a PNG image by default. Use format=svg for SVG or format=jpg for JPEG. format=base64 returns a base64-encoded PNG as plain text, without a data URI prefix. Format names are case-insensitive and may have a leading dot, such as .svg.

Keep enough contrast between dark and light for a scanner to read the code. Styled QR codes accept 3-, 4-, 6-, or 8-digit hex colors, with or without #; color names are not supported for these parameters.

Here's the same code as above but URL encoded with more error protection, colors, and in SVG format:

https://quickchart.io/qr?text=Here's%20my%20text&dark=f00&light=0ff&ecLevel=Q&format=svg

Use our interactive QR code generator to preview API behavior and test things out. You may also be interested in how to generate QR codes in a spreadsheet.

Styled QR codes

Use dotStyle, finderStyle, and finderDotStyle to change the shape of the data modules and finder patterns. Use finderColor to give the finder patterns a different color from the rest of the code.

Parameter	Supported values
dotStyle	square (default), dot, rounded
finderStyle	square (default), rounded, circle
finderDotStyle	square, rounded, dot (defaults to match finderStyle)
finderColor	Hex color (e.g. ff0066). Defaults to dark.

For example, rounded dots with circular finder patterns and a custom finder color:

https://quickchart.io/qr?text=Here's%20my%20text&dotStyle=rounded&finderStyle=circle&finderColor=ff0066

tip

Styled QR codes are still decodable by standard QR readers, but you should always scan-test your final design. Highly stylized codes may be harder to read at small sizes or in low contrast.

Images in QR codes

You may include an image centered in your QR code by using the centerImageUrl parameter. Note that the URL must be URL-encoded. PNG and JPG images are supported. Center images work with PNG, JPEG, and base64 output, but not SVG. Adding a center image sets ecLevel to H and margin to 1.

For example:

https://quickchart.io/qr?text=Here's my text&centerImageUrl=https://cdn-icons-png.flaticon.com/512/1389/1389234.png

To set width/height, use centerImageSizeRatio. This ratio should be a float between 0 and 1. It determines how much space the center image takes up.

https://quickchart.io/qr?text=Here's my text&centerImageUrl=https://cdn-icons-png.flaticon.com/512/1389/1389234.png&centerImageSizeRatio=0.75

Alternatively, you can specify width and height in pixels using centerImageWidth and centerImageHeight.

Note that the image URLs used in QR codes must be accessible on the public internet. Base64 data URIs are also supported.

caution

You should always test the QR code after overlaying an image. This is because an image can potentially block critical portions of the QR code. You can guard against this by making sure the image covers less than ~30% of the available area.

tip

Remember to URL-encode the centerImageUrl parameter. Otherwise the URL will not work correctly if it contains special characters (the QR builder takes care of this automatically).

Text below QR code

You can add text below your QR code with caption. Use captionFontFamily, captionFontSize, and captionFontColor to change its appearance. Captions work with PNG, JPEG, SVG, and base64 output, including styled QR codes.

For example:

https://quickchart.io/qr?text=abc123&caption=TextBelowQr&captionFontFamily=mono&captionFontSize=20

For multiple lines, include a newline in caption (%0A in a URL or \n in a JSON string). The caption fits inside the requested size; the QR code is reduced if more room is needed. Increase size or reduce the font size if the text is too long.

Here is an SVG with a two-line caption:

https://quickchart.io/qr?text=https%3A%2F%2Fexample.com&format=svg&size=240&caption=Scan%20me%0AVisit%20our%20website

POST requests

You can send the same parameters to POST /qr as JSON. This avoids URL encoding:

curl https://quickchart.io/qr \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "https://example.com/?a=1&b=2",
    "size": 300,
    "format": "png",
    "caption": "Scan me"
  }' \
  -o qr.png

For JSON errors instead of an image, check the same body with /api/validate-qr.

Building QR image URLs

Use POST /qr-url if you want a JSON response containing an image URL:

curl https://quickchart.io/qr-url \
  -H 'Content-Type: application/json' \
  -d '{"text": "https://example.com/?a=1&b=2", "size": 300}'

The response is:

{
  "url": "https://quickchart.io/qr?text=https%3A%2F%2Fexample.com%2F%3Fa%3D1%26b%3D2&size=300"
}

For multiple URLs, send an object with a qrCodes array to POST /qr-urls:

{
  "qrCodes": [{ "text": "first" }, { "text": "second" }]
}

The response contains the URLs in the same order:

{
  "urls": [
    "https://quickchart.io/qr?text=first",
    "https://quickchart.io/qr?text=second"
  ]
}

These endpoints encode the parameters into URLs. They do not render, validate, or save the QR codes. Any key included in the body will appear in the returned URL; use signed URLs if you need to share authenticated images.

Dynamic QR codes

QR codes from /qr are static: the text is encoded directly in the image, so changing a URL means reprinting. If you need to change a destination after printing, pause a code, or track scans, use dynamic QR codes. They're managed through a dashboard and API and are included with every QuickChart API key.

Bulk QR code generator

To generate many QR codes in a single request and receive them as a ZIP archive, use the QR Code Batch API.

If you're looking to generate codes quickly without writing code, try our web-based bulk QR code generator.

To create up to 10,000 editable, trackable codes from a CSV, use dynamic QR bulk creation.

Migrating from Google Image Charts

Google Image Chart parameters such as cht, chs, and chl are supported by the API.

This means that to migrate, you only need to replace chart.googleapis.com with quickchart.io:

https://quickchart.io/chart?cht=qr&chs=150x150&chl=Testing123

Troubleshooting

Parameters or Special Characters not working

When creating QR codes with QuickChart, you may find that certain parameters, special characters, or parts of the URL are not correctly preserved when the QR code is scanned.

Root Cause

This issue typically occurs when the URL or text content in the QR code is not properly URL-encoded within the QuickChart API call.

Solution: URL Encode the text or chl Parameter

To resolve this issue, you need to URL encode the entire content that you're putting into the QR code. This applies to both the text parameter in the new API and the chl parameter if you're using the Google Image Charts compatible API.

Steps to URL Encode:

1. Use a URL Encoding Tool:

   • Use an online URL encoder or a function in your programming language
   • Encode the full content of your QR code, including any special characters or parameters

2. Update Your QuickChart API Call:

   • Replace the unencoded content in your text or chl parameter with the encoded version

Example:

Original content:

https://example.com/page?param1=value1&param2=value2

Encoded content (to be used in the 'text' or 'chl' parameter):

https%3A%2F%2Fexample.com%2Fpage%3Fparam1%3Dvalue1%26param2%3Dvalue2

Complete QuickChart API call with encoded content:

https://quickchart.io/qr?text=https%3A%2F%2Fexample.com%2Fpage%3Fparam1%3Dvalue1%26param2%3Dvalue2