> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a QR code

> Create a PNG, SVG, or Base64 QR code through your configured AvraAPI QR Generator.

Generate a QR code from text, a URL, or another compact value. PNG is the default response. SVG is available when you need a vector result, and `base64` returns a PNG data URI inside the normal JSON envelope.

In the Playground, select `png` or `svg` to receive an image response, or select `base64` to inspect the JSON data-URI response. Generated artifacts are real and can consume Development-project credits.

<Info>
  **Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
</Info>

## API endpoint

```text title="POST" theme={null}
https://avraapi.com/api/v1/utilities/qr/generate
```

## Request fields

| Field | Required | Rules |
| - | - | - |
| `data` | Yes | Text to encode; 1–4,096 characters. URLs and vCards are supported as ordinary text values. |
| `format` | No | `png` (default), `svg`, or `base64`. PNG and SVG return media; `base64` returns JSON. |
| `size` | No | Output size from 50 to 2,000 pixels; default `300`. |
| `margin` | No | Quiet-zone margin from 0 to 20 modules; default `2`. |
| `foreground_color` | No | Six-digit hex colour, with or without `#`; default black (`000000`). |
| `background_color` | No | Six-digit hex colour, with or without `#`; default white (`ffffff`). |
| `logo_url` | No | Publicly accessible HTTP or HTTPS image URL, up to 2,048 characters. A logo is applied to PNG and Base64 output; SVG does not include it. |
| `logo_size_percent` | No | Centred-logo width from 5% to 40% of the QR width; default `20`. |
| `privacy_mode` | No | Boolean request-level privacy setting. Use the shared `X-Privacy-Mode: 1` header when you need the platform-wide privacy guarantee. |

When `logo_url` is supplied, AvraAPI fetches the image while producing the code. Use a public image you control; the logo must be reachable, use HTTP or HTTPS, and stay within the 512 KB logo limit. The QR error-correction level is raised automatically so the centred logo remains scannable.

## Request example

```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/utilities/qr/generate" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: image/png" \
  --header "Content-Type: application/json" \
  --data '{
    "data": "https://example.com/receipt/ORDER-2026-001",
    "format": "png",
    "size": 400,
    "logo_url": "https://example.com/brand-mark.png",
    "logo_size_percent": 20
  }' \
  --output order-qr.png
```

## Media response

For `png`, the successful response body is the PNG itself with `Content-Type: image/png`. For `svg`, it is SVG media with `Content-Type: image/svg+xml`. Both include `Content-Length`, `Cache-Control: no-store`, `Content-Disposition: inline`, and `X-APIX-Request-ID` response headers.

There is no JSON success envelope for those image formats. Save the binary response or pass it directly to your own image pipeline; do not parse it as JSON.

## Base64 JSON response

Use `format: "base64"` only when a JSON data URI suits your application. It is a PNG data URI, not raw Base64 bytes.

```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/utilities/qr/generate" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"data":"https://example.com/receipt/ORDER-2026-001","format":"base64"}'
```

```json theme={null}
{
  "success": true,
  "request_id": "01f00000-0000-4000-8000-000000000021",
  "data": {
    "format": "base64",
    "data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}
```

## Error codes

| HTTP | `error.code` | When it happens | What to do |
| - | - | - | - |
| `400` | <span style={{ whiteSpace: 'nowrap' }}><code>http\_error</code></span> | QR generation cannot process the supplied value, colour, or logo URL. An unreachable, unsupported, or oversized logo can produce this outcome. | Correct the value or use a reachable public image, then submit a new request. |
| `401` | <span style={{ whiteSpace: 'nowrap' }}><code>unauthorized</code></span> | Credentials are missing, invalid, inactive, or do not match `X-ENV`. | Check your backend credential configuration. |
| `402` | <span style={{ whiteSpace: 'nowrap' }}><code>insufficient\_funds</code></span> | The selected QR Generator integration requires credits that are unavailable. | Check the project balance and service configuration. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>validation\_failed</code></span> | A field is missing or outside its documented type, size, colour, URL, or range rules. | Correct the body using the field details in the response. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>provider\_selection\_failed</code></span> | No active QR Generator integration can be selected for the project environment. | Enable or configure the QR Generator integration. |
| `429` | <span style={{ whiteSpace: 'nowrap' }}><code>rate\_limit\_exceeded</code></span> | The configured request limit was reached. | Respect `Retry-After` when present. |
| `500` | <span style={{ whiteSpace: 'nowrap' }}><code>internal\_error</code></span> | The generator could not complete unexpectedly. | Retain the request ID and retry only when your workflow permits it. |
| `503` | <span style={{ whiteSpace: 'nowrap' }}><code>project\_paused</code></span> | The project is paused. | Reactivate the project before retrying. |

