Recognition Specification

Specification object
Definition
A recognition specification describes the output format of your recognition algorithm. You may attach multiple algorithms that perform the same task to the same specification in order to leverage automatic updates of your embedded recognition models.
Parameter
Type
Attributes
Description
id
int (string)
read-only
The ID of the recognition specification. This field is a string for public recognition models.
name
string
​
A short name for your recognition specification.
description
string
​
A longer description of your recognition specification.
update_date
string
read-only
Date time (ISO 8601 format) of the last update of the recognition specification.
metadata
object
​
A JSON field containing any kind of information that you may find interesting to store.
current_version_id
int
nullable, hidden for public models
The ID of the current recognition version object that this specification will execute if you ask it to perform an inference. This is convenient if you want to allow your app to point to a constant API endpoint while keeping the possibility to smoothly update the recognition model behind. This field is hidden for public recognition models
outputs
array(object)
hidden
The specification of the outputs you would like to recognize. It's an array of output objects. As this field tends to be large, it is hidden when you access the list of recognition models.
The id field is an integer for private models and a string for public recognition models.
Output object
Parameter
Type
Description
labels
​object​
An output of type labels.
Labels output
Parameter
Type
Description
labels
array(object)
A list of labels objects that will be recognized by your model.
exclusive
bool
A boolean describing if the declared labels are mutually exclusive or not.
roi
string
ROI stands for "Region Of Interest". Possible values are:
NONE: if your model is performing classification only without object localisation
BBOX: if your model can also output bounding boxes for the multiple objects detected in the image.
Label Object
Parameter
Type
Description
id
int
The numeric ID of your label. Can be anything you want, this ID will be present in the inference response for you to use it.
name
string
The name of the label. It will also be present in the inference response.
Create a specification
Definition
Creates a new recognition specification.
cURL
Python
POST https://api.deepomatic.com/v0.7/recognition/specs
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
client.RecognitionSpec.create(...)
Arguments
Parameter
Type
Default
Description
name
string
​
A short name for your recognition model.
description
string
""
A longer description of your recognition model.
metadata
object
{}
A JSON field containing any kind of information that you may find interesting to store.
outputs
​object​
​
An output object to describe how input data should be pre-processed.
Code sample
cURL
Python
curl https://api.deepomatic.com/v0.7/recognition/specs \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-d '{
"name": "My recognition model",
"description": "To recognize various types of birds",
"metadata": {"author": "me", "project": "Birds 101"},
"outputs": [{"labels": {"roi": "NONE", "exclusive": true, "labels": [{"id": 0, "name": "hot-dog"}, {"id": 1, "name": "not hot-dog"}]}}]
}' \
-H "Content-Type: application/json"
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
client.RecognitionSpec.create(
    name="hot-dog VS not hot-dog classifier",
    description="My great hot-dog VS not hot-dog classifier !",
    metadata={
        "author": "me",
        "project": "my secret project"
    },
    outputs = [{
        "labels": {
            "roi": "NONE",
            "exclusive": True,
            "labels": [{
                "id": 0,
                "name": "hot-dog"
            }, {
                "id": 1,
                "name": "not hot-dog"
            }]
        }
    }]
)
Response
A recognition specification object.
JSON
{
    "id": 42,
    "name": "hot-dog VS not hot-dog classifier",
    "description": "My great hot-dog VS not hot-dog classifier !",
    "task_id": 123,
    "update_date": "2018-02-16T16:37:25.148189Z",
    "metadata": {
        "author": "me",
        "project": "my secret project"
    },
    "outputs": [{
        "labels": {
            "roi": "NONE",
            "exclusive": true,
            "labels": [{
                "id": 0,
                "name": "hot-dog"
            }, {
                "id": 1,
                "name": "not hot-dog"
            }]
        }
    }],
    "current_version_id": null
}
List specifications
Definition
Get the list of existing recognition specifications.
cURL
Python
# To list public specifications, use:
GET https://api.deepomatic.com/v0.7/recognition/public
​
# To list your own specifications, use:
GET https://api.deepomatic.com/v0.7/recognition/specs
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# To list public specifications, use:
client.RecognitionSpec.list(public=True)
​
# To list your own specifications, use:
client.RecognitionSpec.list()
Code sample
cURL
Python
# For public specifications:
curl  https://api.deepomatic.com/v0.7/recognition/public \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
​
# For private networks:
curl https://api.deepomatic.com/v0.7/recognition/specs \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
import os, deepomatic
client = deepomatic.Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# For public specifications:
for spec in client.RecognitionSpec.list(public=True):
    print(spec)
