Getting started with the MediaDB API

Sometimes, you only need a service to identify one image from another. Good news, there are entry points for that! And because Images have a meaning only in your context, you can associate metadata and keywords to your images. To access this service, you only need a login and an API Key.

This API allows to search an image

• that is totally or partially identical - ask for a matching signature
• that looks like - ask for a similarity signature
• that are in the same color range - ask for a colors signature

Whatever the signature, it works the same way. Here we will guide you from the creation of your database until the search of an image.

This solution is optimized for High Volumes / High Speed image recognition. Images are indexed in a fast database.

If you want to know more about how our images recognition solution works, please consult our whitepaper or do not hesitate to contact us.

Read Me First

In this documentation are described the media search and management functions and how to call them. The LTU MediaDB API is accessible over the HTTP protocol and is available at this url : https://api.mediadb.ltutech.com/api/services/

The requests have been developed in order to make your task easier. It requires a GET or a POST request and returns an HTTP response with the application/json mimetype, which contains the response serialized as a JSON string.

For all the functions in this documentation, we will assume that the header accepts multipart/form-data or application/json.
application/json is used to send all the parameter in a JSON format as key=value pairs.
multipart/form-data accept binary or ASCII text data. All parameters are sent separately in the body.

Content-Length: xxxxx #size of the message body
Content-Type: multipart/form-data; boundary=--------------------------xxxxxxxxxxxxxxxxxxxxx or application/json

Notice that the values of Content-Length and Content-Type could be set automatically by the librairy that you would use.

A token has to be send in the headers of each request to be authorized (except for getToken of course). How to obtain a token is explained in the next section.

The acepted image formats are jpg, jpeg, png and gif.

If everything goes well, all the functions return a 200 HTTP status code and a JSON result. And in case of error, your will receive an http return error and a message explaning issues in human readable language.

Request AccessTo get access to our services, you will need an account. To request an account to our development team, please fill in that request form.

Contact UsShould you have any feedback or question please feel free to contact us.

What would you like to do today?

Return codes

Here is a list of the main return codes in use in the application.

Success

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource.

201 Created

The request has been fulfilled, resulting in the creation of a new resource.

202 Accepted

The request has been accepted for processing, but the processing has not been finished yet.

204 No Content

The server successfully processed the request and is not returning any content.

207 Multi-Status

The HTTP 207 Multi-Status response code indicates that there might be a mixture of responses.

Client Error

400 Bad Request

The server cannot or will not process the request due to an apparent client error.

401 Unauthorized

When authentication is required and has failed or has not yet been provided.

403 Forbidden

The request was a valid request, but the server is refusing to respond to it.

404 Not Found

The requested resource could not be found but may be available in the future.

409 Conflict

The request could not be completed due to a conflict with the current state of the target resource.

415 Unsupported Media Type client

The server refuses to accept the request because the payload format is in an unsupported format.

Server Error

500 Internal Server Error

This error should not happen, but can be raised when we did not handle properly something on the server side. Sometimes because of a bad request, or a bug. If you encounter this, please contact LTU.

503 Service Unavailable

This error code means that the server is not available right now.

How to get a token

To have access to this service you must be logged. That means you need an account. If you don’t have an account yet, please contact us.
With your login, you could get an token.

Build a POST request of type application/x-www-form-urlencoded.

POST  https://iam.dev.ltutech.com/realms/Production/protocol/openid-connect/token

The function takes as input parameters:

• headers:

  • Content-Type: application/x-www-form-urlencoded

• body:

  • username: your login
  • password: your password
  • client_id: must be ltu-api; the OAuth client ID
  • grant_type: must be password; the type of authorization

A JSON object containing the bearer access token, its duration of validity in second and the refresh token. Your token is valid for 1 day.

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwi.......wKRTus6PAoHMFlIlYQ75dYiLzzuRMvdXkHl6naLNQ8wYDv4gi7A3eJ163YzXSJf5PmQ",
    "expires_in": 600,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cC.......IsInZpZXctcHfX0sInNjb3BlGVtYWlsIHByb2ZpbGUifQ.ePV2aqeDjlg6ih6SA7_x77gT4JYyv7HvK7PLQW-X1mM",
    "token_type": "bearer",
    "id_token": "eyJhbGciOiJSUz.......JSpqeqpMJYlh4AMJqN6kddtrI4ixZLfwAIj-Qwqn9kzGe-v1-oe80wQXrXzVBG7TJbKm4x5bgCO_B9lnDMrey90rvaKKr48K697ug",
    "not-before-policy": 0,
    "session_state": "22c8278b-3346-468e-9533-f41f22ed264f",
    "scope": "openid email profile"
}

curl -X POST https://iam.dev.ltutech.com/realms/Production/protocol/openid-connect/token -H "Content-Type: application/x-www-form-urlencoded" -d "username=$USERNAME" -d "password=$PASSWORD" -d "grant_type=password" -d "client_id=ltu-api"

import requests
url = "https://iam.dev.ltutech.com/realms/Production/protocol/openid-connect/token"

