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

<table><thead><tr><th width="150">Parameter</th><th width="133">Type</th><th width="125">Attributes</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>int (string)</td><td>read-only</td><td>The ID of the recognition specification. <em>This field is a string for public recognition models.</em></td></tr><tr><td>name</td><td>string</td><td></td><td>A short name for your recognition specification.</td></tr><tr><td>description</td><td>string</td><td></td><td>A longer description of your recognition specification.</td></tr><tr><td>update_date</td><td>string</td><td>read-only</td><td>Date time (ISO 8601 format) of the last update of the recognition specification.</td></tr><tr><td>metadata</td><td>object</td><td></td><td>A JSON field containing any kind of information that you may find interesting to store.</td></tr><tr><td>current_version_id</td><td>int</td><td>nullable, hidden for public models</td><td>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. <em>This field is hidden for public recognition models</em></td></tr><tr><td>outputs</td><td>array(<a href="/pages/-LZKqIqdZmQCP9l__ao2#output">object</a>)</td><td>hidden</td><td>The specification of the outputs you would like to recognize. It's an array of output objects. <em>As this field tends to be large, it is hidden when you access the list of recognition models</em>.</td></tr></tbody></table>

{% hint style="warning" %}
The `id` field is an `integer` for private models and a `string` for public recognition models.
{% endhint %}

### Output object

<table><thead><tr><th width="153.33333333333331">Parameter</th><th width="130">Type</th><th>Description</th></tr></thead><tbody><tr><td>labels</td><td><a href="/pages/-LZKqIqdZmQCP9l__ao2#labels-output">object</a></td><td>An output of type labels.</td></tr></tbody></table>

### Labels output

<table><thead><tr><th width="152.33333333333331">Parameter</th><th width="132">Type</th><th>Description</th></tr></thead><tbody><tr><td>labels</td><td>array(<a href="/pages/-LZKqIqdZmQCP9l__ao2#label-object">object</a>)</td><td>A list of labels objects that will be recognized by your model.</td></tr><tr><td>exclusive</td><td>bool</td><td>A boolean describing if the declared labels are mutually exclusive or not.</td></tr><tr><td>roi</td><td>string</td><td><p>ROI stands for "Region Of Interest". Possible values are:</p><ul><li><code>NONE</code>: if your model is performing classification only without object localisation</li><li><code>BBOX</code>: if your model can also output bounding boxes for the multiple objects detected in the image.</li></ul></td></tr></tbody></table>

### Label Object

<table><thead><tr><th width="155.33333333333331">Parameter</th><th width="131">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>int</td><td>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.</td></tr><tr><td>name</td><td>string</td><td>The name of the label. It will also be present in the inference response.</td></tr></tbody></table>

## Create a specification

### Definition

Creates a new recognition specification.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))

client.RecognitionSpec.create(...)
```

{% endtab %}
{% endtabs %}

### Arguments

<table><thead><tr><th width="141">Parameter</th><th width="114">Type</th><th width="109" align="center">Default</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td align="center"></td><td>A short name for your recognition model.</td></tr><tr><td>description</td><td>string</td><td align="center">""</td><td>A longer description of your recognition model.</td></tr><tr><td>metadata</td><td>object</td><td align="center">{}</td><td>A JSON field containing any kind of information that you may find interesting to store.</td></tr><tr><td>outputs</td><td><a href="/pages/-LZKqIqdZmQCP9l__ao2#output">object</a></td><td align="center"></td><td>An output object to describe how input data should be pre-processed.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
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"
```

{% endtab %}

{% tab title="Python" %}

```python
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"
            }]
        }
    }]
)
```

{% endtab %}
{% endtabs %}

### Response

A [recognition specification object](/deepomatic-api-v0.7/recognition-specification.md#specification-object).

{% code title="JSON" %}

```javascript
{
    "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
}
```

{% endcode %}

## List specifications

### Definition

Get the list of existing recognition specifications.

{% tabs %}
{% tab title="cURL" %}

```bash
# 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
```

{% endtab %}

{% tab title="Python" %}

```python
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()
```

{% endtab %}
{% endtabs %}

### Code sample

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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)
```

{% endtab %}
{% endtabs %}

### Response

A paginated list of responses.

<table><thead><tr><th width="135.33333333333331">Parameter</th><th width="142">Type</th><th>Description</th></tr></thead><tbody><tr><td>count</td><td>int</td><td>The total number of results.</td></tr><tr><td>next</td><td>string</td><td>The URL to the next page.</td></tr><tr><td>previous</td><td>string</td><td>The URL to the previous page.</td></tr><tr><td>results</td><td>array(<a href="/pages/-LZKqIqdZmQCP9l__ao2#specification-object">object</a>)</td><td>A list of your recognition specification objects. Please note that the <code>output</code>field is not present and that <code>current_version_id</code> is unavailable for public recognition models.</td></tr></tbody></table>

{% code title="JSON" %}

```javascript
{
    "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": {}
        },
        ...
    ]
}
```

{% endcode %}

## Retrieve a specification

### Definition

Retrieve a recognition specification by ID.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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})
```

