BULK API
BULK API Flow
POST endpoint: POST /bulk
Append endpoint: PUT /bulk/{status id}
Status endpoint: GET /bulk/{task id}/status
Result endpoint: GET /bulk/{task id}?offset=0&size=100
The client sends multiple images (max 1,000 per request) in a request and receives 202(Accepted) status code and TASK ID from the server.
If the client wants to add additional images to the TASK ID, they can make a request to the Append endpoint.
The client can make a GET request to the Status endpoint to retrieve the status of the TASKS. Once the "TASK_DONE" value is received, it means tagging results are available through the Result endpoint.
The client makes a GET request to the Result Endpoint to receive the tagging results (max 100 per request).
POST /bulk
Basic Information
The Header information required to make a request to the TAGGER BULK API URI is as follows.
Method
Request URI
Required Header
POST
x-api-key : API key For Authorization
API Key [Required]
Request
[HTTP Request Header]
POST /tagger/v2.12/bulk HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {API Key provided by Omnious}
[HTTP Request Body]
Field Name
Data Type
Description
Required
albumName
string
Album Name where requested images will be stored
Automatically Created if not defined
X
option
array
Options currently supported: "STRICT"
STRICT: The whole request fails if at least one taggingRequest fails on request validation stage.
X
defaultDetection
array
Default value is used if no value is provided to the defaultDetection field.
default: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR"] Available Values: TOP, BOTTOM, WHOLEBODY, SWIMWEAR, SHOES, BAG, HAT, JEWELRY, ACCESSORY
X
description
string
Description of the task
(MAX 1,024 characters)
X
taggingRequest
string
Product ID on the client's database.
O
taggingRequest[].image
object
Object containing the type of image to be requested and description of the given type.
O
taggingRequest[].image.type
string
Type of the requested image. currently only url type is supported
O
taggingRequest[].image.content
string
Information of the image with regards to its type.
url type: URL information of the requested image.
O
taggingRequest[].context
object
Object containing additional information.
O
taggingRequest[].context.id
string
ID of the requested image.
It must be given a unique Id within a task.
O
taggingRequest[].context.detection
Array[string]
value : TOP, BOTTOM, WHOLEBODY, SWIMWEAR, SHOES, BAG, HAT, JEWELRY, ACCESSORY
When not defined: defaultDetection value is applied.
To tag clothing only.
detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR"]
To tag Accessories only
detection :["ACCESSORY"]
Accessories are provided as Beta service until further notice.
To tag Jewelry only
detection: [“JEWELRY”]
Jewelry is provided as Beta service until further notice.
To tag Hats only
detection :["HAT"]
Hats is provided as Beta service until further notice.
To tag Bags only
detection:["BAG"]
To tag Shoes only
detection:["SHOES"]
To tag Skirts and Pants from clothing only
detection: ["BOTTOM"]
To tag all Clothing Types and Shoes
detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR", "SHOES"]
To tag Tops from Clothing and Shoes
detection: ["TOP", "SHOES"]
To tag all supported types (Clothing, Hats, Bags, Shoes)
detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR", "SHOES", "HAT", "BAG", "JEWELRY", "ACCESSORY"
X
taggingRequest[].context.gender
string
Gender information of the product
ex) male, female, unisex
X
taggingRequest[].context.brand
string
Brand name of product
X
taggingRequest[].context.currency
string
Currency (KRW)
EX) KRW or USD
X
taggingRequest[].context.price
string
Product price
X
taggingRequest[].context.age
Array[string]
The target age group of the product
Example) 10s, early20s, mid-late20s, early30s, mid-late30s, 40s, over50s
X
taggingRequest[].context.keywords
string
Product keywords
Example) summer onepiece
X
taggingRequest[].context.productContentName
string
Product name of the requested image
X
taggingRequest[].context.season
string
Season information about the product
Example) 19SS, 19FW, 20SS, 20FW
X
Example Request
Response
Field ID
Data Type
Description
taskId
string
Created Task ID
albumName
string
Album name where requested images will be stored.
taskExpiredAt
string
Task expiry time.
You cannot request additional PUT requests after the task has expired.
validation
object
Validation results.
Only the images that have passed validation will be tagged.
ex)
Out of total 10 images, if 2 images failed validation, the result is - accept:8 failure:2
validation.accept
int
The number of requests that passed validation
validation.failure
int
The number of requests that failed validation
failureList
object
array
Failed request information.
Contains data from the request and its respective error message
failureList[].request
object
Failed request information
failureList[].request.image
object
Failed request information (image)
failureList[].request.image.type
string
Failed request information. (Fail type)
failureList[].request.image.content
string
Description of the failed image.
base64 type: string of the requested image encoded in base64
failureList[].request.context
object
Additional information of the failed request
failureList[].request.context.id
string
Image Id of the image from the failed request
failureList[].request.context.detection
array
Detection information of the image from the failed request
failureList[].request.context.gender
string
Gender information of the image from the failed request
failureList[].request.context.brand
string
Brand information of the image from the failed request
failureList[].request.context.currency
string
Currency of the image from the failed request
failureList[].request.context.price
string
Price of the image from the failed request
failureList[].request.context.age
Array[string]
Target age group information of the image from the failed request
failureList[].request.context.keywords
string
Keyword information of the image from the failed request
failureList[].request.context.productContentName
string
Product name of the image from the failed request
failureList[].request.context.season
string
Season information of the image from the failed request
failureList[].errorMessage
string
Error message of the image from the failed request
Example Response
PUT /bulk/{task id}
Basic Information
Add additional tagging requests to a given TASK.
No more requests can be added after the expiry time (taskExpireAt).
The expiry time is a minimum 10 minutes after the TASK created time. 10 minutes is extended after every successful PUT request.
This API is the same as POST /bulk API, but `description` and `albumName` options will remain the same in the result even if a new value was provided.
Header information required for TAGGER BULK PUT API is as follows
Method
Request URI
Required Header
PUT
x-api-key : API Key for authentication [Required]
task id: TASK ID generated from the initial POST API request
[Required]
Request
[HTTP Request Header]
PUT /tagger/v2.12/bulk/{task id} HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {API Key retrieved from Omnious} task id: TASK ID generated from the initial POST API request.
[HTTP Request Body]
Same as POST /bulk API
Response
Same as POST /bulk API
GET /bulk
Basic Information
Header information required for TAGGER BULK GET API request is as follows.
Method
Request URI
Required Header
Request
[HTTP Request Header]
GET /tagger/v2.12/bulk HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {API Key provided by Omnious}
Response
Field Name
Data Type
Description
data
object
Object containing task information
data.tasks
array
Array containing task information
data.tasks[].taskId
string
Task identifier
data.tasks[].count
int
Object containing various count information for the requests in a task
data.tasks[].count.total
int
Number of requests in a task
data.tasks[].count.done
int
Number of successful requests in a task
data.tasks[].count.processing
int
Number of requests being processed in a task
data.tasks[].count.failure
int
Number of failed requests in a task
data.tasks[].description
string
Task description
(Information provided on request)
data.tasks[].taskStatus
string
Current status of task
value: TASK_PROCESSING, TASK_DONE
data.tasks[].taskExpireAt
string
After task expires, futher PUT request is not possible
data.tasks[].resultExpiredAt
string
Task result expiry time. After expiry, task results will no longer be available
data.tasks[].createDate
string
Task created time
error
string
Error information of the request
status
string
Sucess/fail status of the request
Example Response
�
GET /bulk/{task id}/status
Basic Information
Header information required for TAGGER BULK TASK STATUS GET API request is as follows.
Method
Request URI
Required Header
GET
https://api.omnious.com/tagger/v2.12/bulk/ {task id}/status
x-api-key : API Key for authentication [Required]
task id: TASK ID retrieved from the inital POST request
[Required]
Request
[HTTP Request Header]
GET /tagger/v2.12/bulk/{task id}/status HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {API Key provided by Omnious} task id: TASK ID retrieved from the initial POST request
Response
Field Name
Data Type
Description
data
object
Object containing task information
data.taskId
string
Task identifier
data.count
int
Object containing various count information for the requests in a task
data.count.total
int
Number of requests in a task
data.count.done
int
Number of successful requests in a task
data.count.processing
int
Number of requests being processed in a task
data.count.failure
int
Number of failed requests in a task
data.description
string
Task description
(Information provided on request)
data.taskStatus
string
Current status of task
value: TASK_PROCESSING, TASK_DONE
data.taskExpireAt
string
After task expires, futher PUT request is not possible
data.resultExpiredAt
string
Task result expiry time. After expiry, task results will no longer be available
data.createDate
string
Task created time
error
string
Error information of the request
status
string
Success/fail status of the request
Example Response
GET /bulk/{task id}?offset=0&size=100
Basic Information
Header information required for TAGGER BULK TASK RESULT GET API request is as follows.
Method
Request URI
Required Header
GET
https://api.omnious.com/tagger/v2.12/bulk/ {task id}?offset=0&size=100
x-api-key : API Key for authentication [Required]
task id: TASK ID retrieved from the initial POST request
[Required]
accept-language : Language to receive tagging results
en: English (default)
ko: Korean
zh: Chinese
ja: Japanese
offset: location from where task results will be retrieved from (Results are saved in the order requests were made).
size: how many items to retreive from the offset location.
Request
[HTTP Request Header]
GET /tagger/v2.12/bulk/{task id}?offset=0&size=100 HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {API Key provided by Omnious} accept-language : {Select language} task id: post TASK ID retrieved from the initial POST request.
Response
Results will only be available after all images within a task have been tagged.
Field Name
Data Type
Description
data
object
Object containing task results information
data.taskInfo
object
Object containing basic task information
data.taskInfo.totalCount
int
Total number of images in a task
data.taskInfo.offset
int
Offset information of the result data
data.taskInfo.size
int
Size information of the result data
data.results
array
object
Object containing image tagging information
data.results[].id
string
Image identifier
data.results[].taggingResult
object
Tagging result (Same as SINGLE API results)
Example Response
Last updated
Was this helpful?