data={
    'username': <your username>,
    'password': <your password>,
    'client_id': 'ltu-api',
    'grant_type': 'password'
}
response = requests.post(url, headers=headers, data=data).json()
token = response["access_token"]

How to refresh your token

Once expired, you can refresh your token from the refresh token. Also, you don't need to log you again. But be carfull, the refresh token has a duration of validation too.

Build a POST request of application/x-www-form-urlencoded type.

POST  https://iam.dev.ltutech.com/realms/Production/protocol/openid-connect/token

This time, the function takes as input parameters:

• headers:

  • Content-Type: application/x-www-form-urlencoded

• body:

  • refresh_token: your refresh token
  • client_id: must be ltu-api; the OAuth client ID
  • grant_type: must be _refresh_token_; the type of authorization

A JSON object containing the bearer access token, its duration of validity in second and the refresh token. Your token is valid for 1 day.

{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6.......wKRTus6PAoHMFlIlYQ75dYiLzzuRMvdXkHl6naLNQ8wYDv4gi7A3eJ163YzXSJf5PmQ", "expires_in": 600, "refresh_expires_in": 1800, "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cC.......IsInZpZXctcHfX0sInNjb3BlGVtYWlsIHByb2ZpbGUifQ.ePV2aqeDjlg6ih6SA7_x77gT4JYyv7HvK7PLQW-X1mM", "token_type": "bearer", "id_token": "eyJhbGciOiJSUz.......JSpqeqpMJYlh4AMJqN6kddtrI4ixZLfwAIj-Qwqn9kzGe-v1-oe80wQXrXzVBG7TJbKm4x5bgCO_B9lnDMrey90rvaKKr48K697ug", "not-before-policy": 0, "session_state": "9c5080b1-42e7-4c4b-a00b-60bf947aa206", "scope": "openid email profile" }

curl -X POST https://iam.dev.ltutech.com/realms/Production/protocol/openid-connect/token -H "Content-Type: application/x-www-form-urlencoded" -d "refresh_token=$REFRESH_TOKEN" -d 'grant_type=refresh_token' -d "client_id=ltu-api" 

import requests
url = "https://iam.dev.ltutech.com/realms/Production/protocol/openid-connect/token"

data={
    'refresh_token': {your refresh token},
    'client_id': 'ltu-api',
    'grant_type': 'refresh_token'
}
response = requests.post(url, headers=headers, data=data).json()
token = response["access_token"]

How to send an image

All the functions found in this documentation work with images. In this section, it is explained how to fill the body of a web request with input image. The different ways of filling them are shown next.

The specifics of how to create a web request depend on the programming language or library you're using. In general, you'll need to specify the HTTP method (usually POST or PUT), the URL of the server endpoint that will receive the request, and any headers or parameters that need to be included in the request. Some headers parameters like the Content-Type or the Content-Length could be automaticaly filled by the librairy.

Once you have created the web request, you need to attach the image to it. There are several ways of doing this, depending on the format in which you send the image and the format that the server accepts. Commons means that our API accepts are described bellow.

By using URLs

This is probably the most simple way. You can just set the string value of the url as a body input parameter named media. media parameter can be sent embed in a JSON in an application/json web request or as an ASCII caracters input in the body of a multipart/form-data web request.
With a multipart request, the other parameters (name, keywords...) must be sent as a key/values JSON format in a paramater named data.

Example with all the parameters embed in a JSON:

curl -X POST https://api.mediadb.ltutech.com/media --header 'api-key: $API-KEY' --header 'Content-Type: application/json' --data '{"media" : "http://data.onprint.com/images/mona-lisa.jpg", "keywords" : ["painting"] "metadata" : {"painter":"Leonardo Da vinci"}}'

Example with formdata parameters:

curl -X POST 'https://api.mediadb.ltutech.com/services/search/media' --header 'api-key: $API-KEY' 
--form 'media="http://data.onprint.com/images/mona-lisa.jpg"' \
--form 'data="{\"keywords\" : [\"painting\"], \"metadata\" : {\"painter\":\"Leonardo Da Vinci\"}}"'

authorization: Bearer <TOKEN>
Accept: */*
Cache-Control: no-cache
Host: api.ltutech.com
Connection: keep-alive
Content-Type: application/json
Content-Length: 63

import requests
import json

headers = {
    'authorization': Bearer <token>
}

data = json.dumps({
  "media": "http://data.onprint.com/images/mona-lisa.jpg",
  "keywords": [
    "paiting"
  ],
  "metadata": {
    "painter": "Leonardo Da vinci"
  }
})

result = requests.post(url, headers=headers, data=data).json()

In this example, data is a JSON that contains all the parameters required by the server.

By sending a binary

You can include the image as a part of the request's body. In this case, you'll need to use a multipart web request, which allows both binary and text data to be sent to the server for processing. The multipart/form-data encoding will generally be used by the library you are using.

authorization: Bearer <TOKEN>
Accept: */*
Cache-Control: no-cache
Host: api.ltutech.com
Connection: keep-alive
Content-Type: multipart/form-data; boundary=--------------------------764488365058661089633609
Content-Length: 20730

The Content-Type header specifies that the request body is in multipart/form-data format, and the boundary parameter indicates the string that separates each part of the data.

curl -X 'https://api.mediadb.ltutech.com/media' --header 'api-key: $API-KEY' --header 'authorization: Bearer $TOKEN' \
--form 'media=@"/Users/Downloads/stomona-lisa.jpg"' \
--form 'data="{\"keywords\" : [\"painting\"], \"metadata\" : {\"painter\":\"Leonardo Da vinci\"}}"'

headers = {
    'authorization': Bearer <token>, #except for search
    'api-key': <your api-key>
}

with open(path_img, 'rb') as media:
    img = media.read()

file = {
    'media': img
}

payload = {
    'data': '{
        "keywords" : ["stone"],
        "painter": "Leonardo Da Vinci",
        "name" : "Mona-Lisa"
        }'
}

