Page Comparison

This contract is currently in the Proof-of-concept stage and still subject to change

Introduction

To expose AI services to our system, we need an API to be exposed for the MediaHaven installation. When creating new Module Plugins having of the following https://mediahaven.atlassian.The contract of this API is as follows (anything can be added before the path):net/wiki/spaces/CS/pages/edit-v2/4438884395#Categories

Embedding
GenerativeMetadata

then MediaHaven will connect to this plugin using REST API calls, which must implement the following methods depending on the category.

Methods

GET /config-rules

...

Status
colour Blue
title ALL CATEGORIES

It gives the possible configuration parameters for this connector

...

Code Block

language	json

{
  "Rules": [
    {
      "Name": "TextModel",
      "Type": "String|Integer|Boolean",
      "Required": false,
      "Default" : "ada2"
    }
  ]
}

POST /text-embedding
Status
colour Blue
title EMBEDDING

Expected parameters

...

Text as json JSON body in Textproperty and Config based on config rules

...

Code Block

language	json

{
  "Text": "Given me pictures of lamas",
  "Dimensions": 1536,
  "Config": {
    "TextModel" : "ada2"
  }
}

Expected headers

...

Code Block
x-api-key: <optional api key>

Output

Array of float (vector) with size equal to dimensions. The vector is normalized

POST /embedding

Expected parameters:

Record as json body in Metadata property and Config based on config rulesMUST BE normalized. When the provided dimensions are 0, the embedding should be in the natural dimensions used by the embedding. If the embeddings cannot be provided in the requested dimensions, then a 400 HTTP error code should be returned.

Ex.

Code Block

language	json

