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.
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)
Authorization: Bearer YOUR_API_KEY_HERE
Option 2: URL Query Parameter
https://www.qrstudio.luxconvo.com/api/qr/generate?api_key=YOUR_API_KEY_HERE&text=https://example.com
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.
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). |
⑥ Center Logo & Badges
| 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:
{
"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"
}
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.
https://www.qrstudio.luxconvo.com/api/qr/styles
Returns JSON: { "eyes": [...], "eyeDots": [...], "dots": [...], "logos": [...] }. Pass ?format=json or Accept: application/json.
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.
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:
text or malformed payload.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:
{
"error": "Free anonymous daily limit reached (50 requests per 24 hours).\nSign up for an API key or upgrade your account."
}