result = requests.post(url, headers=headers, files=file, data=payload).json()

In this example, file is a dictionary where the media key corresponds to the parameter name expected by the server to accept the uploaded file. The rest of the parameter are sent in a dictionnary named data.

Create your database

Get your application

To start using LTU's images recongnition API, you need an application. An application is configured for one or several signatures, is identified by two api-key (private and public) and contains the images that you need to retrieve. If you don’t have one yet, please contact us.

We had to give you your api keys, but here's how to get back your appliction's data. For that, create a GET request.

GET https://api.mediadb.ltutech.com/apikey

The function takes as input parameters:

• headers:
  • authorization: Bearer {your token}
• query:
  • owner: (optional) the company's name. If not specified, it returns the API keys of the application owned by the company to which you belong.

A JSON object containing usefull information about your application, such as:

• public_key: the public API key required for search queries
• private_key: the private API key required for all adminstrative actions on your application
• name: the given name to your application
• signatures: the list of signatures available with your application
• medias_type: the type of medias, default value is image
• public: if your application is public, search requests do not required a token
• status: Active or Inactive
• options: options configurated for your application
  • default: default options set at the application creation
    • url: if true, image url is returned instead of buffer

{
  "count": 2
  "results": [
    {
      "id": "0b8ccbadf1e74ef1a1976445f672652b",
      "public_key": "ad5...81",
      "private_key": "c00...dc",
      "status": "Active",
      "owner": "LTU",
      "name": "Color",
      "created_at": "2023-05-25T12:53:14.350073Z",
      "updated_at": "2023-05-25T12:53:23.226797Z",
      "signatures": [
        "8.0.0"
      ],
      "medias_type": "Image",
      "options": {},
      "public": true
    },
    {
      "id": "58f49921788e40b6bb6025410eaa2768",
      "public_key": "87b...24",
      "private_key": "883...04",
      "status": "Active",
      "owner": "LTU",
      "name": "Matching",
      "created_at": "2023-03-09T14:04:20.475173Z",
      "updated_at": "2023-03-09T14:04:25.877501Z",
      "signatures": [
        "72.4.1"
      ],
      "medias_type": "Image",
      "options": {
        "default": {
          "url": true
        }
      },
      "public": true
    }
  ]
}

curl -X GET 'https://api.mediadb.ltutech.com/apikey?owner=LTU' --header 'authorization: Bearer $TOKEN'

import requests

headers = {
    'authorization': 'Bearer <your token>',
}

params = {
    'owner': 'LTU',
}
url = 'https://api.mediadb.ltutech.com/apikey'
response = requests.get(url, params=params, headers=headers).json()

Add a media in the database

If you want to search an image, you need to add it in your database first.

The POST method is used to add a picture by sending the image file and its properties. As explained in the fourth section, 2 ways are possible to send an image.

• by sending all the properties embeded in a JSON. The Content-type in the header should be application/json.
• by sending an image named media and its properties named data using the form parameters. The Content-type in the headers should be multipart/form-data.

Here, we will explain the second method.

POST https://api.mediadb.ltutech.com/media

The function takes as input parameters:

• headers:

  • authorization: Bearer {your token}
  • api-key: your private API key

• body: The content is made of a binary file and its properties

  • data (optional) : a JSON format string that could take the following parameters. All the parameter are optional:
    • "keywords": a list of keywords separated by a comma
    • "metadata": a JSON that contains keys/values data
    • "name": a string that is the name of the image, if it is not specified the id will be given as name
    • "md5": the md5 value of the image
  • media : the binary content of an image or a string that contains an url

A JSON object that indicates the internal id of the image. HTTP status is 201 - Created.

{
  "id": "635aea82-22cc-4ec4-810b-2189b4a1007e"
}

curl -X POST 'https://api.mediadb.ltutech.com/media' -H 'accept: application/json' -H 'api-key: $PRIVATE-KEY' -H 'authorization: Bearer $TOKEN' -H 'Content-Type: multipart/form-data' -F 'media=@"/painting.jpg" -F 'data="{ \"name\" : \"peinture\"}"'

import requests

url = "https://api.mediadb.ltutech.com/media"

headers = {
  'api-key': <your private API key>,
  'authorization': 'Bearer <your token>'
}

data = {'data': '{"keywords" : ["stone"], "metadata" : {"name":"pierre"}}'}

