(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.data-privacy-src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-TT9ZP96');

Knowledge Base

Create Image API V2

Table of Contents

Synopsis

This API function creates an image defined in the JSON. The response will return a JPG image file for download. Image details like background image URL, barcode, and text areas may be provided.

  • An image must have some data added in the request.
  • At least one of the following is required for an image: background image, barcode, and/or text area. The request will fail if none are included.
  • The background image URL in the image supports jpg image file type. If the background image is not a jpg or if the image does not exist, then the request will fail. Recommendations for background image are jpg image type, 640x1138px size, and 200 KB file size.
  • If a barcode is added in the image, then the barcode id is required. The request will fail if a barcode is added without a barcode id. The barcode id will appear at the bottom center of the barcode by default and can be hidden by passing the boolean value true to “hide-text”. Both the barcode and the barcode id can be customized based on the details passed in the request. Barcode customizations include barcode type, x/y position, width/height, foreground/background color, border width, transparency, alignment, and rotation. Barcode id customizations include font style/size, and the color of the barcode id is based on the foreground color.
  • A dynamic image supports up to 8 text areas. Each text area requires text to be added. The request will fail if a text area is added without text. Text area customizations include x/y position, font style/size/color, and width.

Request: JSON 

curl -X POST \ 
     -H "x-api-key: API_KEY" \
     -H "content-type: application/json" -d '
      {
          "action": "createimage",
          "background-image-url": "BACKGROUND_IMAGE_URL",
          "add-barcode": "YES/NO",
          "barcode": {
              "id": "BARCODE_TEXT",
              "position-x": "X_COORDINATE_VALUE_IN_PIXELS",
              "position-y": "Y_COORDINATE_VALUE_IN_PIXELS",
              "width": "WIDTH_OF_BARCODE_IN_PIXELS",
              "height": "HEIGHT_OF_BARCODE_IN_PIXELS",
              "foreground-color": "FOREGROUND_COLOR_OF_BARCODE_IN_HEXADECIMAL_VALUE",
              "background-color": "BACKGROUND_COLOR_OF_BARCODE_IN_HEXADECIMAL_VALUE",
              "border-width": "WIDTH_OF_BARCODE_BORDER_IN_PIXELS",
              "type": "BARCODE_TYPE",
              "hide-text": true/false,
              "transparent": true/false,
              "font": "FONT_STYLE",
              "font-size": "FONT_SIZE",
              "alignment": "LEFT/CENTER/RIGHT",
              "rotate": "0/90/180/270"
          },
          "add-text-area": "YES/NO",
          "text-area": {
              "text-area-1": {
                  "text": "TEXT_WITHIN_THE_TEXT_AREA_FIELD",
                  "position-x": "X_COORDINATE_VALUE_IN_PIXELS",
                  "position-y": "Y_COORDINATE_VALUE_IN_PIXELS",
                  "font": "FONT_STYLE",
                  "font-size": "FONT_SIZE",
                  "font-color": "FONT_COLOR_IN_HEXADECIMAL_VALUE",
                  "width": "WIDTH_OF_THE_TEXT_AREA_FIELD"
              }
              ...
          }
      }' \
  "API_ENDPOINT_URL"

Success Response: JSON 

Output the dynamic image file to download (.jpg file)
Content-type: image/jpeg; charset=utf-8;
Content-Disposition: inline; filename=FILENAME;

Failure Response: JSON 

{
    "status": "failure",
    "error-code": "ERROR_CODE",
    "error-info": "ERROR_INFO",
}

Request Parameters

Param NameOptional/Mandatory; DatatypeDescription
x-api-keyMandatory; AlphanumericAuthentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive.
actionMandatory; StringExplains the action for this API Request. Value is Case-Insensitive.
background-image-urlOptional; AlphanumericBackground Image URL for dynamic image.
add-barcodeOptional; StringPass “yes” or “no” to add a barcode to the dynamic image.
barcodeOptionalBarcode node which contains barcode details if “add-barcode=yes”.
barcode:idMandatory; AlphanumericBarcode text.
barcode:position-xOptional; IntegerInteger value expected which will be the starting position of the barcode in pixels along the X (horizontal) coordinate. Default: 0
barcode:position-yOptional; IntegerInteger value expected which will be the starting position of the barcode in pixels along the Y (vertical) coordinate. Default: 0
barcode:widthOptional; IntegerWidth of the barcode in pixels. Default: 300
barcode:heightOptional; IntegerHeight of the barcode in pixels. Default: 300
barcode:foreground-colorOptional; AlphanumericHexadecimal value to set as the color of the foreground of the barcode. Default: #000000
barcode:background-colorOptional; AlphanumericHexadecimal value to set as the color of the background of the barcode. Default: #ffffff
barcode:border-widthOptional; IntegerWidth of the barcode border in pixels. Default: 0
barcode:typeOptional; StringThis is the type of barcode which should be created. Available types:

Aztec Code
Code 11
Code 128
Code 39
Data Matrix
EAN
Interleaved 2of5
PDF417
QR Code
UPC-A

Default: QR Code
barcode:hide-textOptional; BooleanBoolean value passed to hide/show the barcode text. Default: false
barcode:transparentOptional; BooleanBoolean value to enable/disable transparency. Default: false
barcode:fontOptional; StringFont style to be used for barcode text. Available styles:

Arvo
Arial
ArialMT
OpenSans
LiberationSans
Ubuntu

Default: OpenSans
barcode:font-sizeOptional; IntegerFont size to be used for barcode text. Default: 20
barcode:alignmentOptional; StringHorizontal alignment options for barcode. Options are Left, Center and Right. Default: Left
barcode:rotateOptional; IntegerRotation option in degrees. Available options are 0, 90, 180, 270. Default: 0
add-text-areaOptional; StringPass “yes” or “no” to add text areas to the dynamic image.
text-areaOptionalText area node which contains text area details if “add-text-area=yes”.
text-area:text-area-{n}OptionalText area subnode. Max text areas supported: 8
text-area:text-area-{n}:textMandatory; StringText to be displayed for the text area field.
text-area:text-area-{n}:position-xOptional; IntegerInteger value expected which will be the starting position of the text area field in pixels along the X (horizontal) coordinate. Default: 50
text-area:text-area-{n}:position-yOptional; IntegerInteger value expected which will be the starting position of the text area field in pixels along the Y (vertical) coordinate. Default: 400
text-area:text-area-{n}:fontOptional; StringFont style to be used for the text area text. Available styles:

Arvo
Arial
ArialMT
OpenSans
LiberationSans
Ubuntu

Default: OpenSans
text-area:text-area-{n}:font-sizeOptional; IntegerFont size to be used for the text area text. Default: 20
text-area:text-area-{n}:font-colorOptional; AlphanumericHexadecimal color value for the text area font. Default: #000000
text-area:text-area-{n}:widthOptional; IntegerWidth of the text area field in pixels. Default: 200

Response Parameters

Param NamePresenceDescription
statusError Response“failure” 
error-codeError ResponseError code associated with the error.
error-infoError ResponseError message explaining the error code.

Request Example: JSON 

curl -X POST \ 
     -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "content-type: application/json" -d '
      {
          "action": "createimage",
          "background-image-url": "https://fake-content-url.com/background.png",
          "add-barcode": "yes",
          "barcode": {
              "id": "QR Code",
              "position-x": 0,
              "position-y": 0,
              "width": 11,
              "height": 11,
              "foreground-color": "#000000",
              "background-color": "#ffffff",
              "border-width": 0,
              "type": "QR Code",
              "hide-text": false,
              "transparent": false,
              "font": "OpenSans",
              "font-size": 20,
              "alignment": "Left",
              "rotate": 0
          },
          "add-text-area": "yes",
          "text-area": {
              "text-area-1": {
                  "text": "Text to be used in the text area",
                  "position-x": 10,
                  "position-y": 10,
                  "font": "OpenSans",
                  "font-size": 20,
                  "font-color": "#000000",
                  "width": 100
              }
          }
      }' \
  "API_ENDPOINT_URL"

Response Example: Success 

Output the dynamic image file to download (.jpg file)
Content-type: image/jpeg; charset=utf-8;
Content-Disposition: inline; filename=image-template-6053bb7aac39a-2021-03-18T20:43:38Z.jpg;

Response Example: Failure 

{
    "status": "failure",
    "error-code": "E1913",
    "error-info": "Dynamic Image: A background image, barcode, or at least one text area is required."
}
©2024 Skycore LLC. ALL Rights Reserved.
We use cookies for navigation, chat, analytics and forms. Will you accept cookies? Cookie Policy Accept Reject
Go to Top