This document details the functionality of the InstaVid360 Image API which provides two main services:
By supplying an original image and the intended background image, an end-user can replace the original image's background with the supplied background. An additional overlay image can be provided which would allow the final image produced by the InstaVid360 API to contain a logo or a company name.
Base URL: https://image-api.instavid360.com
API Version: v1
The API supports two main workflows:
Image upload
Upload original, background, and optional overlay images. The API responds with unique imagekeys for each upload.
Create Background Replacement task
Using valid imageKeys, create a background replacement request. The API responds with a task key and processes the job asynchronously.
Query task status
Using the task key, query the task status and retrieve results when complete.
Callback (Optional)
Optionally provide a callback URL to receive automatic notifications when the task completes.
Image upload
Upload the original image containing licence plates.
Create LPA task
Create an LPA task with the imagekey. The API detects and anonymises licence plates automatically.
Query task status
Query the task status and retrieve the processed image with anonymised plates.
Callback (Optional)
Optionally provide a callback URL for completion notifications.
Clients must first get an account registered for them before they can use the API.
Registration requires a name and email address. Upon Registration a new API user will be created.
The new user will be setup with the below restrictions:
Monthly Quotas – Separate quotas for each service type:
Each successful task request consumes one credit from the respective quota. Once the quota is reached, no further requests of that type can be made until the quota resets.
Rate Limit – A limit on the number of API requests that a client can send per minute
Once a user has been successfully created for the client, the client can request API token/s.
Each client user can have one or more API tokens generated. These are the unique tokens that clients use to authenticate to the API.
Token Properties:
Each user token must have a unique name
All user tokens share the same monthly quotas
User tokens do not share images or tasks
Tokens can have different scopes (permissions) for accessing specific services
Clients with valid access tokens can make requests to the API with authentication done via the Authorization header. The client user must include their given token as Bearer Token on each request to the API.
Headers:
{
"Authorization": "Bearer {{personal_token}}"
}
Maximum upload size: 2MB
Supported formats: JPEG, PNG
Endpoint:
POST: /api/v1/image/upload/{{image_type}}
| Parameters | Value | Description |
| {{image_type}} | original | The original Image that needs to undergo background replacement |
| background | The image to be used as a background | |
| overlay | An image that can be placed on top of the background replaced image. i.e. Transparent image with logo in the top right corner. |
Example:
POST /api/image/upload/original HTTP/1.1
Host: image-api.instavid360.com
Authorization: Bearer {{personal_token}}
Content-Length: 225
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image"; filename="/path/to/local/file"
Content-Type: image/jpeg
(data)
----WebKitFormBoundary7MA4YWxkTrZu0gW
Body:
| Parameters | Type | Description |
| image | Binary | Location of the binary file "/path/to/file" |
Response:
Example
{
"success": true,
"code": 0,
"locale": "en",
"message": "OK",
"data": {
"imagekey": "KEbHXtkHor"
}
}
| Parameters | Type | Description | |
| success | boolean | alphanumeric | |
| code | numeric | ||
| Locale | String | Current supported value (en) for South African English | |
| Message | String | Message describing response | |
| Data | Array | on success: data["imagekey"] | Key corresponding to the image on the system. This key will be used during the call to background replacement task. |
| on failure: data["messages"] | Reason why upload failed | ||
Rules regarding the selected images:
The chosen images need to have the same resolutions (width x height) or else the task will fail.
Endpoint:
POST: /api/image/task/bg-replace
Example:
POST /api/image/task/bg-replace HTTP/1.1
Host: image-api.instavid360.com
Authorization: Bearer {{personal_token}}
Content-Type: application/json
Content-Length: 275
{
"reference": "IV-Test-Ref-1",
"original": "KEbHXtkHor",
"background": "mbLHoCgHlr",
"overlay": null,
"options": {
"shadow": false
},
"meta": {
"VIN": "VIN123",
"Title": "Front 3/4"
}
}
Body:
| Parameters | Type | Description |
| reference | String(required) | A unique reference for the job. Provided by the end-user for their own internal tracking of jobs. |
| Original | String(required) | The image to be background replaced |
| background | String(required) | The new background that must be applied to the original image |
| Overlay | String(required|nullable) | An optional image that can be overlayed on top of the background replaced image |
| Options | Array(optional) | A set of setting to configure the replacement task. Currently supported option is: [shadow -> true/false] Setting to shadow to true will include shadow in the output |
| Meta | Array(optional) | An optional list of info that the end-user may want to associate with a job. The array will be returned as is in the response for the completed job |
| callback_url | url(optional) | End-user supplied, optional, end-point where the API can send the response for a completed job. |
Response:
Example
{
"success": true,
"code": 0,
"locale": "en",
"message": "OK",
"data": {
"task": "yKwRfVtDmp"
}
}
| Parameters | Type | Description | |
| Success | boolean | True on success. False on Failure | |
| Code | numeric | ||
| Locale | String | Current supported value (en) for South African English | |
| Message | String | Message describing response | |
| Data | Array | on success: data["task"] |
Key corresponding to the task. on the system. This key will be used to track task status. |
Endpoint:
POST: /api/image/task/lpa
Example:
POST /api/image/task/lpa HTTP/1.1
Host: image-api.instavid360.com
Authorization: Bearer {{personal_token}}
Content-Type: application/json
Content-Length: 200
{
"reference": "LPA-Test-Ref-1",
"original": "KEbHXtkHor",
"options": {},
"meta": {
"VIN": "VIN123"
}
}
Body:
| Parameters | Type | Description |
| reference | String(required) | A unique reference for the job. Provided by the end-user for their own internal tracking of jobs. |
| Original | String(required) | The image to have licence plates anonymised |
| Options | Array(optional) | A set of settings to configure the anonymisation task. |
| Meta | Array(optional) | An optional list of info that the end-user may want to associate with a job. The array will be returned as is in the response for the completed job |
| callback_url | url(optional) | End-user supplied, optional, end-point where the API can send the response for a completed job. |
Response:
Example
{
"success": true,
"code": 0,
"locale": "en",
"message": "OK",
"data": {
"task": "xMwRfVtDnp"
}
}
| Parameters | Type | Description | |
| Success | boolean | True on success. False on Failure | |
| Code | numeric | ||
| Locale | String | Current supported value (en) for South African English | |
| Message | String | Message describing response | |
| Data | Array | on success: data["task"] |
Key corresponding to the task. on the system. This key will be used to track task status. |
A task can have one of the following statuses:
New - Task has just been created and no action has been taken
Validated - Task has been validated and is ready to be processed
In process - Background replacement task is currently being processed
LPA process - Licence plate anonymisation task is currently being processed
Completed - Task has been successfully completed and results are available
Error - There was an error performing the task, check messages for details
Endpoint:
POST: /api/image/task/{{task}}
Example:
POST /api/image/task/yKwRfVtDmp HTTP/1.1
Host: image-api.instavid360.com
Authorization: Bearer {{personal_token}}
| Parameters | Type | Description |
| {{task}} | Binary | Unique Key corresponding to a task to be queried |
Response:
Example
{
"success": true,
"code": 0,
"locale": "en",
"message": "OK",
"data": {
"reference": "IV-Test-Ref-1",
"status": "new",
"task": "yKwRfVtDmp",
"task_type": "Background Replace",
"options": {
"shadow": false
},
"meta": {
"VIN": "VIN123",
"Title": "Front 3/4"
},
"callback_url": null,
"result": null
}
}