See the [REST API guide](/api-reference/rest-api) for shared credentials, privacy, and response-handling rules.

## Playground resources

The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.


## OpenAPI

````yaml api-reference/provider-api.openapi.yaml POST /utilities/qr/generate
openapi: 3.0.3
info:
  title: AvraAPI Provider API
  version: 1.0.0
  description: >-
    The reviewed public contract for AvraAPI provider services. Operations are
    added to this document only after their route, validation, response,
    privacy, usage, and public-safety contracts have been verified.
servers:
  - url: https://avraapi.com/api/v1
    description: AvraAPI REST API v1
security:
  - ApiKeyHeader: []
    ApiSecretHeader: []
tags:
  - name: Currency
    description: Currency codes, exchange rates, and conversion.
  - name: SMS
    description: Messaging operations through configured AvraAPI providers.
  - name: Security
    description: IP and email security checks.
  - name: Location
    description: IP geolocation and intelligence.
  - name: Utilities
    description: QR code, barcode, and PDF generation.
paths:
  /utilities/qr/generate:
    post:
      tags:
        - Utilities
      summary: Generate a QR code
      description: >-
        Generates a PNG or SVG QR code, or returns a Base64 PNG data URI in a
        JSON envelope. A logo can be placed in the centre for PNG and Base64
        output. This is a live artifact-generation operation and may consume
        credits for the active project integration.
      operationId: generateQrCode
      parameters:
        - $ref: '#/components/parameters/XEnvironmentHeader'
        - $ref: '#/components/parameters/AcceptJsonHeader'
        - $ref: '#/components/parameters/XPrivacyModeHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QrGenerateRequest'
            examples:
              png:
                summary: PNG QR code
                value:
                  data: https://example.com/receipt/ORDER-2026-001
                  format: png
                  size: 400
              base64:
                summary: JSON Base64 response
                value:
                  data: https://example.com/receipt/ORDER-2026-001
                  format: base64
      responses:
        '200':
          description: QR output in the requested format.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                $ref: '#/components/schemas/QrBase64Response'
              examples:
                base64:
                  summary: Base64 PNG data URI
                  value:
                    success: true
                    request_id: 01f00000-0000-4000-8000-000000000021
                    data:
                      format: base64
                      data_uri: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
        '400':
          $ref: '#/components/responses/UtilitiesBadRequest'
        '401':
          $ref: '#/components/responses/UtilitiesUnauthorized'
        '402':
          $ref: '#/components/responses/UtilitiesInsufficientFunds'
        '422':
          $ref: '#/components/responses/UtilitiesUnprocessable'
        '429':
          $ref: '#/components/responses/UtilitiesRateLimited'
        '500':
          $ref: '#/components/responses/UtilitiesInternalError'
        '503':
          $ref: '#/components/responses/UtilitiesUnavailable'
