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

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

An output of type labels.

Labels output

Parameter
Type
Description

labels

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.

POST https://api.deepomatic.com/v0.7/recognition/specs

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

An output object to describe how input data should be pre-processed.

Code sample

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"

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.

# 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

Code sample

# 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}"

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

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.

# 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}

Arguments

Parameter
Type
Default
Description

spec_id

int

The ID of the recognition specification to get.

Code sample

# 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}"

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.

PATCH https://api.deepomatic.com/v0.7/recognition/specs/{SPEC_ID}

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

Code sample

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

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.

DELETE https://api.deepomatic.com/v0.7/recognition/specs/{SPEC_ID}

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 https://api.deepomatic.com/v0.7/recognition/specs/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-X 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.

# 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

Arguments

Parameter
Type
Default
Description

spec_id

int

The neural network ID

inputs

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

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

null

(optional) A bounding box object to crop the image before performing inference.

Code sample

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}\"}}]}"

Response

On success, this endpoint will return a task ID. See Inference output section for a description of the response format.

{
    "task_id": "123"
}

Last updated