API TUTORIAL · 9 MIN READ
A working QR integration is more than an image request. Here is how to handle output types, quotas, print-safe defaults and failures in production.
By StadiaSoft · Updated 25 September 2026 · We publish the API discussed here, and we explain its limitations as well as its uses.
A QR code API is useful when a server needs consistent codes for tickets, invoices, labels or customer-facing documents. The hard part is rarely drawing one square. It is delivering the right format to the next system, keeping credentials out of the browser, and making a printed code reliably scannable.
This guide uses the StadiaSoft QR Code Generator API on RapidAPI. It generates static codes. The service does not host redirects, change destinations after generation or track scans. If you need those features, add a separate redirect and analytics layer.
Choose the response before you write the request
| Format | Response | Best fit | Common mistake |
|---|---|---|---|
| PNG | Binary image/png | Download, attachment or PDF image workflow | Calling response.json() on image bytes |
| SVG | JSON containing SVG markup | Scalable layouts and supported print systems | Assuming the data is a hosted URL |
| Base64 | JSON containing a PNG data URL | JSON-driven pipelines | Storing large data URLs unnecessarily |
Use PNG when the next tool expects a normal image file. SVG is suitable when a trusted renderer accepts SVG. Base64 makes JSON handoffs convenient, but increases payload size; decode it when a downstream tool expects a file.
Generate one QR code in Node.js
Subscribe to the API, put your RapidAPI key in a server-side environment variable, and use Node.js 18 or later for built-in fetch. Never ship the key in browser JavaScript or a public repository. RapidAPI documents the required host and key headers.
const host = "qr-code-generator-api63.p.rapidapi.com";
const key = process.env.RAPIDAPI_KEY;
if (!key) throw new Error("Set RAPIDAPI_KEY on your server");
const response = await fetch(`https://${host}/api/v1/qr/generate`, {
method: "POST",
headers: {
"content-type": "application/json",
"x-rapidapi-host": host,
"x-rapidapi-key": key,
},
body: JSON.stringify({
text: "https://example.com/order/1002",
format: "base64",
size: 600,
errorCorrectionLevel: "M",
margin: 4,
darkColor: "#12304A",
lightColor: "#FFFFFF",
}),
});
if (!response.ok) {
throw new Error(`QR generation failed (${response.status}): ${await response.text()}`);
}
const result = await response.json();
if (!result.success || result.format !== "base64" ||
!result.data.startsWith("data:image/png;base64,")) {
throw new Error("Unexpected QR API response");
}
console.log(result.data.slice(0, 30));
The response shape is {"success":true,"format":"base64","data":"data:image/png;base64,..."}; the ellipsis stands for the real image data. For a PNG response, change the format to png, verify the content type and read Buffer.from(await response.arrayBuffer()). Do not call response.json() on PNG bytes. For SVG, parse JSON and use the returned markup.
Bulk QR generation without quota surprises
The bulk endpoint accepts 1–50 items and returns Base64 PNG data URLs with per-item status. An invalid item does not cancel valid ones. Here is the request body:
{"items":[{"text":"https://example.com/ticket/A-100","size":450},{"text":"https://example.com/ticket/A-101","size":450}]}Send that JSON to POST /api/v1/qr/generate/bulk with the same RapidAPI headers. Inspect total, generated, failed and each entry in results; do not assume that an HTTP 200 means every item succeeded.
Quota math: a bulk call generating 10 codes consumes one Requests unit and 10 QRCodes units. The free Basic plan currently includes 50 requests and 50 generated QR codes per month. A 50-item batch can therefore use the whole free code allowance in one call. The bulk response also has a 4 MB safety limit; split large jobs into smaller chunks. Check current plans before scaling a workflow.
Design for scanning, not just appearance
Keep the default four-module margin unless you have measured the actual output. DENSO WAVE specifies a four-module quiet zone around a QR code. Removing it for a tighter visual can make scanning unreliable.
Error correction is a tradeoff, not a guarantee. The API supports L, M, Q and H. DENSO WAVE explains that higher recovery levels require more encoding space. Start with M, then test the actual destination length, display or print size and environment. Keep dark modules darker than the background. Test branded colors in the final medium, not just on a desktop preview.
- Encode the shortest stable destination you control; long URLs make denser codes.
- Preserve the quiet zone and strong contrast.
- Export at the size the print or UI workflow needs; the API accepts 100–2,000 pixels.
- Scan a proof on multiple devices in realistic lighting and at the smallest intended size.
- Verify the opened URL and landing page, not only that a scanner sees a pattern.
Do not encode passwords, API keys or private customer data. Anyone with a camera can read the payload, and printed codes may circulate indefinitely.
Hosted API or local QR library?
A hosted API is useful for a team already orchestrating third-party APIs, shared document workflows or multiple clients. Its tradeoffs are a network call, authentication, quotas and sending the QR payload to a provider. You can also generate codes locally with node-qrcode. For one Node app, especially with offline or strict data-locality needs, the local library may be simpler and cheaper. Choose the hosted service only when its integration and operational convenience outweigh those costs.
Troubleshooting
- 400: Check empty text, unsupported format, size, color or margin, or content too large for the selected correction level. The 4,296-character request limit does not mean every string of that length can be encoded.
- 403: Check gateway hostname, key and headers.
- 413: Reduce image size or split the bulk job.
- 429: Check both monthly Requests and QRCodes usage.
- Unreadable print: Restore quiet zone, increase physical size and contrast, shorten the URL and scan a print proof.
Frequently asked questions
Can this API make dynamic QR codes?
No. It only generates static codes. You can encode a URL you control and implement your own redirects, but this API does not supply that layer.
Does a bulk call count as one free QR code?
No. It uses one Requests unit and one QRCodes unit per successful item. Basic currently includes 50 of each per month.
Which format should a PDF workflow use?
Use PNG if your PDF library expects image bytes. SVG suits systems that safely support vector artwork. Decode Base64 before handing it to a file-based PDF workflow.
Next step: Try one QR code on the free Basic plan, then scan the result in the real label, ticket or document you intend to ship. Explore more StadiaSoft API tutorials.