QRStudio API DOCS
← Home Launch Studio { } Raw JSON Get API Key

QR Studio Developer API

Welcome to the complete developer documentation for the QR Studio API engine. All design capabilities implemented in the interactive QR Studio—such as 20+ body dot shapes, 17+ corner eye frames, 20+ eye center dots, 4-direction gradients, individual 3-corner colorization, independent 90° rotation, and branded logo plates—are fully accessible programmatically via RESTful endpoints.

⚡ Base API Endpoint

All endpoints are served from: https://www.qrstudio.luxconvo.com/api/qr

Authentication

Programmatic requests (servers, worker scripts, mobile apps, Python, Node.js) require a valid API key. You can generate up to 5 named API keys from your Developer Dashboard.

Authenticate your requests using either method:

Option 1: Authorization Header (Recommended)

HTTP Header
Authorization: Bearer YOUR_API_KEY_HERE

Option 2: URL Query Parameter

Query String
https://www.qrstudio.luxconvo.com/api/qr/generate?api_key=YOUR_API_KEY_HERE&text=https://example.com
🔒 Origin Security Notice

Free unauthenticated generation is permitted exclusively from within the official website studio session. Direct automated requests without a bearer token or api_key receive a 401 Unauthorized response.

Rate Limits & Rolling Quotas

Quotas operate on an anchored, rolling 24-hour window from your exact first request, ensuring equitable throughput without sudden midnight resets.

Plan Tier Daily Request Quota Window Duration Pricing
Free Studio Visitor 50 requests / day 24-hour rolling per IP $0
Starter Tier 1,000 requests / day 24-hour rolling per user $9.99 / mo
Pro Tier 10,000 requests / day 24-hour rolling per user $29.99 / mo
Enterprise Tier Unlimited Dedicated Throughput Custom

Rate Limit Response Headers

Every response returns standardized rate limit headers to help your application track quota consumption in real time:

Response Header Description Example
X-RateLimit-Limit Maximum permitted requests in your current 24-hour window 1000
X-RateLimit-Remaining Remaining requests available before throttling occurs 984
Retry-After Only present when throttled (HTTP 429). Seconds until reset 3600

Endpoint: Generate QR Code

Generate a custom branded, vector SVG QR code. Accepts both POST (recommended for complex or large payloads) and GET requests.

POST GET https://www.qrstudio.luxconvo.com/api/qr/generate

• Vector SVG (Default): image/svg+xml; charset=UTF-8 (Direct scalable stream)

• Hosted PNG (format=png): application/json (Temporary public URL valid for 24 hours)

• Direct PNG Binary (format=png&raw=1): image/png (Direct binary PNG stream)

① Content, Dimensions & Output Format

Parameter Type Requirement Default Description
text string Required — The URL or text payload to encode (max 2,000 characters).
format string Optional svg Output format: svg (default) or png. When format=png, returns a JSON response containing a hosted temporary image URL valid for 24 hours. (Alias: response_type).
padding integer Optional 4 Quiet zone padding around the QR code matrix (min 0, max 20). Set padding=0 for a zero-margin borderless QR code. (Alias: margin).
raw integer Optional 0 When format=png, pass raw=1 or download=1 to stream binary PNG image directly instead of JSON.
size integer Optional 300 Pixel bounding box (min 30, max 4,096). Examples: 150, 300, 500, 1000.
width integer Optional — Explicit output width in pixels.
height integer Optional — Explicit output height in pixels.
scale integer Optional 10 Module matrix scale factor (min 4, max 40).

② Module Colors & Gradients

