Generate a QR or barcode with a qr code api

Use POST /v1/barcodes when you need a QR or linear barcode as a PNG or SVG image. That is the RelayPDF qr code api. It returns an image. It does not stamp the mark onto a PDF. The live endpoint page says so in the first sentence: generate a QR or barcode image (PNG or SVG); compose the mark in your HTML or with POST /v1/pdf/stamp. Docs: https://relaypdf.com/docs/barcodes.

The docs hub lists the same job: “Barcode or QR image (PNG or SVG).” OpenAPI names the body CreateBarcodeRequest. Required fields are type and text. Optional fields on that schema are format, scale, includetext, filename, response, and callbackUrl. The documented type enum is qr, code128, code39, ean13, upca, pdf417, and datamatrix. format is png or svg and defaults to png. scale is an integer from 1 to 10. includetext is a boolean. Host: https://api.relaypdf.com. Authorization: Bearer pdf_live_… Query-string keys are rejected.

It does not stamp onto a PDF

Do not treat /v1/barcodes as a watermark job. The response is image/png or image/svg+xml (or a JSON FileUrlResponse if you ask for response url). There is no pages field, no position field, and no PDF source on CreateBarcodeRequest. You cannot send a PDF url or file to this endpoint and get a marked document back.

To put a mark on a finished PDF, generate the image first, then call POST /v1/pdf/stamp with exactly one of text or image. Stamp position defaults to center. Product page: https://relaypdf.com/pdf-tools/stamp. Sibling how-to: https://relaypdf.com/blog/watermark-pdf-api. To put a mark inside a new document, generate the PNG or SVG, then embed it in the HTML you send to POST /v1/pdf (data URL or a public image URL you host). The barcode call still only produced the image.

Stamp is a PDF tool. Barcode is an image generator. Each successful tools job, including barcode, is $0.005 on the published rate card. Failed jobs are never billed. Mixing stamp fields into a barcode body is invalid_request.

Types: qr, Code 128, EAN-13, and the rest

The brief for this page is qr, code128, and ean13 to PNG or SVG. Those three are on the live enum. Use type qr for a URL, ticket token, or any free-form string you want a 2D mark for. Use type code128 for warehouse SKUs, internal tracking numbers, and other Code 128 payloads. Use type ean13 for a 13-digit retail GTIN. The same endpoint also documents code39, upca, pdf417, and datamatrix. Do not invent extra symbologies. If text fails validation for a retail type, you get structured { error: { code, message } }; failed requests are not billed.

text is a string. The docs page does not publish per-type length tables, check-digit rules, or quiet-zone sizes. Send payload text that the chosen type already accepts. Do not send HTML, markdown, or a PDF. There is no multipart upload. JSON only.

PNG vs SVG, scale, includetext

format defaults to png. Use png when you will stamp the file onto a PDF or drop it into an <img> as a raster. Use svg when you want a vector you can size in CSS or print CSS without a second raster step. OpenAPI documents both image/png and image/svg+xml on the 200 response. filename is optional; if you send one, keep the extension consistent with format. The images endpoint validates filename against screenshot type; barcodes docs list filename without a published extension table. Match png to .png and svg to .svg.

scale is optional, integer, minimum 1, maximum 10. The docs page does not define the unit as module width or CSS pixels. Treat it as a size multiplier on the generated image. Values outside 1–10 are out of schema. includetext is optional boolean. When true, the generator includes a human-readable caption with the bars. When omitted, do not assume a default in your UI; the OpenAPI schema does not publish a default for includetext. QR marks typically do not need a caption; Code 128 and EAN-13 often do.

There is no color field, no foreground/background pair, no error-correction level for QR, no GS1 flag, and no rotation on CreateBarcodeRequest. Those are not documented. If you need a color treatment, generate PNG or SVG and restyle the SVG yourself, or wrap the PNG in HTML and print with /v1/pdf.

Request and response