with open(path_img, 'rb') as media:
    img = media.read()

files = {
  'image' = img
}

result = requests.post(url, headers=headers, files=files, data=data).json()

Get your medias

If you want to create a platform to manage your images, you will need to get a complete list of your medias.
For that, create a GET web request.

GET https://api.mediadb.ltutech.com/media?page=10

The function takes as input parameters:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API key
• query:
  • page: page number. The result is paginated. Images are returned one hundred by one hundred. If nothing is specify, the function returns the first hundred images.

A JSON that contains a list of maximun one hundred medias, the most recent first:

• count: the total number of images in the database
• next: the url to call to get the next hundred medias
• previous: the url to call to get the previous hundred medias
• results: a list of up to one hundred media listed in order of most recen
  • id: the uiid of the media
  • name: the name given at the media creation. If any name have been specified, the name is the MD5 value of the ID
  • url: the url of the media. If the application is configurated the get url's medias instead of buffer
  • buffer: the image buffer, if the application has been configurated to receive buffer.
  • thumbnail: the thumbnail's url

{
    "count": 9161,
    "next": "http://api.mediadb.ltutech.com/medias?page=2",
    "previous": null,
    "results": [
        {
            "id": "978b...5c1",
            "created_at": "2023-09-29T13:15:33.341804Z",
            "name": "image_01",
            "media": {
                "url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a323..4b88/978b6..13125c1/files/media",
                "thumbnail_url": "https://torage.dev.ltutech.com/mediadb-bucket/2b9a32...3d5b87a8684b88/978b6...13125c1/files/thumbnail"
            }
        },
        {
            "id": "b9641e6e-1f03-4b9a-948c-0a2e9ba99632",
            "created_at": "2023-09-29T13:11:36.726784Z",
            "name": "image_02",
            "media": {
                "url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a...b88/b964...632/files/media",
                "thumbnail_url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a...b87a8684b88/b96...632/files/thumbnail"
            }
        },

curl -X GET 'http://api.mediadb.ltutech.com/media?page=2' --header 'Authorization: Bearer $TOKEN' --header 'api-key: $PRIVATE-KEY'

import requests

url = "https://api.mediadb.ltutech.com/media?page=3"

headers = {
  'api-key': <your api-key>,
  'authorization': 'Bearer <TOKEN>'
}

result = requests.get(url, headers=headers).json()

Remove a media from the database

Sometimes, you need to remove images from your application. For that you need to know the id or the name of your media. The name is given by you at the media creation, the id is generated by LTU.

Build an application/json DELETE Web request.

DELETE https://api.mediadb.ltutech.com/media/{media's name or id}

The function takes as input:

• headers:
  • authorization: Bearer {token}
  • api-key: your private API KEY
• body: a JSON that contains the following parameter
  • force: (optional) if True the media is deleted definitively, if False the media is deactivated but not deleted. False is the default value.

A JSON answser that contain the id of the media.

{
    "id": "d32800b1-0cd2-4c41-b777-ea08d3b6b389",
}

curl -X DELETE 'https://api.mediadb.ltutech.com/media/d32800b1-0cd2-4c41-b777-ea08d3b6b389' -H 'accept: application/json' -H 'api-key: $PRIVATE-KEY' -H 'authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{"force": true}'

import requests

url = "https://api.mediadb.ltutech.com/media/d32800b1-0cd2-4c41-b777-ea08d3b6b389"

payload = {'data': '{ "force" : "true"}'}
headers = {
  'api-key': '<your private API key>',
  'Authorization': 'Bearer <TOKEN>'
  }

response = requests.delete(url, headers=headers, data=payload).json()

Organize your database

There is two kinds of collections that can help you to organise your medias in your applications:

• a collection, that is a simple list of medias added in this collection
• a smart collection built of media based on criteria such as metadata or/and keywords

Simple collections

Create a collection

To organise your database, you can group your images in a same collection without automatic criteria. The media must be added in the collection.
To add a new collection, Build a POST request of application/json type.

POST https://api.mediadb.ltutech.com/collection

The function collection takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY
• body: parameters are sent under a JSON format that could contain:
  • name: the name of the collection
  • keywords: (optional) a list of keywords associated
  • metadata: (optional) a JSON that contains keys/values data

A JSON object that contains information about the collection such as its id.

{
    "id": "ec1aae8f1e9748e5ac6728394c73b47a",
    "collections": [],
    "created_at": "2023-10-05T16:06:05.624275Z",
    "updated_at": "2023-10-05T16:06:05.624311Z",
    "name": "statue",
    "metadata": {},
    "keywords": [],
    "api_key": "2b9a3...b88",
    "parent": null
}

curl -X POST 'https://api.mediadb.ltutech.com/collection' --header 'Authorization: Bearer $TOKEN' --header 'api-key: $PRIVATE_KEY' --header 'Content-Type: application/json' --data '{"name": "painting"}'

import requests
import json

url = "https://api.mediadb.ltutech.com/collection"

payload = json.dumps({
  "name": "statue"
})

headers = {
  'Authorization': 'Bearer <TOKEN>,
  'api-key': <your private api key>,
  'Content-Type': 'application/json
}

response = requests.request("POST", url, headers=headers, data=payload).json()

Get all your collections

If you want to create a platform to organise your medias, you need to get the list of the collections containing your images.
Build a GET web request.

GET https://api.mediadb.ltutech.com/collection

The function collection takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY
• query:
  • full: (optional) if true returns collections and all sub-collections, if false returns first-level collections only. Set to false if not specified.

A JSon that contains the list of your collections with the following main information:

• name: the name you have given to your collection
• id: the uiid of the collection. It will be usefull to get the list of the medias of your collections
• collections: a list of identifiers for collections of direct children. It could be usefull to recreate the tree structure
• keywords: a list of the keywords of the collection
• metadata: the metadata of the collection
• parent: the parent collection, if any

[ { "id": "5ced6bbd29d940b5bb6366160dbcf50e", "collections": ["4a882d5ddf114088a37ae09423f387c1"], "created_at": "2023-10-05T13:56:51.586829Z", "updated_at": "2023-10-05T13:56:51.586895Z", "name": "statue", "metadata": {}, "keywords": [ "bla" ], "api_key": "2b9a3...84b88", "parent": null }, { "id": "f68c358adab845eb9ec8a66bc626f8b4", "collections": [], "created_at": "2023-09-29T12:56:24.374055Z", "updated_at": "2023-09-29T12:56:26.738990Z", "name": "painting", "metadata": {}, "keywords": [], "api_key": "2b9a3231...a8684b88", "parent": null } ]

curl -X GET 'https://api.mediadb.ltutech.com/collection' -H 'api-key: $PRIVATE_KEY' -H 'authorization: Bearer $TOKEN'

import requests

url = "https://api.mediadb.ltutech.com/collection"

headers = {
  'api-key': <your api-key>,
  'authorization': 'Bearer <token>'
}

result = requests.get(url, headers=headers).json()

Add a media to a collection

Once your database organisation is in place, you can add your media to one or more collections.
For that, build a application/json PATCH web request and send it with a list of images ids.

PATCH https://api.mediadb.ltutech.com/collection/ec1aae8f1e9748e5ac6728394c73b47a/medias

The function takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY
• body: a JSON that contains the following parameter
  • medias: a list of media's ID

A JSON object and a HTTP code.

curl -X PATCH 'https://api.mediadb.ltutech.com/collection/{collection ID}/medias' -H 'accept: application/json' -H 'api-key: $PRIVATE_KEY' -H 'authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{"medias": ["4b654bc9-3376-4ddd-9172-5873138275d8"]'

import requests
import json

url = "https://api.mediadb.ltutech.com/collection/3a557075ba0343808c66f303289645c0/medias"

payload = json.dumps({
  "medias": [
    "9f9c486c-d3f3-4436-b111-d53d61c8c3e2"
  ]
})
headers = {
  'api-key': <your private API key>
  'authorization' : <TOKEN>
  'Content-Type': 'application/json'
}

response = requests.patch(url, headers=headers, data=payload)

Get medias from a simple collection

Sometimes, you just want to get the media of one specific collection.
Buils a GET web request, with the collection ID set in the url.

GET https://api.mediadb.ltutech.com/collection/{collecion id}/medias

The function takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY
• query:
  • order_by: (optional) sorting criteria: created_at, request_at, name, status, thumbnail_url, url, uuid or version
  • page: (optional) the page number to be returned. The result is paginated. Images are returned according to the page number and the size page
  • page_size (optional) the max number of medias returned par page
  • desc: (optional) if True, the parameter is set to descending. Otherwise, it is set to ascending

A JSON answer that could contain the following information:

• count: the total number of images in the collection
• next: the url to call to get the next page of medias
• previous: the url to call to get the previous page of medias
• results: a list of the one medias ordered by the most recent by default
  • id: the id of the media
  • name: the name given at the media creation.
  • url: the url of the media. If the application is configurated the get url's medias instead of buffer
  • thumbnail: the thumbnail's url

{ "count": 1010, "next": "http://api.mediadb.ltutech.com/collection/4a882d5ddf114088a37ae09423f387c1/media_listing?page=3&page_size=10", "previous": "http://api.mediadb.ltutech.com/collection/4a882d5ddf114088a37ae09423f387c1/media_listing?page_size=10", "results": [ { "id": "4b654bc9-3376-4ddd-9172-5873138275d8", "created_at": "2023-10-09T15:16:10.820591Z", "name": "4b654bc9-3376-4ddd-9172-5873138275d8", "media": { "url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/4b654bc9-3376-4ddd-9172-5873138275d8/files/media", "thumbnail_url": "https://demo.storage.dev.ltutech.com/mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/4b654bc9-3376-4ddd-9172-5873138275d8/files/thumbnail" } }, ... ] }

curl -X POST 'https://api.mediadb.ltutech.com/collection/{collection id}/medias?page=4&page_size=100&order_by=created_at&desc=true' -H 'accept: application/json' -H 'api-key: $API-KEY' -H 'authorization: Bearer $TOKEN'

import requests
import json

url = "https://demo.api.mediadb.ltutech.com/collection/3a557075ba0343808c66f303289645c0/medias"

headers = {
  'api-key': '<your private API key>',
  'Authorization': 'Bearer <TOKEN>',
  'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers).json()

Remove a media from a collection

To remove a media from a collection, you have to update the media ID list of a collection.
For that, build a DELETE web request with the collection ID in the url. The Content-type must be application/json.

DELETE https://api.mediadb.ltutech.com/collection/{Collection ID}/medias

The function takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY
• body: a JSON that contains the following parameter
  • medias: a list of media's ID

A JSON object and a HTTP code.

curl -X DELETE 'https://api.mediadb.ltutech.com/collection/{collection ID}/medias' -H 'accept: application/json' -H 'api-key: $PRIVATE_KEY' -H 'authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{"medias": ["4b654bc9-3376-4ddd-9172-5873138275d8"]'

import requests
import json

url = "https://demo.api.mediadb.ltutech.com/collection/3a557075ba0343808c66f303289645c0/medias"

payload = json.dumps({
  "medias": [
    "9f9c486c-d3f3-4436-b111-d53d61c8c3e2"
  ]
})
headers = {
  'api-key': <your private API key>
  'authorization' : <TOKEN>
  'Content-Type': 'application/json'
}

response = requests.delete(url, headers=headers, data=payload)

Remove a collection

To remove a colletion from an application, build a DELETE web request. The collection ID is specified in the url.

DELETE https://api.mediadb.ltutech.com/collection/{collection id}

The function takes as input paramters:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY

A JSON object that contains the ID of the removed collection.

curl -X DELETE 'https://api.mediadb.ltutech.com/collection/{collection ID}' -H 'api-key: $PRIVATE_KEY' -H 'authorization: Bearer $TOKEN' -H 'Content-Type: application/json'

import requests
import json

url = "https://api.mediadb.ltutech.com/collection/3a557075ba0343808c66f303289645c0"

headers = {
  'api-key': <your private API key>
  'authorization' : <TOKEN>
  'Content-Type': 'application/json'
}

response = requests.delete(url, headers=headers)

Smart collections

You can group together images that meet the same criteria, such as the keywords "painting" for example. The media don't have to be added to the collection, the media list will be calculated according to the criteria of the collection. All criteria must be met.

Create a smart collection

To create a smart collection, build a POST application/json web request.

POST https://api.mediadb.ltutech.com/smart_collection

The function takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY
• body: parameters are sent under a JSON format that could contain:
  • name: the name of the collection
  • keywords: (optional) a list of keywords associated. These keywords are not collection criteria.
  • metadata: (optional) a JSON that contains keys/values data. These metadata are not collection criteria.
  • query : a JSON that contains selection criteria: keywords or/and metadata

A JSON object that contains information about the smart collection such as its id.

{
    "id": "7dadf9588be04bacaab355566a4b226c",
    "created_at": "2023-10-06T13:09:33.976500Z",
    "updated_at": "2023-10-06T13:09:33.976526Z",
    "name": "painting",
    "metadata": {},
    "keywords": [],
    "query": {
        "keywords": [
            "painting"
        ],
        "metadata": {
            "artist": "Da Vinci"
        }
    },
    "api_key": "2b9a3...b88"
}

curl -X  POST 'https://api.mediadb.ltutech.com/smart_collection' --header 'Authorization: Bearer $TOKEN' --header 'api-key: $PRIVATE_KEY' --header 'Content-Type: application/json'--data '{ "name": "painting", "query" : {"keywords": ["painting"], "metadata" : {"artist":"Da Vinci"}}}'

import requests
import json

url = "https://api.mediadb.ltutech.com/smart_collection"

payload = json.dumps({
  "name": "painting",
  "query": {
    "keywords": [
      "painting"
    ],
    "metadata": {
      "country": "france"
    }
  }
})

headers = {
  'authorization': 'Bearer <TOKEN>,
  'api-key': '46a02ff1593e46afb4a60be49f09e8b3',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload).json()

Get all your smart collections

If you want to create a platform to organise your medias, you need to get the list of the smart collections containing your images. Build a GET web request.

GET https://api.mediadb.ltutech.com/smart_collection

The function takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY

A JSON object that contains the list of your collections, their name and ids.

[
    {
        "id": "3a2231cfde86444e84119fa218154a4d",
        "created_at": "2023-09-29T13:06:43.612020Z",
        "updated_at": "2023-09-29T13:06:43.612045Z",
        "name": "painting",
        "metadata": {},
        "keywords": [],
        "query": {
            "keywords": [
                "painting"
            ]
        },
        "api_key": "2b9a3...b88"
    },
    {
        "id": "608d6f54afca42e4a8a7194d78328956",
        "created_at": "2023-09-29T08:55:07.276111Z",
        "updated_at": "2023-09-29T08:55:07.276148Z",
        "name": "notre-dame",
        "metadata": {},
        "keywords": [],
        "query": {
            "metadata": {
                "sujet": "notre-dame"
            }
        },
        "api_key": "2b9a3...b88"
    }
]

curl --location 'https://api.mediadb.ltutech.com/smart_collection' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6Qnc4XzlaU0NsVFdxVVptWEwxWi1VVlhLY2RSdnRoWC1yU1ZVV3U5bG9BIn0.

import requests

url = "https://api.mediadb.ltutech.com/smart_collection"

headers = {
  'api-key': <your api-key>,
  'authorization': 'Bearer <token>'
}

result = requests.get(url, headers=headers).json()

Get medias from a smart collection

Sometimes, you just want to get the media of one specific smart collection. Buils a GET web request, with the collection ID set in the url.

GET https://demo.api.mediadb.ltutech.com/smart_collection/{smart collection id}/medias?page=1&order_by=created_at

The function takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY
• query:
  • order_by: (optional) sorting criteria: created_at, request_at, name, status, thumbnail_url, url, uuid or version.
  • page: (optional) the page number to be returned. The result is paginated. Images are returned according to the page number and the size page.
  • page_size (optional) the max number of medias returned per page
  • desc: (optional) if True, the parameter is set to descending. Otherwise, it is set to ascending

A JSON answer that could contain the following information:

• count: the total number of images
• next: the url to call to get the next page of medias
• previous: the url to call to get the previous page of medias
• results: a list of medias ordered by the most recent by default
  • id: the id of the media
  • name: the name given at the media creation. If any name have been specified, the name is the MD5 value of the ID
  • url: the url of the media. If the application is configurated the get url's medias instead of buffer
  • thumbnail: the thumbnail's url

curl -X GET 'https://api.mediadb.ltutech.com/smart_collection/{smart collection id}/medias' -H 'accept: application/json' -H 'api-key: $PRIVATE-KEY' -H 'authorization: Bearer $TOKEN'

import requests

url = "https://api.mediadb.ltutech.com/smart_collection/2319215cef0445c6899db89bdcf8dfd2/medias?page=1&order_by=created_at"

headers = {
  'api-key': '<your private API key>',
  'Authorization': 'Bearer <TOKEN>'
}

response = requests.get() url, headers=headers).json()

Remove a smart collection

To remove a smart colletion from an application, build a DELETE web request, with the collection ID specified in the url.

DELETE https://api.mediadb.ltutech.com/smart_collection/{smart collection id}

The function takes as input:

• headers:
  • authorization: Bearer {your token}
  • api-key: your private API KEY

A JSON object that contains the ID of the removed collection.

curl -X DELETE 'https://api.mediadb.ltutech.com/smart_collection/{smart collection ID}' -H 'api-key: $PRIVATE_KEY' -H 'authorization: Bearer $TOKEN'

import requests
import json

url = "https://api.mediadb.ltutech.com/smart_collection/3a557075ba0343808c66f303289645c0"

headers = {
  'api-key': <your private API key>
   'authorization' : <TOKEN>
  'Content-Type': 'application/json'
}

response = requests.delete(url, headers=headers)

Search for a Picture

From an image

You can search for images in your database by sending a query image with or withour keywords and metadata. If several criteria are specified, the media returned will match all the criteria. Build an multipart/form-data POST web request.

POST https://api.mediadb.ltutech.com/media

The function takes as input:

• headers:

  • api-key: your public API KEY

• body: The content is made of a binary file and its properties.

  • media : the binary content of an image or a string that contains an url
  • data:(optionnal) a JSON format string that could take the following parameters:
    • keywords: a list of keywords separated by a comma

A JSON object that contains a list of matched medias with the mains following information:

• id: the uiid of the image
• url: the url of the media, if your application is configured to return urls
• thumbnail_url: the url of the thumbnail
• name: the image name
• keywords: list of the media keywords
• metadata: metadata of the media
• details: the match details per signature
  • best_signature: the signature that returns the best score
  • decision: String describing the decision, possible values are
    • “Clone” if the query is the same image as the reference
    • “Match”
    • “Rejection due to geometric test”
    • “Rejection due to shape of the matching box”
  • category: “LOCALMATCHING” (constant)
  • reference: information about the reference
    • matchingBox: for the reference, the matching box is always rectangular with no rotation
      • scores: alternative scores
    • boxCoveredSurface: surface within the matching box with matching points (expressed as percentage)
    • boxPointsRatioHomography: ratio of matching points among all points in the query matching box
    • matchStrength: normalized score based on the number of matching points
      • distance: matching score, best matches have a low distance
  • query: information about the query
    • originalDimensions: size of the original image
    • resizedDimensions: size of the processed image after resizing
    • matchingBox
      • points: vertices of the matching box inside the query
      • area: surface of the matching box in percentage (0.2728 → 27.28 %)
  • homography: transformation from the reference to the query
  • score: matching score, best matches have a low distance

{
        "id": "9f9c486c-d3f3-4436-b111-d53d61c8c3e2",
        "media": {
            "url": "https://storage.dev.ltutech.com/demo-mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/9f9c486c-d3f3-4436-b111-d53d61c8c3e2/files/media",
            "thumbnail_url": "https://storage.dev.ltutech.com/demo-mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/9f9c486c-d3f3-4436-b111-d53d61c8c3e2/files/thumbnail"
        },
        "name": "donut",
        "details": {
            "best_index": "72004001",
            "72004001": {
                "message": "succeed",
                "keywords": [],
                "code": 0.0,
                "info": {
                    "decision": "Match",
                    "category": "LOCALMATCHING",
                    "reference": {
                        "resizedDimensions": [
                            512.0,
                            288.0
                        ],
                        "originalDimensions": [
                            640.0,
                            360.0
                        ],
                        "matchingBox": {
                            "points": [
                                [
                                    0.3672,
                                    0.2882
                                ],
                                [
                                    0.6543,
                                    0.2882
                                ],
                                [
                                    0.6543,
                                    0.7153
                                ],
                                [
                                    0.3672,
                                    0.7153
                                ]
                            ],
                            "area": 0.1226
                        }
                    },
                    "scores": {
                        "boxPointsRatio": 1.0,
                        "boxCoveredSurface": 0.2679,
                        "boxPointsRatioHomography": 1.0,
                        "matchStrength": 1.0,
                        "matchStrengthWithoutWeighting": 0.625
                    },
                    "distance": 0.01,
                    "query": {
                        "originalDimensions": [
                            640.0,
                            360.0
                        ],
                        "resizedDimensions": [
                            512.0,
                            288.0
                        ],
                        "matchingBox": {
                            "points": [
                                [
                                    0.3672,
                                    0.2882
                                ],
                                [
                                    0.6543,
                                    0.2882
                                ],
                                [
                                    0.6543,
                                    0.7153
                                ],
                                [
                                    0.3672,
                                    0.7153
                                ]
                            ],
                            "area": 0.1226
                        }
                    },
                    "homography": {
                        "source": "reference",
                        "coefficients": [
                            1.0,
                            -0.0,
                            -0.0,
                            0.0,
                            1.0,
                            -0.0,
                            0.0,
                            -0.0,
                            1.0
                        ],
                        "destination": "query"
                    }
                },
                "score": 0.009999999776482582
            },
            "score": 0.009999999776482582,
            "keywords": []
        }
    }

curl -X 'https://api.mediadb.ltutech.com/services/search/media' --header 'api-key: $PUBLIC-KEY' --form 'media=@"/Users/Downloads/donut.jpg"'

import requests

url = "https://api.mediadb.ltutech.com/services/search/media"

payload = {
  'data' = '{"keywords" : ["painting"]}'
}
files=[
  ('media',('donut.jpg',open('/Users/Downloads/donut.jpg','rb'),'image/jpeg'))
]
headers = {
  'api-key': <your public API key>
}

response = requests.post(url, headers=headers, data=payload, files=files)

From keywords and metadata

You can search by keywords and/or metadata only. If several criteria are specified, the media returned will match all the criteria. Build an application/json POST web request.

POST https://api.mediadb.ltutech.com/media

The function takes as input:

• headers:

  • api-key: your public API KEY

• body: a JSON that could contain the following search criteria

  • keywords: a list of keywords
  • metadata: a key/value criteria

A JSON object that contains a list of matched medias with the following information:

• id: the uiid of the image
• url: the url of the media, if your application is configured to return urls
• thumbnail_url: the url of the thumbnail
• name: the media name
• keywords: list of the media keywords
• metadata: metadata of the media

{ "id": "3d795457-1791-45d6-83fd-a974279c0640", "media": { "url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/3d795457-1791-45d6-83fd-a974279c0640/files/media", "thumbnail_url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/3d795457-1791-45d6-83fd-a974279c0640/files/thumbnail" }, "name": "86291410_132205950d_c", "metadata": { "topic": "architecture" }, "keywords": [ "notre-dame" ] }, .., { "id": "96e8255d-720f-439b-9dea-60448af252fb", "media": { "url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/96e8255d-720f-439b-9dea-60448af252fb/files/media", "thumbnail_url": "https://storage.dev.ltutech.com/mediadb-bucket/2b9a32313333414cad3d5b87a8684b88/96e8255d-720f-439b-9dea-60448af252fb/files/thumbnail" }, "name": "52945251_23a3a7d2bd_c", "metadata": { "sujet": "notre-dame", "topic": "architecture", }, "keywords": [ "notre-dame" ] } }

curl -X POST 'https://demo.api.mediadb.ltutech.com/services/search/media' --header 'api-key: $PUBLIC_KEY' --header 'Content-Type: application/json' --data {"keywords" : ["notre-dame"]}'

import requests
import json

url = "https://api.mediadb.ltutech.com/services/search/media"

payload = json.dumps({
  "keywords": ["notre-dame"]
})
headers = {
  'api-key': '{your public api-key}',
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload).json()

∴

That's it! You went through all our documentation. We hope you liked it. We would love to hear from your feedback, so for anything please contact us! You can now start ahead, and if you need more, don't forget the reference documentation.

We also have a Swagger page, useful to test a little. You can find it here: https://swagger.dev.ltutech.com/?urls.primaryName=MediaDB

Thank you for your interest in the LTU API. Any question let us know.