Create Image API V2

6 min read

Table of Contents

Synopsis
Request: JSON
Success Response: JSON
Failure Response: JSON
Request Parameters
Response Parameters
Request Example: JSON
Response Example: Success
Response Example: Failure

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 Name	Optional/Mandatory; Datatype	Description
x-api-key	Mandatory; Alphanumeric	Authentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive.
action	Mandatory; String	Explains the action for this API Request. Value is Case-Insensitive.
background-image-url	Optional; Alphanumeric	Background Image URL for dynamic image.
add-barcode	Optional; String	Pass “yes” or “no” to add a barcode to the dynamic image.
barcode	Optional	Barcode node which contains barcode details if “add-barcode=yes”.
barcode:id	Mandatory; Alphanumeric	Barcode text.
barcode:position-x	Optional; Integer	Integer value expected which will be the starting position of the barcode in pixels along the X (horizontal) coordinate. Default: 0
barcode:position-y	Optional; Integer	Integer value expected which will be the starting position of the barcode in pixels along the Y (vertical) coordinate. Default: 0
barcode:width	Optional; Integer	Width of the barcode in pixels. Default: 300
barcode:height	Optional; Integer	Height of the barcode in pixels. Default: 300
barcode:foreground-color	Optional; Alphanumeric	Hexadecimal value to set as the color of the foreground of the barcode. Default: #000000
barcode:background-color	Optional; Alphanumeric	Hexadecimal value to set as the color of the background of the barcode. Default: #ffffff
barcode:border-width	Optional; Integer	Width of the barcode border in pixels. Default: 0
barcode:type	Optional; String	This 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-text	Optional; Boolean	Boolean value passed to hide/show the barcode text. Default: false
barcode:transparent	Optional; Boolean	Boolean value to enable/disable transparency. Default: false
barcode:font	Optional; String	Font style to be used for barcode text. Available styles: Arvo Arial ArialMT OpenSans LiberationSans Ubuntu Default: OpenSans
barcode:font-size	Optional; Integer	Font size to be used for barcode text. Default: 20
barcode:alignment	Optional; String	Horizontal alignment options for barcode. Options are Left, Center and Right. Default: Left
barcode:rotate	Optional; Integer	Rotation option in degrees. Available options are 0, 90, 180, 270. Default: 0
add-text-area	Optional; String	Pass “yes” or “no” to add text areas to the dynamic image.
text-area	Optional	Text area node which contains text area details if “add-text-area=yes”.
text-area:text-area-{n}	Optional	Text area subnode. Max text areas supported: 8
text-area:text-area-{n}:text	Mandatory; String	Text to be displayed for the text area field.
text-area:text-area-{n}:position-x	Optional; Integer	Integer 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-y	Optional; Integer	Integer 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}:font	Optional; String	Font 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-size	Optional; Integer	Font size to be used for the text area text. Default: 20
text-area:text-area-{n}:font-color	Optional; Alphanumeric	Hexadecimal color value for the text area font. Default: #000000
text-area:text-area-{n}:width	Optional; Integer	Width of the text area field in pixels. Default: 200

Response Parameters

Param Name	Presence	Description
status	Error Response	“failure”
error-code	Error Response	Error code associated with the error.
error-info	Error Response	Error 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."
}

Updated on February 14, 2024

Knowledge Base

Messaging Platform KB

Content Tools

MMS MM7 API

Messaging API v1

Messaging API v2

Content API V2

Integrations KB