Generate a QR Code

Use this method to generate a QR Code image from plain text content.
GET generate

Parameters

Request parameters should be present as key-value pairs in URL query, values should be URL encoded. Parameter content is the only required and must always be specified. Other parameters are optional and can be ignored. If an optional parameter is not set it automatically gets the default value.
auth string optional API key to authenticate user. This parameter is optional.
content string required Content to be encoded in QR Code. This parameter is required.
format string optional Target image format: png (default), jpg, bmp, tif, xaml, svg, eps, txt, html, zip
version int optional Defines capacity and overall image size; values 1..40, unspecified or empty value for auto (default value)
size int optional Size of a single QR code module ("pixel") in real pixels; values 1..20, default: 8
padding int optional Border thickness in QR code modules ("pixels"); values 0..20, default: 4
em string optional Encoding mode, defines what kind of characters can encode and affects overall image size; values:
  • byte - can store any data, default value
  • numeric - only numbers are allowed 0-9
  • alphanumeric - numbers 0-9, letters A-Z, subset of punctuation .$%*/:-
ec string optional Error Correction level, defines how much code can be damaged but still recoverable, affects capacity and image size; values: M (default), H, L, Q
foreground color optional QR Code module color as ARGB hex value (#AARRGGBB), default: black or #FF000000
background color optional Background color as ARGB hex value (#AARRGGBB), default: white or #FFFFFFFF
shorten string optional Hyperlink shortening service, e.g. esp.to, can be used only when content value is URL starting with http or https, default: none
attachment bool optional Flag indicating whether to return response as downloadable file, values "true" or "false", default: false
filename string optional Suggested attachment file name, default: none
Notes on colors: jpg and bmp formats do not support transparency, gif supports only full or no transparency, while png and vector formats support full range of alpha transparency levels. Note that URL encoded # equals %23

Response

Successful response should contain image bytes. In case an error occurs the response will contain HTTP status code 400-500 and HTTP header X-Api-Error with descriptive error message.

Examples

Since the generate method works with GET verb the URLs can be tested directly in a web browser.
How to create a QR Code with "Hello World" content in default PNG format?
Request:
GET http://www.esponce.com/api/v3/generate?content=Hello%20World&format=png&auth=API-KEY
Response:
How to create a vector EPS QR Code with "Hello World" content with 4 module padding, module size 10 pixels, and background color #FFD2DADE?
Request:
GET http://www.esponce.com/api/v3/generate?content=Hello%20World&format=eps&size=10&padding=4&background=%23ffd2dade&auth=API-KEY
Response:
How to create a vector SVG QR Code with "Hello World" content using named colors?
Request:
GET http://www.esponce.com/api/v3/generate?content=Hello%20World&format=svg&background=aliceblue&foreground=blue&auth=API-KEY
Response:

Generate a decorated QR Code

Use this method to generate a QR Code image. The method offers QR Code styling and decoration.
POST /api/v3/generate

Query String Parameters

Request parameters should be present as key-value pairs in URL query, values should be URL encoded. Parameter content is the only required and must always be specified. Other parameters are optional and can be ignored. If an optional parameter is not set it automatically gets the default value.
auth string required API key to authenticate user. This parameter is required.

Request body

content string required Content to be encoded in QR Code. This parameter is required.
format string optional Target image format: png (default), jpg, bmp, tif, svg. Note that xaml, eps, txt, html, zip formats are not supported in POST method, thus available only in GET method.
version int optional Defines capacity and overall image size; values 1..40, unspecified or empty value for auto (default value)
width int optional QR Code width in pixels
height int optional QR Code height in pixels
padding int optional Border thickness in QR code modules ("pixels"); values 0..20, default: 4
em string optional Encoding mode, defines what kind of characters can encode and affects overall image size; values:
  • byte - can store any data, default value
  • numeric - only numbers are allowed 0-9
  • alphanumeric - numbers 0-9, letters A-Z, subset of punctuation .$%*/:-
ec string optional Error Correction level, defines how much code can be damaged but still recoverable, affects capacity and image size; values: M (default), H, L, Q
foreground color optional QR Code module color as RGB hex value (#RRGGBB) or gradient (see example), default: black
background color optional Background color as RGB hex value (#RRGGBB) or gradient (see example), default: white
shorten string optional Hyperlink shortening service, e.g. esp.to, can be used only when content value is URL starting with http or https, default: none
flip string optional Flip the QR Code; values: none, horizontal, vertical, both; default: none
modules object optional Module rendering options, see below
modules.type string optional Type of modules: default, rounded, sprite
modules.union bool optional Merge rectangles to a single path tag, vector shape union, default: false
modules.sprite string optional Name of a predefined sprite from the internal assets. Value `modules.type` must be set to `sprite` and overwrites the `sprites` property. Values: `circle, diamond, diamond2, five, four, plus, six, smiley, star, triangle, x`
modules.sprites array optional Array of available sprites to render QR Code modules, sprites are applied only when `type == "sprite"` and are picked randomly
modules.spritesn.name string optional Sprite name
modules.spritesn.type string optional Sprite rendering: fill - render sprite on module, blank - render on blank space, padding - on padding, both - on every blank space (blank + padding)
modules.spritesn.width number required Sprite width in pixels
modules.spritesn.height number required Sprite height in pixels
modules.spritesn.content string required Content of a sprite, can be URL or embedded PNG, JPEG, SVG content (as base64 "data:image...")
markers object optional Position patterns (eyes), see below
markers.topLeft object optional Top left marker
markers.topLeft.pattern string required predefined pattern name: default, eye-1, eye-2... eye-17
markers.topLeft.innerColor color optional Color of inner shape
markers.topLeft.outerColor color optional Color of outer shape
markers.topLeft.opacity number optional Marker opacity, values from 0.0 to 1.0, default: 1.0
markers.topRight object optional Top right marker, properties same as for `topLeft`
markers.bottomLeft object optional Bottom left marker, properties same as for `topLeft`
layers array optional Array of layers
layersn.name string optional Layer name
layersn.content string required Layer content, can be URL or "data:image..." or "icon:" for predefined icons
layersn.x number required Layer X offset in pixels
layersn.y number required Layer Y offset in pixels
layersn.width number required Layer width in pixels
layersn.height number required Layer height in pixels
layersn.opacity number optional Layer opacity, values 0.0 to 1.0, default: 1.0
layersn.color color optional Change color, only for "icon:"
layersn.display string optional Blend mode: overlay, box-hit-test, pixel-hit-test
layersn.tolerance number optional Hit test tolerance, value in pixels, value can be negative, only for `box-hit-test` and `pixel-hit-test` display modes
wrapper object optional A decorative container for the QR Code
wrapper.source string required URL or "data:image..." of the wrapper
wrapper.width number required Wrapper width
wrapper.height number required Wrapper height
wrapper.placeholder object required Placeholder for the QR Code
wrapper.placeholder.x number required X offset in pixels
wrapper.placeholder.y number required Y offset in pixels
wrapper.placeholder.width number required Available width for the QR Code
wrapper.placeholder.height number required Available height for the QR Code
template string optional Stored template name to preload the parameters. Template is created by using web interface.
Notes:
  1. Output formats jpg and bmp do not support transparency, gif supports only 0% or 100% transparency, while png and vector formats support full range of alpha transparency levels.
  2. URL encoded # equals %23

Response body

Successful response should contain image bytes. In case an error occurs the response will contain HTTP status code 400-500 and HTTP header X-Api-Error with descriptive error message.

Examples

How to create a QR Code with "Hello World" content in the PNG format?
Request:
POST https://www.esponce.com/api/v3/generate?auth=API-KEY
{
  "content": "Hello World"
}
Response:
Request:
POST https://www.esponce.com/api/v3/generate?auth=API-KEY
{
  "content": "Hello World",
  "padding": 4,
  "width": 256,
  "height": 256,
  "foreground": "#007700",
  "background": "#ffffff",
  "ec": "M",
  "format": "svg"
}
Response:
Request:
POST https://www.esponce.com/api/v3/generate?auth=API-KEY
{
  "content": "Hello World",
  "padding": 4,
  "width": 512,
  "height": 512,
  "format": "png",
  "modules": {
    "type": "rounded",
    "union": true
  }
}
Response:
Request:
POST https://www.esponce.com/api/v3/generate?auth=API-KEY
{
  "content": "Hello World",
  "padding": 4,
  "width": 512,
  "height": 512,
  "foreground": "#007700",
  "background": "#ffffff",
  "format": "svg",
  "modules": {
    "type": "sprite",
    "sprites": [
      {
        "name": "star",
        "type": "fill",
        "width": 1792,
        "height": 1792,
        "content": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjxzdmcKICAgeG1sbnM6ZGM9Imh0dHA6Ly9wdXJsLm9yZy9kYy9lbGVtZW50cy8xLjEvIgogICB4bWxuczpjYz0iaHR0cDovL2NyZWF0aXZlY29tbW9ucy5vcmcvbnMjIgogICB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiCiAgIHhtbG5zOnN2Zz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciCiAgIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIKICAgeG1sbnM6c29kaXBvZGk9Imh0dHA6Ly9zb2RpcG9kaS5zb3VyY2Vmb3JnZS5uZXQvRFREL3NvZGlwb2RpLTAuZHRkIgogICB4bWxuczppbmtzY2FwZT0iaHR0cDovL3d3dy5pbmtzY2FwZS5vcmcvbmFtZXNwYWNlcy9pbmtzY2FwZSIKICAgdmlld0JveD0iMCAtMjU2IDE3OTIgMTc5MiIKICAgaWQ9InN2ZzIiCiAgIHZlcnNpb249IjEuMSIKICAgaW5rc2NhcGU6dmVyc2lvbj0iMC45MSByMTM3MjUiCiAgIHdpZHRoPSIxNzkyIgogICBoZWlnaHQ9IjE3OTIiCiAgIHNvZGlwb2RpOmRvY25hbWU9InN0YXIuc3ZnIj4KICA8bWV0YWRhdGEKICAgICBpZD0ibWV0YWRhdGExMiI+CiAgICA8cmRmOlJERj4KICAgICAgPGNjOldvcmsKICAgICAgICAgcmRmOmFib3V0PSIiPgogICAgICAgIDxkYzpmb3JtYXQ+aW1hZ2Uvc3ZnK3htbDwvZGM6Zm9ybWF0PgogICAgICAgIDxkYzp0eXBlCiAgICAgICAgICAgcmRmOnJlc291cmNlPSJodHRwOi8vcHVybC5vcmcvZGMvZGNtaXR5cGUvU3RpbGxJbWFnZSIgLz4KICAgICAgPC9jYzpXb3JrPgogICAgPC9yZGY6UkRGPgogIDwvbWV0YWRhdGE+CiAgPGRlZnMKICAgICBpZD0iZGVmczEwIiAvPgogIDxzb2RpcG9kaTpuYW1lZHZpZXcKICAgICBwYWdlY29sb3I9IiNmZmZmZmYiCiAgICAgYm9yZGVyY29sb3I9IiM2NjY2NjYiCiAgICAgYm9yZGVyb3BhY2l0eT0iMSIKICAgICBvYmplY3R0b2xlcmFuY2U9IjEwIgogICAgIGdyaWR0b2xlcmFuY2U9IjEwIgogICAgIGd1aWRldG9sZXJhbmNlPSIxMCIKICAgICBpbmtzY2FwZTpwYWdlb3BhY2l0eT0iMCIKICAgICBpbmtzY2FwZTpwYWdlc2hhZG93PSIyIgogICAgIGlua3NjYXBlOndpbmRvdy13aWR0aD0iMTUzNiIKICAgICBpbmtzY2FwZTp3aW5kb3ctaGVpZ2h0PSI4MDMiCiAgICAgaWQ9Im5hbWVkdmlldzgiCiAgICAgc2hvd2dyaWQ9ImZhbHNlIgogICAgIGlua3NjYXBlOnpvb209IjAuMjYzMzkyODYiCiAgICAgaW5rc2NhcGU6Y3g9IjExNC43Nzk1NCIKICAgICBpbmtzY2FwZTpjeT0iMTA1My43Mzk0IgogICAgIGlua3NjYXBlOndpbmRvdy14PSItOCIKICAgICBpbmtzY2FwZTp3aW5kb3cteT0iLTgiCiAgICAgaW5rc2NhcGU6d2luZG93LW1heGltaXplZD0iMSIKICAgICBpbmtzY2FwZTpjdXJyZW50LWxheWVyPSJzdmcyIiAvPgogIDxyZWN0CiAgICAgc3R5bGU9ImZpbGw6I2ZmZmZmZjtmaWxsLW9wYWNpdHk6MTtzdHJva2U6bm9uZTtzdHJva2Utd2lkdGg6NTtzdHJva2UtbWl0ZXJsaW1pdDo0O3N0cm9rZS1kYXNoYXJyYXk6MTUsIDE1O3N0cm9rZS1kYXNob2Zmc2V0OjAiCiAgICAgaWQ9InJlY3Q0MTM0IgogICAgIHdpZHRoPSIxNzkyIgogICAgIGhlaWdodD0iMTc5MiIKICAgICB4PSIwIgogICAgIHk9Ii0yNTYiIC8+CiAgPGcKICAgICB0cmFuc2Zvcm09Im1hdHJpeCgxLDAsMCwtMSw2MC43NDU3NjMsMTM1My43NjI3KSIKICAgICBpZD0iZzQiPgogICAgPHBhdGgKICAgICAgIGQ9Im0gMTY2NCw4ODkgcSAwLC0yMiAtMjYsLTQ4IGwgLTM2MywtMzU0IDg2LC01MDAgcSAxLC03IDEsLTIwIDAsLTIxIC0xMC41LC0zNS41IFEgMTM0MSwtODMgMTMyMSwtODMgcSAtMTksMCAtNDAsMTIgTCA4MzIsMTY1IDM4MywtNzEgcSAtMjIsLTEyIC00MCwtMTIgLTIxLDAgLTMxLjUsMTQuNSBRIDMwMSwtNTQgMzAxLC0zMyBxIDAsNiAyLDIwIEwgMzg5LDQ4NyAyNSw4NDEgcSAtMjUsMjcgLTI1LDQ4IDAsMzcgNTYsNDYgbCA1MDIsNzMgMjI1LDQ1NSBxIDE5LDQxIDQ5LDQxIDMwLDAgNDksLTQxIGwgMjI1LC00NTUgNTAyLC03MyBxIDU2LC05IDU2LC00NiB6IgogICAgICAgaWQ9InBhdGg2IgogICAgICAgaW5rc2NhcGU6Y29ubmVjdG9yLWN1cnZhdHVyZT0iMCIKICAgICAgIHN0eWxlPSJmaWxsOiMwMDAwMDAiIC8+CiAgPC9nPgo8L3N2Zz4K"
      }
      ...
    ]
  }
}
Response:
Request:
POST https://www.esponce.com/api/v3/generate?auth=API-KEY
{
  "content": "Hello World",
  "padding": 4,
  "width": 256,
  "height": 256,
  "foreground": "#007700",
  "background": "#ffffff",
  "format": "svg",
  "markers": {
    "topLeft": {
      "pattern": "eye-1",
      "innerColor": "#0000dd",
      "outerColor": "#00dd00"
    },
    "topRight": {
      "pattern": "eye-2"
    },
    "bottomLeft": {
      "pattern": "eye-14",
      "innerColor": "#000000",
      "outerColor": "#000000"
    }
  }
}
Response:
Request:
POST https://www.esponce.com/api/v3/generate?auth=API-KEY
{
  "content": "Hello World",
  "padding": 4,
  "width": 256,
  "height": 256,
  "format": "svg",
  "background": "#ffffff",
  "foreground": {
    "gradient": "linear",
    "units": "relative",
    "direction": {
      "start": { x: 0.3, y: 1.0 },
      "stop": { x: 1.0, y: 0.0 }
    },
    "stops": [
      { "offset": 0.3, "color": "#0000ff", "opacity": 1.0 },
      { "offset": 0.7, "color": "#00ffff", "opacity": 0.7 }
    ]
  }
}
Response:
Request:
POST https://www.esponce.com/api/v3/generate?auth=API-KEY
{
  "content": "Hello World",
  "padding": 4,
  "width": 256,
  "height": 256,
  "format": "svg",
  "background": {
    "gradient": "radial",
    "units": "relative",
    "cx": 0.5,
    "cy": 0.5,
    "fx": 0.5,
    "fy": 0.5,
    "radius": 0.5,
    "stops": [
      { "offset": 0.0, "color": "#ffff00", "opacity": 1.0 },
      { "offset": 1.0, "color": "#ff0000", "opacity": 0.7 }
    ]
  },
  "modules": {
    "union": true
  }
}
Response: