QRay API

Генерируйте QR-коды из своих приложений через простой REST API: все 8 типов данных, PNG и SVG, цвета, градиенты, логотипы и рамки — всё, что умеет веб-генератор.

Получить API-ключ https://stg.qray.io/api/v1

Попробуй прямо сейчас — без регистрации

Вставь это в терминал. Один запрос — и у тебя готовый QR-код:

curl -X POST https://stg.qray.io/api/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"qr":{"type":"url","fields":{"url":"https://qray.io"},"style":{"dot_style":"rounded","gradient":{"colors":["#2563EB","#A3E635"],"angle":45}}}}' \
  -o qr.png && open qr.png

Откроет qr.png (macOS; на Linux — xdg-open qr.png). Ключ не нужен: демо разрешает 10 запросов в час с одного IP.

Аутентификация

Каждый запрос должен содержать API-ключ в заголовке X-Api-Key. Ключи создаются и управляются в личном кабинете.

curl https://stg.qray.io/api/v1/usage \
  -H "X-Api-Key: qray_live_YOUR_KEY"

Полный ключ показывается один раз — при создании. Храните его в секрет-менеджере: у нас остаётся только SHA-256 дайджест.

Быстрый старт

Сгенерировать стилизованный QR-код для ссылки:

curl -X POST https://stg.qray.io/api/v1/generate \
  -H "X-Api-Key: qray_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qr": {
      "type": "url",
      "fields": { "url": "https://example.com" },
      "format": "png",
      "size": 512,
      "style": {
        "fg_color": "#111113",
        "dot_style": "rounded",
        "gradient": { "colors": ["#2563EB", "#A3E635"], "angle": 45 }
      }
    }
  }'

Ответ содержит картинку в base64 и постоянные ссылки:

{
  "hash": "1c9a7f2b40d861e3",
  "format": "png",
  "size": 512,
  "image": "iVBORw0KGgoAAA…",          // base64
  "image_url": "https://stg.qray.io/qr/1c9a7f2b40d861e3.png",
  "share_url": "https://stg.qray.io/qr/1c9a7f2b40d861e3",
  "url": "/qr/1c9a7f2b40d861e3"
}

Эндпоинты

Эндпоинт	Описание
`POST /api/v1/demo`	Сгенерировать картинку QR без ключа (демо, 10/час с IP)
`POST /api/v1/generate`	Сгенерировать QR-код; вернёт base64-картинку и постоянные ссылки
`GET /api/v1/qr_codes`	Список ваших QR-кодов (по 50 на страницу, ?page=N)
`GET /api/v1/qr_codes/:hash`	Метаданные одного QR-кода
`GET /api/v1/qr_codes/:hash/image`	Бинарная картинка (PNG/SVG); ссылка не протухает
`DELETE /api/v1/qr_codes/:hash`	Удалить QR-код
`GET /api/v1/usage`	Текущий план, дневной лимит и расход
`GET /api/v1/api_keys`	Список ваших API-ключей
`POST /api/v1/api_keys`	Создать дополнительный ключ ({"name": "…"})
`DELETE /api/v1/api_keys/:id`	Отозвать ключ (ключ текущего запроса отозвать нельзя)

Нужна машиночитаемая спека? Открой интерактивно или импортируй наш OpenAPI-файл в Postman, Insomnia или генератор клиента: Интерактивный API-эксплорер · openapi.yaml

Типы QR и их поля

Тип данных передаётся в qr.type, его поля — в qr.fields:

type	fields
`url`	`url`
`text`	`text`
`wifi`	`ssid`, `password`, `encryption` (WPA \| WEP \| nopass), `hidden` (true \| false)
`vcard`	`first_name`, `last_name`, `phone`, `email`, `org`, `title`, `url`
`email`	`address`, `subject`, `body`
`phone`	`number`
`sms`	`number`, `message`
`geo`	`latitude`, `longitude`

Например, WiFi-QR, который гости сканируют для подключения:

curl -X POST https://stg.qray.io/api/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"qr":{"type":"wifi","fields":{"ssid":"MyCafe","password":"latte123","encryption":"WPA"}}}' \
  -o wifi.png && open wifi.png

Опции и стилизация

Параметр	Описание
`format`	`png` (default) \| `svg`
`size`	`256` \| `512` (default) \| `1024` \| `2048`
`style.fg_color`, `style.bg_color`	hex, e.g. `#111113`
`style.dot_style`	`square` (default) \| `circle` \| `rounded`
`style.eye_style`	`square` (default) \| `rounded`
`style.gradient`	`{ "colors": ["#hex", "#hex", …], "angle": 0–360 }` — два и более цветов; перекрывает fg_color
`style.frame`	`{ "type": "scan-me" \| "custom-text", "text": "…", "color": "#hex" }` — только PNG; для SVG игнорируется
`style.logo_data`	PNG/JPG в сыром base64 (без префикса data:), до ~500 КБ. Коррекция ошибок повышается автоматически.

Картинки кэшируются на 24 часа, затем прозрачно регенерируются — image_url постоянен, его можно хотлинкать.

Планы и лимиты

У каждого ключа дневная квота, сбрасывается в полночь UTC:

План	Запросы
free	100 запросов / день
pro	10 000 запросов / день
enterprise	100 000 запросов / день

Каждый ответ содержит состояние текущего окна:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

Нужен pro или enterprise? Напишите на support@qray.io — переключим ключ.

Ошибки

HTTP	`error`	Описание
400	`missing_parameter`	Некорректный запрос (например, нет параметра qr)
401	`unauthorized`	Ключ отсутствует, неверен или отозван
404	`not_found`	QR-код не найден (или принадлежит другому аккаунту)
422	`unknown_type`	Неизвестный qr.type
429	`rate_limited`	Дневной лимит исчерпан — повторите после полуночи UTC или обновите план
503	`service_unavailable`	Сервис генерации временно недоступен — повторите с бэкоффом