{% endtab %}
{% endtabs %}

### Arguments

<table><thead><tr><th width="133">Parameter</th><th width="102">Type</th><th width="117" align="center">Default</th><th>Description</th></tr></thead><tbody><tr><td>spec_id</td><td>int</td><td align="center"></td><td>The ID of the recognition specification to get.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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)
```

{% endtab %}
{% endtabs %}

### Response

A [recognition specification object](/deepomatic-api-v0.7/recognition-specification.md#specification-object).

{% code title="JSON" %}

```javascript
{
    "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"
                    }
                ]
            }
        }
    ]
}
```

{% endcode %}

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

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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(...)
```

{% endtab %}
{% endtabs %}

### Arguments

<table><thead><tr><th width="187">Parameter</th><th width="84">Type</th><th width="110">Attributes</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>optional</td><td>A short name for your network.</td></tr><tr><td>description</td><td>string</td><td>optional</td><td>A longer description of your network.</td></tr><tr><td>metadata</td><td>object</td><td>optional</td><td>A JSON field containing any kind of information that you may find interesting to store.</td></tr><tr><td>current_version_id</td><td>int</td><td>optional</td><td>The ID of the current <a href="/pages/-LZKqIx_k7DW83QlWSTU#the-version-object">recognition version object</a> 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.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
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
```

{% endtab %}

{% tab title="Python" %}

```python
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
)
```

{% endtab %}
{% endtabs %}

### Response

A [recognition specification object](https://developers.deepomatic.com/docs/v0.7#reco_spec_object).

## Delete a specification

### Definition

Permanently deletes a recognition specification. It cannot be undone. Attached resources like recognition versions will also be suppressed.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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()
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
**This cannot be undone. Attached resources like recognition versions will also be suppressed.**
{% endhint %}

### Arguments

<table><thead><tr><th width="135">Parameter</th><th width="78">Type</th><th width="99" align="center">Default</th><th>Description</th></tr></thead><tbody><tr><td>spec_id</td><td>int</td><td align="center"></td><td>The ID of the specification to delete.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
curl https://api.deepomatic.com/v0.7/recognition/specs/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-X DELETE
```

{% endtab %}

{% tab title="Python" %}

```python
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))

spec = client.RecognitionSpec.retrieve(42)
spec.delete()
```

{% endtab %}
{% endtabs %}

#### Response <a href="#response-5" id="response-5"></a>

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.

{% tabs %}
{% tab title="cURL" %}

```bash
# 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
```

{% endtab %}

{% tab title="Python" %}

```python
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(...)
```

{% endtab %}
{% endtabs %}

### Arguments

<table><thead><tr><th width="175">Parameter</th><th width="131">Type</th><th width="105" align="center">Default</th><th>Description</th></tr></thead><tbody><tr><td>spec_id</td><td>int</td><td align="center"></td><td>The neural network ID</td></tr><tr><td>inputs</td><td>array(<a href="/pages/-LZKqIqdZmQCP9l__ao2#input-object">object</a>)</td><td align="center"></td><td>The inputs of the neural network as an array of input objects. <em>Must be non empty.</em></td></tr><tr><td>show_discarded</td><td>bool</td><td align="center">false</td><td>A boolean indicating if the response must include labels which did not pass the recognition threshold.</td></tr><tr><td>max_predictions</td><td>int</td><td align="center">100</td><td>The maximum number of predicted and discarded objects to return.</td></tr></tbody></table>

### Input object

<table><thead><tr><th width="175.33333333333331">Parameter</th><th width="134">Type</th><th>Description</th></tr></thead><tbody><tr><td>image</td><td><a href="/pages/-LZKqIqdZmQCP9l__ao2#image-input">object</a></td><td>An image input. It is the only supported type for now.</td></tr></tbody></table>

### Image input

<table><thead><tr><th width="128">Parameter</th><th width="97">Type</th><th width="101" align="center">Default</th><th>Description</th></tr></thead><tbody><tr><td>source</td><td>string</td><td align="center"></td><td>Either the URL of the image (in which case it must start with <code>http:</code> or  <code>https:</code> ), or directly the binary content of the image (in which case it must start with <code>data:image/jpeg;encoding,</code> with <code>encoding</code> being either <code>binary</code>or <code>base64</code>. <code>jpeg</code> might be replaced by another image type).</td></tr><tr><td>bbox</td><td><a href="/pages/-LZKqOz8ooW34-aJsZO-#bounding-box-object">object</a></td><td align="center">null</td><td>(optional) A bounding box object to crop the image before performing inference.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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")])
```

{% endtab %}
{% endtabs %}

### Response

On success, this endpoint will return a task ID. See [Inference output](/deepomatic-api-v0.7/inference-output.md) section for a description of the response format.

{% tabs %}
{% tab title="JSON Response" %}

```javascript
{
    "task_id": "123"
}
```

{% endtab %}

{% tab title="JSON Task Data" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.deepomatic.com/deepomatic-api-v0.7/recognition-specification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.