​
# For private specifications:
for spec in client.RecognitionSpec.list():
    print(spec)
Response
A paginated list of responses.
Parameter
Type
Description
count
int
The total number of results.
next
string
The URL to the next page.
previous
string
The URL to the previous page.
results
array(object)
A list of your recognition specification objects. Please note that the outputfield is not present and that current_version_id is unavailable for public recognition models.
JSON
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 42,
            "name": "My great hot-dog VS not hot-dog classifier !",
            "description": "Very complicated classifier",
            "update_date": "2018-03-09T18:30:43.404610Z",
            "current_version_id": 1,
            "metadata": {}
        },
        ...
    ]
}
Retrieve a specification
Definition
Retrieve a recognition specification by ID.
cURL
Python
# To retrieve a public specification, use:
GET https://api.deepomatic.com/v0.7/recognition/public/{SPEC_ID}
​
# To retrieve your own specification, use:
GET https://api.deepomatic.com/v0.7/recognition/specs/{SPEC_ID}
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# {SPEC_ID} may be a string for a public specification
# or an integer for your own specification.
client.RecognitionSpec.retrieve({SPEC_ID})
Arguments
Parameter
Type
Default
Description
spec_id
int
​
The ID of the recognition specification to get.
Code sample
cURL
Python
# For a public specification:
curl https://api.deepomatic.com/v0.7/recognition/public/fashion-v4 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
​
# For a private specification:
curl https://api.deepomatic.com/v0.7/recognition/specs/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
import os, deepomatic
client = deepomatic.Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# For a public specification:
client.RecognitionSpec.retrieve("fashion-v4")
​
# For a private specification:
client.RecognitionSpec.retrieve(42)
Response
A recognition specification object.
JSON
{
    "id": "fashion-v4",
    "name": "Fashion detector",
    "description": "",
    "update_date": "2018-03-08T19:24:26.528815Z",
    "metadata": {},
    "outputs": [
        {
            "labels": {
                "roi": "BBOX",
                "exclusive": true,
                "labels": [
                    {
                        "id": 0,
                        "name": "sweater"
                    },
                    {
                        "id": 1,
                        "name": "hat"
                    },
                    ...
                    {
                        "id": 14,
                        "name": "swimwear"
                    }
                ]
            }
        }
    ]
}
Edit a specification
Definition
Updates the specified specification by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
This request accepts only the name, metadata and current_version_id arguments. Other values are immutable.
cURL
Python
PATCH https://api.deepomatic.com/v0.7/recognition/specs/{SPEC_ID}
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
spec = client.RecognitionSpec.retrieve({SPEC_ID})
spec.update(...)
Arguments
Parameter
Type
Attributes
Description
name
string
optional
A short name for your network.
description
string
optional
A longer description of your network.
metadata
object
optional
A JSON field containing any kind of information that you may find interesting to store.
current_version_id
int
optional
The ID of the current recognition version object that this specification will execute if you ask it to perform an inference. This is convenient if you want to allow your app to point to a constant API endpoint while keeping the possibility to smoothly update the recognition model behind.
Code sample
cURL
Python
curl https://api.deepomatic.com/v0.7/recognition/specs/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-d name='new name' \
-d current_version_id=123 \
-X PATCH
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
spec = client.RecognitionSpec.retrieve(42)
spec.update(
    name="new name",
    current_version_id=123
)
Response
A recognition specification object.
Delete a specification
Definition
Permanently deletes a recognition specification. It cannot be undone. Attached resources like recognition versions will also be suppressed.
cURL
Python
DELETE https://api.deepomatic.com/v0.7/recognition/specs/{SPEC_ID}
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
spec = client.RecognitionSpec.retrieve({SPEC_ID})
spec.delete()
This cannot be undone. Attached resources like recognition versions will also be suppressed.
Arguments
Parameter
Type
Default
Description
spec_id
int
​
The ID of the specification to delete.
Code sample
cURL
Python
curl https://api.deepomatic.com/v0.7/recognition/specs/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-X DELETE
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
spec = client.RecognitionSpec.retrieve(42)
spec.delete()
Response
Return 204 (no content).
Specification Inference
Definition
Run inference on the current version of the specification. Therefore, its current_version_id field must not be null. This endpoint returns a task ID.
cURL
Python
# To run inference on a public specification, use:
POST https://api.deepomatic.com/v0.7/recognition/public/{SPEC_ID}/inference
​
# To run inference on your own specification, use:
POST https://api.deepomatic.com/v0.7/recognition/specs/{SPEC_ID}/inference
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# {SPEC_ID} may be a string for a public specification
# or an integer for your own specification.
spec = client.RecognitionSpec.retrieve({SPEC_ID})
spec.inference(...)
Arguments
Parameter
Type
Default
Description
spec_id
int
​
The neural network ID
inputs
array(object)
​
The inputs of the neural network as an array of input objects. Must be non empty.
show_discarded
bool
false
A boolean indicating if the response must include labels which did not pass the recognition threshold.
max_predictions
int
100
The maximum number of predicted and discarded objects to return.
Input object
Parameter
Type
Description
image
​object​
An image input. It is the only supported type for now.
Image input
Parameter
Type
Default
Description
source
string
​
Either the URL of the image (in which case it must start with http: or  https: ), or directly the binary content of the image (in which case it must start with data:image/jpeg;encoding, with encoding being either binaryor base64. jpeg might be replaced by another image type).
bbox
​object​
null
(optional) A bounding box object to crop the image before performing inference.
Code sample
cURL
Python
URL=https://static.deepomatic.com/resources/demos/api-clients/dog2.jpg
# Inference from an URL:
curl https://api.deepomatic.com/v0.7/recognition/public/fashion-v4/inference \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-d "{\"inputs\":[{\"image\": {\"source\": \"${URL}\"}}]}" \
-d show_discarded="True" \
-H "Content-Type: application/json" \
-d max_predictions=100
​
# You can also directly send an image file or binary content using multipart/form-data:
curl ${URL} > /tmp/img.jpg
curl https://api.deepomatic.com/v0.7/recognition/public/fashion-v4/inference \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-F inputs[0]image.source=@/tmp/img.jpg
​
# You can also send base64 data by prefixing it with 'data:image/*;base64,' and sending it as application/json:
BASE64_DATA=$(cat /tmp/img.jpg | base64)
curl https://api.deepomatic.com/v0.7/recognition/public/fashion-v4/inference \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"inputs\":[{\"image\": {\"source\": \"data:image/*;base64,${BASE64_DATA}\"}}]}"
import base64
import sys, tarfile
if sys.version_info >= (3, 0):
    from urllib.request import urlretrieve
