Generate QR Code

Generate a QR code from any URL or text — with or without a logo

Simple QR Code

GET/api/v1/qr/generate

Generate a QR code via query parameters. Returns a raw PNG binary, SVG string, or a JSON object (base64). Best for simple use cases where you can pass the URL directly as an img src wrapper or fetch the binary.

Query Parameters

Parameter	Type	Description
`data`*	string	The URL or text to encode. Max 2048 characters.
`size`	number	Output image size in pixels (100–2000). Default: 300.
`format`	string	Output format: "png" \| "svg" \| "base64". Default: "png".
`fg`	string	Foreground (dark modules) hex color. Default: "#000000".
`bg`	string	Background hex color. Default: "#ffffff".
`margin`	number	Quiet zone size (0–10 modules). Default: 4.
`ec`	string	Error correction level: "L" \| "M" \| "Q" \| "H". Default: "M".

Example Request

curl -G "https://api.citoapi.com/api/v1/qr/generate" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "data=https://example.com" \
  -d "size=400&format=png&fg=%23000000&bg=%23ffffff&margin=4&ec=M" \
  --output qr.png

Response Types

format	Content-Type	Body
`"png"`	image/png	Raw binary buffer
`"svg"`	image/svg+xml	SVG string (logo not supported in SVG mode)
`"base64"`	application/json	JSON: `{ success, data: { image, format, size } }`

JavaScript Example

Fetch binary and use as an img src:

// Option A — fetch and use as <img> src (binary response)
const params = new URLSearchParams({
  data: 'https://example.com',
  size: '400',
  format: 'png',
  fg: '#000000',
  bg: '#ffffff',
  margin: '4',
  ec: 'M',
});

const res = await fetch(
  `https://api.citoapi.com/api/v1/qr/generate?${params}`,
  { headers: { 'x-api-key': YOUR_KEY } }
);
const blob = await res.blob();
const imgSrc = URL.createObjectURL(blob);
// <img src={imgSrc} />

QR Code with Logo

POST/api/v1/qr/generate

Generate a QR code with an embedded logo via a JSON body. Error correction is automatically forced to H when a logo is present to maintain scannability. Logo is passed as a base64 data URL.

Query Parameters

Parameter	Type	Description
`data`*	string	The URL or text to encode. Max 2048 characters.
`size`	number	Output image size in pixels (100–2000). Default: 300.
`format`	string	"png" \| "svg" \| "base64". Default: "png".
`foreground`	string	Foreground hex color. Default: "#000000".
`background`	string	Background hex color. Default: "#ffffff".
`margin`	number	Quiet zone (0–10). Default: 4.
`errorCorrection`	string	"L" \| "M" \| "Q" \| "H". Auto-forced to "H" when logo is present.
`logo.image`	string	Base64 data URL (data:image/png;base64,...) or raw base64 string.
`logo.sizeRatio`	number	Logo width as fraction of QR size (0.1–0.35). Default: 0.25.
`logo.padding`	number	White padding behind logo in px (0–50). Default: 8.

Example Request

curl -X POST "https://api.citoapi.com/api/v1/qr/generate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": "https://example.com",
  "size": 400,
  "format": "png",
  "foreground": "#000000",
  "background": "#ffffff",
  "margin": 4,
  "errorCorrection": "M",
  "logo": {
    "image": "data:image/png;base64,iVBORw0KGgo...",
    "sizeRatio": 0.25,
    "padding": 8
  }
}' --output qr-with-logo.png

JavaScript Logo Upload Example

Convert a file input to base64 and POST it:

// POST with logo (file input → base64)
async function generateQrWithLogo(url, logoFile) {
  const base64 = await new Promise((resolve) => {
    const reader = new FileReader();
    reader.onload = (e) => resolve(e.target.result);
    reader.readAsDataURL(logoFile);
  });

  const res = await fetch('https://api.citoapi.com/api/v1/qr/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': YOUR_KEY,
    },
    body: JSON.stringify({
      data: url,
      size: 400,
      format: 'png',
      logo: { image: base64, sizeRatio: 0.25, padding: 8 },
    }),
  });

  const blob = await res.blob();
  return URL.createObjectURL(blob);
}

Base64 JSON Response

Use "format": "base64" to receive a JSON response instead of a binary buffer — useful in environments where binary blobs are harder to handle.

Request

curl -X POST "https://api.citoapi.com/api/v1/qr/generate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":"https://example.com","format":"base64"}'

Response

{
  "success": true,
  "data": {
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "format": "png",
    "size": 300
  }
}

Error Responses

All validation errors return HTTP 400 with a JSON body:

{
  "success": false,
  "error": ""data" is required and must be a string"
}

Status	Cause
`400`	Missing or invalid parameters (data, size out of range, invalid hex color, etc.)
`401`	Missing or invalid x-api-key header
`429`	Rate limit exceeded for your plan
`500`	Internal server error

QR Code API Overview