Updated at March 20, 2024 06:18 AM
Object recognition
This method allows you to find various objects in the photo.
HOST: https://smarty.mail.ru
ENDPOINT: /api/v1/objects/detect
Authorization data is passed in the query string:
Parameter | Type | Meaning |
|---|---|---|
oauth_token | string | OAuth2 access token (required non-empty) |
oauth_provider | string | OAuth2 provider (required non-empty) |
Supported OAuth2 providers:
Provider | oauth_provider value | Getting a token |
|---|---|---|
VK Cloud | mcs | See in article |
Request parameters are passed in JSON format in the request body with name="meta":
Parameter | Type | Meaning |
|---|---|---|
mode | []string | Types of objects to be searched for in the passed images (required non-empty) |
images | []image_meta | Transferred image metadata (required non-empty) |
Possible values for mode:
Parameter | Type |
|---|---|
object | Search objects in the image |
object2 | Search for objects in the image (v2 model version — recognizes objects belonging to more classes) |
scene | Search on scene image |
car_number | Search on the image for car numbers |
multiobject | Search the image for multi-objects — objects and the entire set of boxes of all found objects |
pedestrian | Search for people in the image (more precisely determines the set of boxes of all people in the image) |
mode may contain one or more modes. For example:
"mode":["object"]<-- search for objects only;"mode":["scene"]<-- search for scenes only;"mode":["object","scene"]<-- search for scenes and objects.
image_meta parameters:
Parameter | Type | Meaning |
|---|---|---|
name | string | Filenames to match files in request and response (required non-empty) |
Images are passed in the body of the request, the values of the name field must match those passed in images.
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@objects_detect_ok_people_in_theatre.jpg;type=image/jpeg' \-F 'meta={"mode": ["scene","multiobject","pedestrian"],"images": [{"name": "file"}]}'
Parameter | Type | Meaning |
|---|---|---|
status | int | 200 in case of successful interaction with the Vision servers |
body | response | Response body |
response parameters:
Parameter | Type | Meaning |
|---|---|---|
scene labels | [] object | Array of responses for each scene file (may be missing) |
object labels | [] object | Array of responses for each file with objects (may be missing) |
car_number_labels | [] object | Array of responses for each file with machine numbers (may be missing) |
multiobject labels | [] object | Array of responses for each file with multi-objects (may be missing) |
pedestrian labels | [] object | Array of responses for each file with people (may be missing) |
object parameters:
Parameter | Type | Meaning |
|---|---|---|
status | enum | Execution result |
error | string | Text description of the error (optional) |
name | string | File name to match files in request and response |
labels | [] label | Listobjects (marks) found on the image |
count_by_density | int | The number of people in the frame, calculated using the density map (only for mode="pedestrian") |
status parameters:
Parameter | Meaning |
|---|---|
0 | Successfully |
1 | Permanent error |
2 | Temporary error |
label parameters:
Parameter | Meaning |
|---|---|
eng | Label (name) for the found object in English |
rus | Label (name) of the found object in Russian |
eng_categories | List of categories (each category includes many tags) in English (optional) |
eng_categories | List of categories (each category includes many tags) in Russian (optional) |
sample | Degree of confidence that this object is in the image |
coordinate | Found object coordinates (optional) |
types_prob | An array of license plate type probabilities. currently the following types are supported: "rus" — all types of Russian numbers; "cis" — numbers of the CIS (except individual and military Ukrainian ones); "eu" — one-story plates of Europe (optional, only for car_number mode). |
Request example:
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@persons_set_error_no_face.jpg;type=image/jpeg' \-F 'meta={"mode": ["object","scene"],"images": [{"name": "file"}]}'
Request example (invalid JSON):
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@objects_detect_ok_people_in_theatre.jpg;type=image/jpeg' \-F 'meta={"mode": ["sceneaaaa","multiobjet"],"images": [{"name": "file"}]}'
Request example (invalid image):
curl -X 'POST' \'https://smarty.mail.ru/api/v1/objects/detect?oauth_token=<ваш токен>&oauth_provider=mcs' \-H 'accept: application/json' \-H 'Content-Type: multipart/form-data' \-F 'file=@empty.jpg;type=image/jpeg' \-F 'meta={"mode": ["scene","multiobjeсt"],"images": [{"name": "file"}]}'
Response example:
{"status": 400,"body": "empty image","htmlencoded": false,"last_modified": 0}