Every generating endpoint accepts response binary, url, or async. Binary is the default: file bytes plus x-relaypdf-id, x-relaypdf-size, and content-disposition. url returns JSON with id, status, url, filename, sizeBytes, and expiresAt; GET /v1/files/:id is a public 24-hour download and does not take an API key. async returns 202 with a pollUrl; poll GET /v1/jobs/:id with the same key until completed or failed, or set callbackUrl (https). callbackUrl on a private or http host is url_not_allowed.

Rate limits on the published card: trial 20/min, funded or auto-reload 60/min, burst 5 per 10 seconds. 429 includes Retry-After and is not billed. payment_required is 402 when the wallet is empty. New accounts get a $5.00 trial (5000 millicents). GET /v1/account is not billed. GET /health returns { ok: true } without a key.

curl, CLI, Python

The barcodes docs sample is a QR PNG. Same body on the CLI as relaypdf barcode --type qr --data 'https://relaypdf.com' --out qr.png. The Python SDK (0.1.2) exposes barcodes.create(**input) and barcodes.qr(text, **extra). The README sample is qr = client.barcodes.qr("https://relaypdf.com"). JSON field names stay camelCase: type, text, format, includetext, callbackUrl.

curl -X POST https://api.relaypdf.com/v1/barcodes
  -H "Authorization: Bearer pdf_live_…"
  -H "Content-Type: application/json"
  -d '{
    "type": "qr",
    "text": "https://relaypdf.com",
    "format": "png"
  }'
  --output qr.png
curl -X POST https://api.relaypdf.com/v1/barcodes
  -H "Authorization: Bearer pdf_live_…"
  -H "Content-Type: application/json"
  -d '{
    "type": "code128",
    "text": "PKG-1042-A",
    "format": "png",
    "includetext": true,
    "scale": 3,
    "filename": "tracking.png"
  }'
  --output tracking.png
curl -X POST https://api.relaypdf.com/v1/barcodes
  -H "Authorization: Bearer pdf_live_…"
  -H "Content-Type: application/json"
  -d '{
    "type": "ean13",
    "text": "5901234123457",
    "format": "svg",
    "includetext": true
  }'
  --output gtin.svg
import os
from relaypdf import RelayPDF
client = RelayPDF(api_key=os.environ["RELAYPDF_API_KEY"])
qr = client.barcodes.qr("https://relaypdf.com")
qr.save("qr.png")
ean = client.barcodes.create(
    type="ean13",
    text="5901234123457",
    format="png",
    includetext=True,
)

Compose after you have the image

Two documented compose paths, neither of them this endpoint. Path one: HTML. Insert the PNG as a data URL or host the 24-hour file URL from response url, then POST /v1/pdf. Path two: stamp. POST /v1/pdf/stamp with image set to the barcode bytes (base64 file in JSON; SDKs accept bytes) or a url to the image, plus the PDF url or file. Stamp accepts exactly one of text or image. Do not send the barcode payload as stamp text unless you want literal characters, not bars.

MCP and CLI expose the same job. CLI: relaypdf barcode --type qr --data …. MCP tool name: barcode. Do not ask a human to paste a key; run npx @relaypdf/cli setup and approve in the browser. Credentials live in ~/.config/relaypdf/credentials.json with mode 0600 and are never printed.

What this is not

This is not OCR, not a scanner, and not an e-sign flow. POST /v1/pdf/text extracts an existing text layer and does not OCR. There is no published barcode-read endpoint. This is not POST /v1/images (Chromium screenshot of HTML or a URL). It is not POST /v1/pdf/raster (PDF pages to PNG or JPEG). It is not POST /v1/pdf/from-images (images assembled into a PDF). It does not stamp onto a PDF.

Field list and the PNG example live at https://relaypdf.com/docs/barcodes. Schema: https://relaypdf.com/openapi.json (CreateBarcodeRequest). Hub: https://relaypdf.com/docs. If you need a marked PDF, generate the image here, then stamp or print.