{
  "Metadata": {
    "RightsManagement": {
        "Permissions": {
            "ExportEmbedding": [ 
               "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
-0.006929283495992422,
               "dd100b7a-efd0-44e3-8816-0905572421da"-0.005336422007530928,
    ... (omitted for  spacing)
       "da100b7a-efd0-44e3-8816-0905572421da"
            ],
            "Write": [
                "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
   -4.547132266452536e-05,
            "dd100b7a-efd0-44e3-8816-0905572421da",
                "da100b7a-efd0-44e3-8816-0905572421da"
            ],
            "Read": [
                "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
                "dd100b7a-efd0-44e3-8816-0905572421da",
                "330060ae-548c-474f-a863-9673fdf99458",
                "de100b7a-efd0-44e3-8816-0905572421da",
                "df100b7a-efd0-44e3-8816-0905572421da",
 -0.024047505110502243]
}

POST /embedding
Status
colour Blue
title EMBEDDING

Expected parameters

Record as JSON body in Metadata property and Config based on config rules

Ex.

Code Block

language	json

{
  "Config": {
    "TextModel" : "ada2"
  },
  "Metadata": {
    "RightsManagement": {
              "da100b7a-efd0-44e3-8816-0905572421da"
            ]
        "Permissions": {...},
        "RecordPhase": "Concept",
        "ExpiryDate": null,
        "ExpiryStatus": null,
        "Zone": {}
    }   },
  "Config": {
    "TextModelDimensions" : "ada2"1536
  }
}

Expected headers

...

Code Block
x-api-key: <optional api key>

Output

Array of float (vector) with size equal to dimensions. The vector is normalizedMUST BE normalized. When the provided dimensions are 0, the embedding should be in the natural dimensions used by the embedding. If the embeddings cannot be provided in the requested dimensions, then a 400 HTTP error code should be returned.

Ex.

Code Block

language	json

{
  "Embedding": [ 
    -0.006929283495992422,
    -0.005336422007530928,
    ... (omitted for spacing)
    -4.547132266452536e-05,
    -0.024047505110502243 
  ]
}

POST /describe
POST /generative-metadata/description
Status
colour Blue
title GENERATIVE

Expected parameters

...

Record as json JSON body in Metadata property and Config based on config rules

...

Code Block

language	json

{
  "MetadataConfig": {
    "RightsManagement": {
        "Permissions": {
            "Export": [
                "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
                "dd100b7a-efd0-44e3-8816-0905572421da",
                "da100b7a-efd0-44e3-8816-0905572421da"
            ],
       TextModel" : "ada2"
  },
  "Metadata": {
    "WriteRightsManagement": [
       {
        "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
                "dd100b7a-efd0-44e3-8816-0905572421da",
                "da100b7a-efd0-44e3-8816-0905572421da"
            ],
            "Read": [
                "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
                "dd100b7a-efd0-44e3-8816-0905572421da",
                "330060ae-548c-474f-a863-9673fdf99458",
                "de100b7a-efd0-44e3-8816-0905572421da",
                "df100b7a-efd0-44e3-8816-0905572421da",
                "da100b7a-efd0-44e3-8816-0905572421da"
            ]
        Permissions": {...},
        "RecordPhase": "Concept",
        "ExpiryDate": null,
        "ExpiryStatus": null,
        "Zone": {}
    }
  },
 
"Config": {
    "TextModel" : "ada2"
  }
}

Expected headers

...

Code Block
x-api-key: <optional api key>

Output

Textual string

Ex.

Code Block

language	json

{
  "Description": "This is an image of a cat"
}

POST /

...

generative-metadata
Status
colour Blue
title GENERATIVE

Record as json JSON body in Metadata property, Describe Fields with as items Dotted dotted keys and AI hint as value, Locale as the requested target locale for the output and finally Config based on config rules

...

Code Block

language	json

{
  "MetadataFields": { 
    "RightsManagementDescriptive.Description": {
 
      "PermissionsHint": {"Give a description for          "Export": [the image"
     },
           "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
  "Descriptive.Keywords.Keyword": {
             "dd100b7a-efd0-44e3-8816-0905572421da",
                "da100b7a-efd0-44e3-8816-0905572421da"
            ],
   "Hint": "Give a list of keywords. Generate around 10.",
        "WriteType": [                 "058b5713-a7d6-45fe-81fc-bcb8b1925fbf","array"
     }
    },
     "dd100b7a-efd0-44e3-8816-0905572421da",
                "da100b7a-efd0-44e3-8816-0905572421da"
            ],
            "Read": [
          "Locale": "en_US",
  "Config": {
     "058b5713-a7d6-45fe-81fc-bcb8b1925fbf",
                "dd100b7a-efd0-44e3-8816-0905572421da",
                "330060ae-548c-474f-a863-9673fdf99458",
                "de100b7a-efd0-44e3-8816-0905572421da",
                "df100b7a-efd0-44e3-8816-0905572421da",
"TextModel" : "ada2"
  },
  "Metadata": {
    "RightsManagement": {
               "da100b7a-efd0-44e3-8816-0905572421da"
            ]
        "Permissions": {...},
        "RecordPhase": "Concept",
        "ExpiryDate": null,
        "ExpiryStatus": null,
        "Zone": {}
    }
  },
  "Fields": 
    { 
    "Descriptive.Description":
"Give a description for the image"
    } 
  
  "Config": {
  
 "TextModel" : "ada2"
  }
}

Expected headers

...

Code Block
x-api-key: <optional api key>

Output

Follow the input fields a nested structure should be returned A JSON object of generated fields with as keys dotted keys and as value the AI's generated value.

Ex:

Code Block

language	json

{ 
  "DescriptiveGeneratedFields": {
    "Descriptive.Description": "This is an image of a cat",
    "Descriptive.Keywords.Keyword": ["Animal", "Cat", ...]  
  }
}

Versions Compared

Old Version 19

New Version Current

Key

Introduction

Methods

GET /config-rules

Status
colour Blue
title ALL CATEGORIES

POST /text-embedding
Status
colour Blue
title EMBEDDING

Expected parameters

Text as json JSON body in `Text`property and `Config` based on config rules
...
Code Block
language json
{ "Text": "Given me pictures of lamas", "Dimensions": 1536, "Config": { "TextModel" : "ada2" } }

Expected headers

Code Block
x-api-key: <optional api key>

Output

POST /embedding

Expected parameters:

POST /embedding
Status
colour Blue
title EMBEDDING

Expected parameters

Expected headers

Code Block
x-api-key: <optional api key>

Output

POST /describe
POST /generative-metadata/description
Status
colour Blue
title GENERATIVE

Expected parameters

Expected headers

Code Block
x-api-key: <optional api key>

Output

POST /

generative-metadata
Status
colour Blue
title GENERATIVE

Expected headers

Code Block
x-api-key: <optional api key>

Output

Page Comparison

Versions Compared

Old Version 19

New Version Current

Key

Introduction

Methods

GET /config-rules

StatuscolourBluetitleALL CATEGORIES

POST /text-embedding StatuscolourBluetitleEMBEDDING

Expected parameters

Text as json JSON body in Textproperty and Config based on config rules... Code Blocklanguagejson{ "Text": "Given me pictures of lamas", "Dimensions": 1536, "Config": { "TextModel" : "ada2" } }

Expected headers

Code Blockx-api-key: <optional api key>

Output

POST /embedding

Expected parameters:

POST /embedding StatuscolourBluetitleEMBEDDING

Expected parameters

Expected headers

Code Blockx-api-key: <optional api key>

Output

POST /describePOST /generative-metadata/description StatuscolourBluetitleGENERATIVE

Expected parameters

Expected headers

Code Blockx-api-key: <optional api key>

Output

POST /

generative-metadata StatuscolourBluetitleGENERATIVE

Expected headers

Code Blockx-api-key: <optional api key>

Output

Status
colour Blue
title ALL CATEGORIES

POST /text-embedding
Status
colour Blue
title EMBEDDING

Text as json JSON body in `Text`property and `Config` based on config rules
...
Code Block
language json
{ "Text": "Given me pictures of lamas", "Dimensions": 1536, "Config": { "TextModel" : "ada2" } }

Code Block
x-api-key: <optional api key>

POST /embedding
Status
colour Blue
title EMBEDDING

Code Block
x-api-key: <optional api key>

POST /describe
POST /generative-metadata/description
Status
colour Blue
title GENERATIVE

Code Block
x-api-key: <optional api key>

generative-metadata
Status
colour Blue
title GENERATIVE

Code Block
x-api-key: <optional api key>