The VuMark Generation Web API allows the generation of printable instances from a VuMark template. These instances are delivered as a graphics file that encodes the instance ID provided with the generation request, which may be in one of several data formats.
To create VuMark instances, you will need to have a Vuforia Engine developer account and a license on the Plans & Licenses tab. Once you have created a license, go to the Target Manager, create a VuMark database, and upload your VuMark template as an SVG file; this provides you with a server-access key to authenticate your calls to the VuMark generation service.
See: How To Create a New VuMark Database
If you still need to make a VuMark template, consult the following articles on designing one in Adobe Illustrator.
See:
Authentication
All requests to the VuMark Generation API need to be authenticated using the Vuforia Web Services (VWS) signature scheme described in the Vuforia Web API Authentication.
Instance Generation
Request:
- Method and URL: POST https://vws.vuforia.com/targets/<target-uuid>/instances.
- Authentication header: A VWS Authentication header using the access-key/secret-key associated with a VuMark Database.
- Date header.
- Content-Type header: application/JSON.
- Accept header: Specifies desired output format: One of image/SVG+XML, image/PNG, or application/PDF.
- Body encoded as JSON with the following fields:
Field name |
Type |
Mandatory |
Description |
|
String |
yes |
Instance ID to be encoded in the VuMark bits.
|
Request body example:
123Copy{
"instance_id": "TAR-0003"
}
Response (Success case):
- Content-type header: One of image/SVG+XML, image/PNG, or application/PDF.
- HTTP Status Code: 200 OK.
- Binary body containing the file in SVG, PNG, or PDF format
Response (Error case):
- • Content-type header: application/JSON.
- HTTP Status Code: 4xx or 5xx (see table below).
- Body: JSON object with the following fields:
transaction_id
: unique transaction id.result_code
: Predefined string specifying the error cause (see below).
Error Code |
HTTP Status Code |
Description |
|
Unprocessable Entity (422) |
Specified instance ID has illegal characters for the given VuMark type, or id is too short or too long. |
|
Forbidden (403) |
No more instances can be created using the license that is associated to the VuMark database. |
|
Forbidden (403) |
The request could not be completed because the target is not in the success state. |
|
Unprocessable Entity (422) |
Target Type is invalid (e.g., trying to generate a VuMark of a Cloud Target). |
|
Forbidden (403) |
According to the license state and/or type, this request can not be executed. |
|
Unauthorized (401) |
General authentication problem. |
|
Bad Request (400) |
The accept header does not contain a valid VuMark output format. See the description of the Accept header for the list of valid output formats |
NOTE: The Standard HTTP error codes and an unspecified body can also be returned by the web API.
Response body example (failure):
1234Copy{
"transaction_id": "a8b8c78b856c56a",
"result_code": "LicenseCheckFailed"
}