AI QR Code Art: How It Works and How to Make Sure It Scans

A scanner ignores the picture. It looks for a grid of small squares, called modules, and decides whether each one is dark or light. It depends on a few fixed parts defined in the ISO/IEC 18004 standard:

• Finder patterns. The three large squares in the corners, each 7 × 7 modules. The reader uses them to find the code, measure it and tell which way up it is.
• Timing patterns. Lines of alternating modules between the finder squares that show how wide each module is.
• Alignment patterns. Smaller squares, from version 2 upward, that help correct for tilt.
• Format information. Modules beside the finder squares, stored twice, that record the error correction level and mask.
• Contrast. Dark modules must be clearly darker than light ones. Hue does not matter; brightness does.
• A quiet zone. A plain light margin 4 modules wide, so the reader can tell where the code ends.
• Module size. Each module must cover enough camera pixels at the scanning distance.

Art has to leave all of those parts readable. Inside the data area there is some freedom. Around the finder squares and in the margin there is almost none.

Every QR code carries extra Reed–Solomon error correction data, so a reader can rebuild the message when some modules are wrong. At level L roughly 7% of the codewords can be recovered, at M 15%, at Q 25% and at H 30%. That budget is what gives art room. Three limits matter:

• It only covers the data. Error correction cannot rebuild a finder square. If the corners become flowers, the reader never gets far enough to use it.
• Damage adds up. One wrong module spoils its whole 8-module codeword, so scattered changes use the budget faster than one solid patch. Glare, blur and print grain draw on the same budget.
• More correction means more modules. A 37-character short link makes a 29 × 29 code at level M and a 37 × 37 code at level H.

A worked example: a poster carries a code about 6 cm wide. At level M each module is about 2.1 mm (60 ÷ 29). At level H it is about 1.6 mm (60 ÷ 37), so the H version has to be read from closer. The common rule of thumb of a scanning distance about ten times the code’s width assumes a clean code; busy art needs a larger print or a shorter distance. The error correction guide covers the levels in depth, and the size guide covers distance.

There are three common approaches. Each trades artistic freedom against scan reliability.

• Guiding an image model with the code’s pattern. A diffusion model draws the picture while a control input pushes each area toward dark or light where the modules need it. ControlNet, a technique published in February 2023, is a widely used way to add that kind of guidance. A strength setting decides how much the pattern wins over the art.
• Blending after generation. The image is made first, then pixels are darkened or lightened toward the module pattern, usually most strongly at the center of each module, where readers sample.
• Drawing the code as an object in the scene. The model paints the code onto something in the picture, such as a sign, a tile or a label. The code keeps its structure, but its size and angle need checking.

None of these guarantees a working code. Image models copy the look of a QR code better than its exact pattern, so an image can look right and decode to nothing, or to a different link. The only reliable check is to decode the finished image.

Many phones read light-on-dark codes, but not every scanner app does, so inverted art is a gamble for print.

In CirculateQR, a Gemini image model paints the code’s real short link into the scene you choose. It is instructed to reproduce every module, keep a light margin and strong contrast, and place the code on a flat surface, tilted no more than about 30 degrees and never curved, cropped or covered. You choose how much of the image the code takes up: tiny (about 5–8%), small (10–15%), medium (20–25%) or large (30–40%). A density setting picks the error correction: low is L, standard (the default) is M, high is H.

1. Verify. The image is decoded with ZXing-C++ at several sizes (longest side 4,096, 2,048, 1,400, 1,000 and 700 pixels), with jsQR as a fallback. It passes only if it decodes to the exact expected link, and is then labeled “✓ Scans”.
2. Correct. If it fails, the code’s four corners are located and the true pattern is redrawn in place, in perspective, in the artwork’s own light and dark tones, with a minimum contrast enforced, classic finder squares and a light margin. If no code can be found at all, the image is regenerated once instead.
3. Verify again. A pass is labeled “✓ Scans (corrected)”. Anything that still fails is labeled “⚠ Not verified”: test it with your phone before using it.

The raw AI version is always kept for comparison. The “keep the raw AI art” option skips the correction, and the result may not scan. To change an image, you describe the change in a text prompt, and the new version is verified again. There is no brush or region editor.

AI art is available on every plan through AI credits: 10 a month on Studio, 50 on Artisan and 250 on Stealth. The free plan includes no AI credits, but AI credit packs (from $9 for 10) can be bought on any plan, including Free, and never expire. Artisan and Stealth include all 124 scene templates; on lower plans the first template in each category is free and the rest are sold separately. Images are 2K by default; 4K needs Artisan (10 a month) or Stealth (50 a month). See features and pricing.

An automatic decode proves the file holds the right link. It cannot tell you how the print behaves on a wall. Before a print run:

1. Print a proof at the real size on the real material. Paper is duller than a screen, and printing shifts colors.
2. Use several phones: at least two iPhones and two Android phones, including an older or cheaper one.
3. Try two readers: the built-in camera app and Google Lens. A code that works in one can fail in the other.
4. Scan at the real distance and lighting. If the poster hangs 2 meters away in a dim bar, test it there.
5. Scan from angles, from the side and from below, the way people actually stand.
6. Check the destination, and retest after any change to size, crop or color.