else:
    from urllib import urlretrieve
​
import os
from deepomatic.api.client import Client
from deepomatic.api.inputs import ImageInput
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
spec = client.RecognitionSpec.retrieve("fashion-v4")
​
# Inference from an URL:
url = "https://static.deepomatic.com/resources/demos/api-clients/dog2.jpg"
spec.inference(inputs=[ImageInput(url)], show_discarded=True, max_predictions=100)
​
# You can also directly send an image file:
urlretrieve(url, '/tmp/img.jpg')
with open('/tmp/img.jpg', 'rb') as fp:
    spec.inference(inputs=[ImageInput(fp)])
​
# You can also send binary data:
with open('/tmp/img.jpg', 'rb') as fp:
    binary_data = fp.read()
​
spec.inference(inputs=[ImageInput(binary_data, encoding="binary")])
​
# If you finally want to send base64 data, you can use:
base64_data = base64.b64encode(binary_data)
spec.inference(inputs=[ImageInput(base64_data, encoding="base64")])
Response
On success, this endpoint will return a task ID. See Inference output section for a description of the response format.
JSON Response
JSON Task Data
{
    "task_id": "123"
}
{
    "outputs": [{
        "labels": {
            "predicted": [{
                "label_id": 9,
                "label_name": "sunglasses",
                "score": 0.990304172,
                "threshold": 0.347,
                "roi": {
                    "region_id": 1,
                    "bbox": {
                        "xmin": 0.312604159,
                        "ymin": 0.366485775,
                        "ymax": 0.5318923,
                        "xmax": 0.666821837
                    }
                }
            }],
            "discarded": []
        }
    }]
}
​