Parameter Type Default Description
color string (hex) #000000 Primary foreground color (e.g. #7b6cf6). URL encode as %237b6cf6.
bgcolor string (hex) #ffffff Background color (e.g. #ffffff or #0b0b18 for dark mode).
gradient integer 0 Set to 1 to enable color gradients across the body.
color2 string (hex) — Secondary gradient color when gradient=1 (e.g. #f368e0).
gradient_dir string diag Direction: diag (↘ diagonal), horiz (→ horizontal), vert (↓ vertical), or radial (⦿ radial circular).

③ Corner Eye Colors & Modes

Parameter Type Default Description
eye_mode string sync sync: Eyes automatically follow module color.
single: All 3 eyes share custom frame & center dot colors.
individual: Customize Top-Left, Top-Right, and Bottom-Left separately!
eyecolor string (hex) — Outer eye frame color when eye_mode=single.
eye_inner_color string (hex) — Inner center eye dot color when eye_mode=single.
eye_tl_color string (hex) — Top-Left eye frame color (individual mode).
eye_tl_inner_color string (hex) — Top-Left center eye dot color (individual mode).
eye_tr_color string (hex) — Top-Right eye frame color (individual mode).
eye_tr_inner_color string (hex) — Top-Right center eye dot color (individual mode).
eye_bl_color string (hex) — Bottom-Left eye frame color (individual mode).
eye_bl_inner_color string (hex) — Bottom-Left center eye dot color (individual mode).

④ Body & Eye Shape Matrix

Parameter Type Default Description
dot string square Shape of the QR matrix body dots. See 20+ Dot Catalog.
eye string square Shape of the outer eye frame ring. See 17+ Eye Frame Catalog.
eye_dot string square Shape of the inner center eye dot. See 20+ Eye Dot Catalog.
eye_tl_dot string — Individual shape override for the Top-Left inner center dot.
eye_tr_dot string — Individual shape override for the Top-Right inner center dot.
eye_bl_dot string — Individual shape override for the Bottom-Left inner center dot.

⑤ Eye Frame & Center Dot Rotation

Parameter Type Default Description
eye_frame_rot integer 0 Global outer frame rotation in degrees: 0, 90, 180, or 270.
eye_dot_rot integer 0 Global inner center dot rotation in degrees: 0, 90, 180, or 270.
eye_tl_rot / eye_tl_dot_rot integer 0 Top-Left frame / dot rotation (0, 90, 180, 270).
eye_tr_rot / eye_tr_dot_rot integer 0 Top-Right frame / dot rotation (0, 90, 180, 270).
eye_bl_rot / eye_bl_dot_rot integer 0 Bottom-Left frame / dot rotation (0, 90, 180, 270).
Parameter Type Default Description
logo string — Preset logo name (e.g. scanme, whatsapp, instagram) or Base64 Data URI (data:image/svg+xml;base64,...).
logo_mode string clean clean: Removes QR dots behind the logo for pristine contrast. overlay: Keeps all QR dots intact.
logo_size integer 22 Logo diameter as percentage of QR width (10 to 35).
logo_shape string rounded Card plate badge shape: rounded (rounded card), circle (circle badge), square (square card), or none (no plate).
logo_bg string (hex) #ffffff Background color of the logo badge plate.
logo_pad integer 8 Padding around logo inside the plate card in pixels (0 to 24).

⑦ Output Formats & 24-Hour Temporary URLs

QR Studio supports both native vector SVG streaming and high-resolution raster PNG generation with automatic 24-hour hosted storage:

Format Mode Query Parameters Response Type Output Behavior
Vector SVG (Default) format=svg (or omitted) image/svg+xml Streams crisp, scalable vector XML directly to client. Best for web design and high-DPI print.
Temporary Hosted PNG format=png application/json Rasterizes the QR code with full gradient, eye, and logo fidelity, stores it temporarily, and returns a JSON payload with a direct URL valid for 24 hours.
Direct PNG Binary format=png&raw=1 image/png Streams binary PNG image directly with inline disposition. Ideal for <img src="..."> tags and download scripts.
Zero-Margin Borderless padding=0 SVG or PNG Disables the quiet zone padding, producing a compact borderless QR code that fills 100% of the canvas.

Sample JSON Response for format=png:

JSON Response (HTTP 200)
{
  "status": "success",
  "format": "png",
  "url": "https://www.qrstudio.luxconvo.com/temp/qrcodes/qr_7a8f9c01de3b5c6e8f1a2b3c4d5e6f7a.png",
  "filename": "qr_7a8f9c01de3b5c6e8f1a2b3c4d5e6f7a.png",
  "expires_in_hours": 24,
  "expires_at": "2026-11-12T01:04:56+00:00"
}
🕒 24-Hour Lifecycle & Automated Cleanup

Generated PNG files are hosted in high-speed public cache and are valid for exactly 24 hours. An automated hourly background cron job cleans up expired files, ensuring optimal performance and zero storage leaks.

Visual Presets & Styles Catalog

The GET /api/qr/styles endpoint provides programmatically queryable lists of all available shapes, corner frames, eye dots, and brand logos. Click any card below to copy its exact parameter to your clipboard.

GET https://www.qrstudio.luxconvo.com/api/qr/styles

Returns JSON: { "eyes": [...], "eyeDots": [...], "dots": [...], "logos": [...] }. Pass ?format=json or Accept: application/json.

Copy circle
circle
Copy circle-zebra
circle-zebra
Copy circle-zebra-cut
circle-zebra-cut
Copy circle-zebra-cut-vertical
circle-zebra-cut-vertical
Copy circle-zebra-vertical
circle-zebra-vertical
Copy circular
circular
Copy cross
cross
Copy diamond
diamond
Copy donut
donut
Copy dot
dot
Copy edg-cut-pointed
edg-cut-pointed
Copy edg-cut-pointed-in
edg-cut-pointed-in
Copy edg-cut-pointed-smooth
edg-cut-pointed-smooth
Copy edg-cut-round
edg-cut-round
Copy edg-cut-sharp
edg-cut-sharp
Copy edge-cut-smooth
edge-cut-smooth
Copy heart
heart
Copy hexagon
hexagon
Copy japnese
japnese
Copy leaf
leaf
Copy mosaic
mosaic
Copy pointed
pointed
Copy pointed-edge-cut
pointed-edge-cut
Copy pointed-in
pointed-in
Copy pointed-in-smooth
pointed-in-smooth
Copy pointed-smooth
pointed-smooth
Copy round
round
Copy rounded
rounded
Copy rounded-in
rounded-in
Copy rounded-in-smooth
rounded-in-smooth
Copy rounded-pointed
rounded-pointed
Copy square
square
Copy star
star
Copy ticket
ticket

Interactive API Console & Playground

Test parameters in real time. Adjust options below and click "Execute Request" to view the live generated SVG and copy the exact request parameters.

Live API Preview
Status: 200 OK (Vector SVG)

Code Examples

Copy production-ready integration snippets in your programming language of choice:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "text=https://myapp.com" \
  -d "dot=leaf" \
  -d "eye=shield" \
  -d "eye_dot=circle" \
  -d "color=%236366f1" \
  -d "gradient=1" \
  -d "color2=%23a855f7" \
  -d "gradient_dir=diag" \
  -d "logo=scanme" \
  -o "my-qrcode.svg" \
  "https://www.qrstudio.luxconvo.com/api/qr/generate"

HTTP Status Codes & Error Handling

The API utilizes conventional HTTP response codes to indicate request outcomes. Inspect error payloads to handle edge cases programmatically:

200 OK Success
Request succeeded. Returns crisp vector SVG XML content.
400 Bad Request Bad Request
Missing required parameter text or malformed payload.
401 Unauthorized Unauthorized
Missing, revoked, or invalid API key on external request.
403 Forbidden Forbidden
Account has been suspended or email address unverified.
422 Unprocessable Validation Error
Invalid parameter value (e.g. invalid hex color, text exceeding 2,000 chars).
429 Too Many Requests Quota Exceeded
Daily rate limit reached. Inspect Retry-After header for reset countdown.

Error Response Schema

When an error occurs, the API returns a structured JSON payload explaining the reason for rejection:

JSON Error Response (HTTP 4xx)
{
  "error": "Free anonymous daily limit reached (50 requests per 24 hours).\nSign up for an API key or upgrade your account."
}