components:
  parameters:
    XEnvironmentHeader:
      name: X-ENV
      in: header
      required: false
      description: >-
        Selects the Development credential environment. The Documentation
        Playground exposes Development values only; normal backend integrations
        may use their documented Production credentials outside this tool.
      schema:
        type: string
        enum:
          - dev
          - development
        default: development
    AcceptJsonHeader:
      name: Accept
      in: header
      required: false
      description: Requests a JSON response where the selected operation supports JSON.
      schema:
        type: string
        example: application/json
    XPrivacyModeHeader:
      name: X-Privacy-Mode
      in: header
      required: false
      description: >-
        Optional privacy override. Turn this on to request that AvraAPI suppress
        request-payload storage in observability logs for this request.
      schema:
        type: boolean
        default: false
        example: true
  schemas:
    QrGenerateRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: string
          minLength: 1
          maxLength: 4096
          description: Text, URL, vCard, or other data to encode.
          x-default: https://example.com/receipt/ORDER-2026-001
        format:
          type: string
          enum:
            - png
            - svg
            - base64
          default: png
          x-default: png
        size:
          type: integer
          minimum: 50
          maximum: 2000
          default: 300
          x-default: 300
          description: Output size in pixels.
        margin:
          type: integer
          minimum: 0
          maximum: 20
          default: 2
          x-default: 2
          description: Quiet-zone margin in modules.
        foreground_color:
          type: string
          pattern: ^#?[0-9a-fA-F]{6}$
          default: '000000'
          x-default: '000000'
        background_color:
          type: string
          pattern: ^#?[0-9a-fA-F]{6}$
          default: ffffff
          x-default: ffffff
        logo_url:
          type: string
          format: uri
          maxLength: 2048
          nullable: true
          description: >-
            A publicly accessible HTTP or HTTPS image. Used for PNG and Base64
            output only.
        logo_size_percent:
          type: integer
          minimum: 5
          maximum: 40
          default: 20
          description: Width of the centred logo as a percentage of the QR width.
        privacy_mode:
          type: boolean
          description: >-
            Optional request-level privacy setting. X-Privacy-Mode is the
            universal header override.
    QrBase64Response:
      allOf:
        - $ref: '#/components/schemas/ApiSuccessEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/QrBase64Data'
    ApiSuccessEnvelope:
      type: object
      required:
        - success
        - request_id
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        request_id:
          type: string
          format: uuid
          description: Include this value when contacting AvraAPI support.
        data:
          description: Operation-specific result data.
          nullable: true
    QrBase64Data:
      type: object
      required:
        - format
        - data_uri
      properties:
        format:
          type: string
          enum:
            - base64
        data_uri:
          type: string
          description: PNG data URI beginning with data:image/png;base64,.
    ApiErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable error summary.
            details:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
              description: Field-level validation messages when available.
        meta:
          type: object
          description: Some infrastructure errors include additional diagnostic metadata.
          additionalProperties: true
  headers:
    RequestIdHeader:
      description: AvraAPI request identifier for support and troubleshooting.
      schema:
        type: string
        format: uuid
    RetryAfterHeader:
      description: Seconds to wait before retrying a rate-limited request.
      schema:
        type: integer
        minimum: 0
  responses:
    UtilitiesBadRequest:
      description: >-
        The generator could not process an otherwise valid request, such as an
        unsupported barcode payload or an unreachable QR logo URL.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            http_error:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000025
                error:
                  code: http_error
                  message: The generator could not process the supplied input.
                meta: {}
    UtilitiesUnauthorized:
      description: >-
        Missing, invalid, inactive, or environment-mismatched project
        credentials.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            unauthorized:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000026
                error:
                  code: unauthorized
                  message: Project credentials were not accepted.
                meta: {}
    UtilitiesInsufficientFunds:
      description: >-
        The selected Utility integration requires credits that are not
        available.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            insufficient_funds:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000027
                error:
                  code: insufficient_funds
                  message: The selected Utility integration has insufficient credits.
                meta: {}
    UtilitiesUnprocessable:
      description: >-
        The request body is invalid, or the matching Utility integration cannot
        be resolved for the project environment.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            validation_failed:
              summary: Request validation error
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000022
                error:
                  code: validation_failed
                  message: Validation failed.
                  details:
                    data:
                      - The data field is required.
            unavailable_provider:
              summary: Utility provider is not available
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000023
                error:
                  code: provider_selection_failed
                  message: >-
                    No active generator integration is available for this
                    project environment.
    UtilitiesRateLimited:
      description: The configured request limit has been reached.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
        Retry-After:
          $ref: '#/components/headers/RetryAfterHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            rate_limit_exceeded:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000029
                error:
                  code: rate_limit_exceeded
                  message: The request limit has been reached.
                meta: {}
    UtilitiesInternalError:
      description: The Utility operation could not complete unexpectedly.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            internal_error:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000028
                error:
                  code: internal_error
                  message: The Utility operation could not complete.
                meta: {}
    UtilitiesUnavailable:
      description: The project is paused.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            project_paused:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000024
                error:
                  code: project_paused
                  message: This project is currently paused.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your Development project's Client ID. Enter your own value in the
        Documentation Playground.
    ApiSecretHeader:
      type: apiKey
      in: header
      name: X-API-SECRET
      description: >-
        Your Development project's Client Secret. Mintlify does not proxy these
        requests; the browser sends them directly to AvraAPI. Never enter a
        Production secret in the Documentation Playground.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.