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}"
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."
}