QR generator: 3 simple steps to a safe scan

Reference

Name	Type	Required	Description
`data`	string	yes	Text or URL. Maximum 8192 bytes after decoding.
`size`	integer	no	Pixels per QR module, 1–30. It is not the final image width. Default: 3.
`type`	string	no	png, jpg or jpeg. Default: png.
`ecc`	string	no	Error correction: L, M, Q, H. Default: M.

Example request

curl -s "https://api2.globus.studio/v2/qr?data=Hello&size=5"

Open documentation

The QR generator encodes text or a URL and returns a PNG or JPEG image. The encoder is MADEVAL/phpQRcode. A short value makes a simple code; a long URL makes a dense one that is harder to scan on paper. A QR generator call is cheap, so test a few sizes before the print run.

What the QR generator returns

The body is the image. A successful call returns 200 with image/png or the type you asked for. An invalid payload returns 400 with text/plain and the message Invalid data.

HTTP/1.1 200 OK
Content-Type: image/png

<PNG binary>

Parameters

data is the text to encode, up to 8192 bytes after decoding. size is pixels per QR module from 1 to 30, not the final image width. type is png, jpg or jpeg. ecc sets error correction to L, M, Q or H.

Size and pixel limits

A QR generator response is capped by limits.image_pixels. Large size values are reduced automatically. A client that needs a print-ready file should generate at a reasonable size and check the result, not assume that a large number was honoured.

Error correction

In a QR generator request, level L recovers about 7 percent of damaged modules. Level H recovers about 30 percent and produces a denser code. For a sticker or a label that may get scratched, H is a reasonable choice. For a clean screen, M is enough. A higher level leaves less room for data, so a long URL and a high level can hit the cap.

Test with a phone

A code that looks fine on a monitor can fail on a phone. Check the contrast, the quiet zone around the code and the physical size if it will be printed. A code on a dark background needs a light border. Scan the proof with two phones and a cheap reader app.

When a QR code is the wrong tool

A code that points to a page behind a login is confusing unless the phone is already signed in. A code with a long URL is dense and harder to scan. Use a short link when you control the redirect. A code that changes every minute needs a display that can refresh it.

Caching and tracking

A generated code is an image with no built-in analytics. If you need to count scans, point the code at a URL you control and log the request there. Do not encode personal data that you would not put on a printed page. The QR generator is rate limited as a heavy operation.

Legacy nested URLs

A nested URL in data is parsed for data, size and type query parameters for legacy compatibility. A new client should send the parameters directly and encode a clean value. The legacy rule can surprise a caller who wants to encode a URL that already has a query string.

Print resolution and size

A screen code can be 300 pixels wide. A printed code needs more pixels per centimetre. For a label, generate at 600 or 1000 pixels and print at the physical size you need. A small PNG scaled up in a layout editor looks blurry and scans poorly.

A long URL makes a dense code. If you control the destination, use a short path and redirect. The code stays simple, and you can change the destination later without reprinting. Keep the redirect page fast and mobile friendly.

Limits

A code that will be printed on a curved surface needs a smaller data payload, because the modules bend with the label. Test the curve before the print run. A QR generator call returns PNG or JPEG, not SVG. Read the QR code guide for print sizes and quiet zones.

For the artwork around a printed code, use the image placeholder. For a page that is still being written, the text placeholder fills the copy slot.