Parameter	Type	Attributes	Description
id	int (string)	read-only	The ID of the recognition specification. This field is a string for public recognition models.
name	string		A short name for your recognition specification.
description	string		A longer description of your recognition specification.
update_date	string	read-only	Date time (ISO 8601 format) of the last update of the recognition specification.
metadata	object		A JSON field containing any kind of information that you may find interesting to store.
current_version_id	int	nullable, hidden for public models	The ID of the current recognition version object that this specification will execute if you ask it to perform an inference. This is convenient if you want to allow your app to point to a constant API endpoint while keeping the possibility to smoothly update the recognition model behind. This field is hidden for public recognition models
outputs	array(object)	hidden	The specification of the outputs you would like to recognize. It's an array of output objects. As this field tends to be large, it is hidden when you access the list of recognition models.

Parameter	Type	Description
labels	object	An output of type labels.

Parameter	Type	Description
labels	array(object)	A list of labels objects that will be recognized by your model.
exclusive	bool	A boolean describing if the declared labels are mutually exclusive or not.
roi	string	ROI stands for "Region Of Interest". Possible values are: `NONE`: if your model is performing classification only without object localisation `BBOX`: if your model can also output bounding boxes for the multiple objects detected in the image.

Parameter	Type	Description
id	int	The numeric ID of your label. Can be anything you want, this ID will be present in the inference response for you to use it.
name	string	The name of the label. It will also be present in the inference response.

Parameter	Type	Default	Description
name	string		A short name for your recognition model.
description	string	""	A longer description of your recognition model.
metadata	object	{}	A JSON field containing any kind of information that you may find interesting to store.
outputs	object		An output object to describe how input data should be pre-processed.

Parameter	Type	Description
count	int	The total number of results.
next	string	The URL to the next page.
previous	string	The URL to the previous page.
results	array(object)	A list of your recognition specification objects. Please note that the `output`field is not present and that `current_version_id` is unavailable for public recognition models.

Parameter	Type	Default	Description
spec_id	int		The ID of the recognition specification to get.

Parameter	Type	Attributes	Description
name	string	optional	A short name for your network.
description	string	optional	A longer description of your network.
metadata	object	optional	A JSON field containing any kind of information that you may find interesting to store.
current_version_id	int	optional	The ID of the current recognition version object that this specification will execute if you ask it to perform an inference. This is convenient if you want to allow your app to point to a constant API endpoint while keeping the possibility to smoothly update the recognition model behind.

Parameter	Type	Default	Description
spec_id	int		The ID of the specification to delete.

Parameter	Type	Default	Description
spec_id	int		The neural network ID
inputs	array(object)		The inputs of the neural network as an array of input objects. Must be non empty.
show_discarded	bool	false	A boolean indicating if the response must include labels which did not pass the recognition threshold.
max_predictions	int	100	The maximum number of predicted and discarded objects to return.

Parameter	Type	Description
image	object	An image input. It is the only supported type for now.

Parameter	Type	Default	Description
source	string		Either the URL of the image (in which case it must start with `http:` or `https:` ), or directly the binary content of the image (in which case it must start with `data:image/jpeg;encoding,` with `encoding` being either `binary`or `base64`. `jpeg` might be replaced by another image type).
bbox	object	null	(optional) A bounding box object to crop the image before performing inference.

Neural Networks

Recognition Version

Last modified 8d ago