---
title: "Use this when you need to turn text or a URL into a real, scannable QR code rather than describing one."
method: POST
path: "/v1/generate_qr"
tags: ["developer"]
---

# Use this when you need to turn text or a URL into a real, scannable QR code rather than describing one.

`POST /v1/generate_qr`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/generate_qr`
- Auth: none declared

Use this when you need to turn text or a URL into a real, scannable QR code rather than describing one. Deterministic: same input, same output. Byte mode, error-correction level M, versions 1-10 auto-selected by length (up to 213 bytes); the encoder scores all 8 mask patterns and keeps the lowest-penalty one. Returns both the module matrix as rows of 0/1 (1 = dark module) and a ready-to-render self-contained SVG string. moduleSize sets SVG pixels per module (default 10) and quietZone the border width in modules (default 4). Example: {text:'HELLO'} -> version 1, size 21x21, byteLength 5. Longer text auto-bumps the version and matrix size; over 213 bytes returns an error.

## Request body

- object
  - `text` string, required: Text/URL to encode (up to 213 bytes).
  - `moduleSize` integer: SVG pixels per module (default 10).
  - `quietZone` integer: Quiet-zone module border (default 4).

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `text` string, required: Echo of the encoded text.
    - `version` integer, required: Auto-selected QR version (1-10).
    - `errorCorrectionLevel` 'M', required: Always "M" (medium, ~15% recovery).
    - `mask` integer, required: Chosen mask pattern (0-7), the one with the lowest penalty score.
    - `size` integer, required: Matrix dimension in modules (version*4+17, so 21-57).
    - `byteLength` integer, required: UTF-8 byte length of the encoded text.
    - `quietZone` integer, required: Quiet-zone border width in modules (echo of input, clamped 0-16; default 4).
    - `moduleSize` integer, required: SVG pixels per module (echo of input, clamped 1-40; default 10).
    - `matrix` array[], required: size x size grid; each row is an array of 0/1 where 1 is a dark module. Excludes the quiet-zone border.
      - integer[]
    - `svg` string, required: Self-contained SVG document string rendering the QR code (includes the quiet zone and moduleSize scaling): a white background rect plus a #000000 group of one rect per dark module.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)