Recognition Specification | Deepomatic API v0.7

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

The id field is an integer for private models and a string for public recognition models.

Output object

Parameter

Type

Description

Labels output

Parameter

Type

Description

Label Object

Create a specification

Definition

Creates a new recognition specification.

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

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"

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.

# 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

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

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}

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

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

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.

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

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

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.

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

Code sample

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.

# 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

Input object

Image input

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

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.

{
    "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": []
        }
    }]
}