Introduction

Welcome to the steg.ai API! You can use our API to access steg.ai API endpoints, which can protect and authenticate media.

We have code examples in Shell, Python, and JavaScript! You can view it in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Base URL:

"https://api.steg.ai"

Authentication

To authorize, include the API key in the header like in this code:

import requests

requests.get("https://api.steg.ai/<ENDPOINT>", 
  headers={
    "x-api-key" : "api_key_here"
  }, 
)

# With shell, you can just pass the correct header with each request
curl "https://api.steg.ai" \
  -H "x-api-key: api_key_here"

fetch(
  "https://api.steg.ai",
  headers: {
    "x-api-key": "api_key_here"
  }
)

Make sure to replace api_key_here with your own API key.

steg.ai uses API keys to allow access to the API. You can register a new steg.ai API key by contacting us.

steg.ai expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-api-key: api_key_here

Response

All steg.ai endpoints will return a successful response in the following format:

For non-successful responses, see Errors for more information.

How To Guides

This section describes the most common flows to support developers getting started with the steg.ai API. Each step is linked to their respective section for more information.

How to Encode an Image

In this guide, we'll show the full process on how to encode the following image using python as an example.

The image is called download.png.

01) Generate presigned-url to upload image

See upload api for more information.

import json

import requests

BASE_URL = "https://api.steg.ai"
APIKEY = "api_key_here"

headers = {
    "Content-Type": "application/json",
    "x-api-key": APIKEY
}
payload = {
    "name": "download.png",
    "content_type": "image/png"
}
response = requests.post(f"{BASE_URL}/upload",
                         headers=headers, data=json.dumps(payload))

# Need these values for next steps
post_to_fields = response.json().get("data").get("post_to")
media_id = response.json().get("data").get("media_id")

02) Upload an image to the url

See upload api for more information.

with open("download.png", "rb") as file:
    url = post_to_fields.get("url")
    form_data = post_to_fields.get("fields")
    files = {
        "file": file
    }

    requests.post(url=url, files=files, data=form_data)

03) Encode the image

See encode api for more information.

payload = {
    "media_id": media_id,
}
response = requests.post(
    f"{BASE_URL}/encode_image_async", headers=headers, data=json.dumps(payload))

request_id = response.json().get("data").get("request_id")

04) Get the status of the encoding

See Check Status API for more information.

while True:
    response = requests.get(
        f"{BASE_URL}/media_status?request_id={request_id}", headers=headers)
    request_data = response.json().get("data")
    if request_data.get("status") == "Completed.":
        media_data = request_data.get("media_data")
        media_url = media_data.get("media_url")
        break

05) Download the encoded image

response = requests.get(media_url)
if response.status_code == 200:
    with open("encoded_image.png", 'wb') as f:
        f.write(response.content)

Full code below

import json

import requests

BASE_URL = "https://api.steg.ai"
APIKEY = "api_key_here"

headers = {
    "Content-Type": "application/json",
    "x-api-key": APIKEY
}
payload = {
    "name": "download.png",
    "content_type": "image/png"
}
response = requests.post(f"{BASE_URL}/upload",
                         headers=headers, data=json.dumps(payload))

post_to_fields = response.json().get("data").get("post_to")
media_id = response.json().get("data").get("media_id")

with open("download.png", "rb") as file:
    url = post_to_fields.get("url")
    form_data = post_to_fields.get("fields")
    files = {
        "file": file
    }

    requests.post(url=url, files=files, data=form_data)

payload = {
    "media_id": media_id,
}
response = requests.post(
    f"{BASE_URL}/encode_image_async", headers=headers, data=json.dumps(payload))

request_id = response.json().get("data").get("request_id")

while True:
    response = requests.get(
        f"{BASE_URL}/media_status?request_id={request_id}", headers=headers)
    request_data = response.json().get("data")
    if request_data.get("status") == "Completed.":
        media_data = request_data.get("media_data")
        media_url = media_data.get("media_url")

        response = requests.get(url=media_url)
        with open("encoded_image.png", 'wb') as f:
            f.write(response.content)
        break

How to Decode an Image

In this guide, we'll show the full process on how to decode the following image using python as an example.

The image is called watermarked_file.png. When successfully decoded, the image will contain data with the following message: "this is an example image that's been watermarked".

01) Generate presigned-url to upload image

See upload api for more information.

import json
import requests

BASE_URL = "https://api.steg.ai"
APIKEY = "api_key_here"

headers = {
    "Content-Type": "application/json",
    "x-api-key": APIKEY
}
payload = {
    "name": "watermarked_file.png",
    "content_type": "image/png"
}
response = requests.post(f"{BASE_URL}/upload",
                         headers=headers, data=json.dumps(payload))

# Need these values for next steps
post_to_fields = response.json().get("data").get("post_to")
media_id = response.json().get("data").get("media_id")

02) Upload the image to the url

See upload api for more information.

with open("watermarked_file.png", "rb") as file:
    url = post_to_fields.get("url")
    form_data = post_to_fields.get("fields")
    files = {
        "file": file
    }

    requests.post(url=url, files=files, data=form_data)

03) Decode the image

See Decode API for more information.

payload = {
    "media_id": media_id,
}
response = requests.post(
    f"{BASE_URL}/decode_image_async", headers=headers, data=json.dumps(payload))

request_id = response.json().get("data").get("request_id")

04) Get the data from the image

See check status api for more information.

while True:
    response = requests.get(
        f"{BASE_URL}/media_status?request_id={request_id}", headers=headers)
    request_data = response.json().get("data")
    if request_data.get("status") == "Completed.":
        media_data = request_data.get("media_data")
        print(media_data)
        break

Full code below

import json
import requests

BASE_URL = "https://api.steg.ai"
APIKEY = "api_key_here"

headers = {
    "Content-Type": "application/json",
    "x-api-key": APIKEY
}
payload = {
    "name": "watermarked_file.png",
    "content_type": "image/png"
}
response = requests.post(f"{BASE_URL}/upload",
                         headers=headers, data=json.dumps(payload))

post_to_fields = response.json().get("data").get("post_to")
media_id = response.json().get("data").get("media_id")

with open("watermarked_file.png", "rb") as file:
    url = post_to_fields.get("url")
    form_data = post_to_fields.get("fields")
    files = {
        "file": file
    }

    requests.post(url=url, files=files, data=form_data)

payload = {
    "media_id": media_id,
}
response = requests.post(
    f"{BASE_URL}/decode_image_async", headers=headers, data=json.dumps(payload))

request_id = response.json().get("data").get("request_id")

while True:
    response = requests.get(
        f"{BASE_URL}/media_status?request_id={request_id}", headers=headers)
    request_data = response.json().get("data")
    if request_data.get("status") == "Completed.":
        media_data = request_data.get("media_data")
        print(media_data)
        break

How to Set Custom Data When Encoding

You might have an usecase where the attributes provided: [license, owner] in the encode api aren't useful or needed. We provide a custom parameter allowing users to put any data they want into their media. The custom object is an object allowing any key-value pairs you can think of.

import json
import requests

BASE_URL = "https://api.steg.ai"
APIKEY = "api_key_here"

headers = {
    "Content-Type": "application/json",
    "x-api-key": APIKEY
}

payload = {
    "media_id": "example_media_id",
    "custom": {
      "custom_key_1": "custom_value_1",
    }
}
requests.post(
    f"{BASE_URL}/encode_image_async", headers=headers, data=json.dumps(payload))

Example 01: Including location data into the image

import json

import requests

BASE_URL = "https://api.steg.ai"
APIKEY = "api_key_here"

headers = {
    "Content-Type": "application/json",
    "x-api-key": APIKEY
}

payload = {
    "media_id": "example_media_id",
    "custom": {
      "location": "New York, NY",
      "ip_address": "192.158.1.38"
    }
}
requests.post(
    f"{BASE_URL}/encode_image_async", headers=headers, data=json.dumps(payload))

Sample Applications

This section provides examples of sample applications in Python and JavaScript that use steg.ai's API, which encapsulate the entire process of encoding and decoding an image.

Head to the sample apps repo to access the repository and instructions on how to run them.

Encode API

steg.ai offers two asychronous endpoints to encode images or videos.

Encode an Image

import base64
import json
import requests

response = requests.post("https://api.steg.ai/encode_image_async", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }, 
  data=json.dumps({
    "license": {},
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8",
    "method": 0,
    "owner": "steg.ai",
  })
)

print(response.text)

curl "https://api.steg.ai/encode_image_async" \
  -H "x-api-key: api_key_here" \
  --data-raw '{ \
    "license": {}, \
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8", \
    "method": 0, \
    "owner": "steg.ai", \
  }'

fetch(
  "https://api.steg.ai/encode_image_async",
  method: "POST",
  headers: {
    "x-api-key": "api_key_here"
  },
  body: JSON.stringify({
    "license": {},
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8",
    "method": 0,
    "owner": "steg.ai",
  })
)

The above code returns JSON structured like this:

{
    "message": "Request successful. Your image will be encoded soon.",
    "data": {
      "encode_media_id": "7e1da036-f04d-4c08-9e02-d58366d41037",
      "request_id": "c7deb911-2c7e-498f-91be-eaee25721c49"
    }
}

This endpoint encodes an image with a payload. To check the status of the encoding see get media status for more info.

Request body

Data object

Encode a Video

import json
import requests

response = requests.post("https://api.steg.ai/encode_video", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }, 
  data=json.dumps({
    "license": {},
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8",
    "method": 0,
    "owner": "steg.ai",
  })
)

print(response.text)

curl "https://api.steg.ai/encode_video" \
  -H "x-api-key: api_key_here" \
  --data-raw '{ \
    "license": "{}", \
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8", \
    "method": "0", \
    "owner": "steg.ai", \
  }'

fetch(
  "https://api.steg.ai/encode_video",
  method: "POST",
  headers: {
    "x-api-key": "api_key_here"
  },
  body: JSON.stringify({
    "license": {},
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8",
    "method": 0,
    "owner": "steg.ai",
  })
)

The above code returns JSON structured like this:

{
    "message": "Request successful. Your video will be encoded soon.",
    "data": {
      "encode_media_id": "7e1da036-f04d-4c08-9e02-d58366d41037",
      "request_id": "c7deb911-2c7e-498f-91be-eaee25721c49"
    }
}

This endpoint encodes a video with a payload. To check the status of the encoding see get media status for more info.

Request body

Data object

Decode API

steg.ai offers two asychronous endpoints to decode images or videos.

Decode an Image

import base64
import json
import requests

response = requests.post("https://api.steg.ai/decode_image_async", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }, 
  data=json.dumps({
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8"
  })
)

print(response.text)

curl "https://api.steg.ai/decode_image_async" \
  -H "x-api-key: api_key_here" \
  --data-raw '{ \
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8" \
  }'

fetch(
  "https://api.steg.ai/decode_image_async",
  method: "POST",
  headers: {
    "x-api-key": "api_key_here"
  },
  body: JSON.stringify({
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8"
  })
)

The above code returns JSON structured like this:

{
  "message": "Request successful. Your image will be decoded soon.", 
  "data": {
    "request_id": "c7deb911-2c7e-498f-91be-eaee25721c49"
  }
}

This endpoint decodes an image. To check the status of the decoding see get media status for more info.

Request body

Data object

Decode a Video

import base64
import json
import requests

response = requests.post("https://api.steg.ai/decode_image_async", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }, 
  data=json.dumps({
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8"
  })
)

print(response.status_code) # Returns 200

curl "https://api.steg.ai/decode_image_async" \
  -H "x-api-key: api_key_here" \
  --data-raw '{ \
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8" \
  }'

fetch(
  "https://api.steg.ai/decode_image_async",
  method: "POST",
  headers: {
    "x-api-key": "api_key_here"
  },
  body: JSON.stringify({
    "media_id": "eabb1b2c-e380-409b-a29b-62608aa695a8"
  })
)

The above code returns JSON structured like this:

{
  "message": "Request successful. Your image will be decoded soon.", 
  "data": {
    "request_id": "c7deb911-2c7e-498f-91be-eaee25721c49"
  }
}

This endpoint decodes a video. To check the status of the decoding see get media status for more info.

Request body

Data object

Upload API

Generate a pre-signed URL

import requests

response = requests.post("https://api.steg.ai/upload", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  },
  data=json.dumps({
    "name": "name of file",
    "content_type": "image/png"
  })
)

print(response.status_code) # Returns 200

curl "https://api.steg.ai/upload" \
  -H "x-api-key: api_key_here" \
  --data-raw '{ \
    "name" : "name of file", \
    "content_type": "image/png" \
  }'

fetch(
  "https://api.steg.ai/upload",
  method: "POST",
  headers: {
    "x-api-key": "api_key_here"
  },
  body: JSON.stringify({
    "name": "name of file",
    "content_type": "image/png"
  })
)

{
    "message": "Send a POST request to the url"
    "data": {
        "media_id": "EXAMPLE_MEDIA_ID",
        "post_to": {
          "url": "PRESIGNED_URL",
          "fields": "PRESIGNED_FIELDS"
        },
        "ts": "09/08/2021 12:00:00",
        "expires": "09/08/2021 12:05:00"
    }
}

This endpoint generates a presigned url for you to upload your media file.

Request body

Data object

Returns an object with the following attributes:

Upload file

import requests

with open(<file_path>, "rb") as file:
    files = {
        "file": file
    }

    requests.post(url=<PRESIGNED_URL_HERE>, files=files, data=<PRESIGNED_FIELDS>)

    print(response.status_code) # Returns 200

curl -X POST -T "/path/to/file" \
  -H "Content-Type: image/png" \
  "<PRESIGNED_URL_HERE>" 

curl --location --request POST "<PRESIGNED_URL_HERE>" \
--form '<PRESIGNED_FIELDS>' \
--form 'file=@"/path/to/image"'

const uploadFormData = new FormData();
for (const [key, value] of <POST_TO_OBJECT>) {
    uploadFormData.append(key, value);
}

// Note: Append the file object
uploadFormData.append("file", <file>);

fetch(
  "<PRESIGNED_URL_HERE>", {
    method: "POST",
    body: uploadFormData
  }
)

After generating a presigned url, use the post_to object to make a POST request to upload your files.

Check Status

Get Media Status

Get the status of a request.

import requests

request_id = "example_request_id"

response = requests.get("https://api.steg.ai/media_status?request_id=request_id", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }
)

print(response.status_code) # Returns 200

curl "https://api.steg.ai/media_status?request_id=example_request_id" \
  -H "x-api-key: api_key_here"

const requestId = "example_request_id";

fetch(
  "https://api.steg.ai/media_status?request_id=requestId",
  method: "GET",
  headers: {
    "x-api-key": "api_key_here"
  },
)

The above code returns JSON structured like this:

{
    "message": "request_id found.",
    "data": {
        "status": "Completed.",
        "request_type": "encode",
        "media_data": {
          "media_url": "URL_TO_IMAGE",
        }
    }
}

Querystring

Message values

Data object

Media data object

Usage API

Get Current Usage of the API

import requests

response = requests.get("https://api.steg.ai/usage", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }
)

print(response.status_code) # Returns 200

curl "https://api.steg.ai/usage" \
  -H "x-api-key: api_key_here"

fetch(
  "https://api.steg.ai/usage",
  method: "GET",
  headers: {
    "x-api-key": "api_key_here"
  }
)

The above code returns JSON structured like this:

{
  {
    "message": 3,
    "data": [
        {
            "media_id": "d051f164-b066-4702-8343-c61ba098ba63",
            "ts": "01/05/2021 16:54:24",
            "endpoint": "encode_image",
            "status_code": 200
        },
        {
            "media_id": "e5c57510-d2e2-4cc8-afb4-b3ce1fa77b71",
            "ts": "01/05/2021 17:12:15",
            "endpoint": "encode_image",
            "status_code": 200
        },
        {
            "ts": "01/05/2021 17:27:58",
            "endpoint": "encode_image",
            "status_code": 400
        },
    ]
  }
}

This endpoint returns the usage of each endpoint and the status code for steg.ai API.

Querystring

Use querystrings to get more specific usage data of a date or of an endpoint.

The start and end querystrings needs to be in this format: YYYY-MM-DD. Must contain the year while month and day are optional.

Data object

Asset API

Assets is a collection of media (image or video) you have uploaded.

Retrieve All Assets

import requests

response = requests.get("https://api.steg.ai/asset",
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }
)

print(response.text)

curl "https://api.steg.ai/asset" \
  -H "x-api-key: api_key_here"

fetch(
  "https://api.steg.ai/asset",
  method: "GET",
  headers: {
    "x-api-key": "api_key_here"
  }
)

{
    "message": 7
    "data": [
        {
            "ts": "03/12/2021 15:58:03",
            "license": {
                "editorial": false,
                "commercial": true,
                "expiration": "2021-03-09T17:49:46.117Z",
                "type": "Royalty Free",
                "url": "https://en.wikipedia.org/wiki/Royalty-free",
                "info": "Royalty-free (RF) material subject to copyright or other intellectual property rights may be used without the need to pay royalties or license fees for each use, per each copy or volume sold or some time period of use or sales."
            },
            "size": 159779,
            "version": 2,
            "path" : "URL_TO_IMAGE",
            "thumbnail" : "URL_TO_THUMBNAIL",
            "status": true,
            "owner": "steg.ai",
            "media_id": "30bbab94-5e0d-4639-9bdf-acbf55812d61"
        },
        . . .
    ],
    "next_key": "EXAMPLE_PAGE_KEY"
}

This endpoint returns all media files you have uploaded and each one's associated data. Limits to 25 per request.

Querystring

Message

Contains the total number of media you have uploaded.

Data object

Next key

This value is used for pagination and is only included in the response when there are more media files that can be retrieved. Include it in the next query param in a subsequent call to the endpoint to retrieve the next set of media files. Repeat until the value is no longer provided and you will have every media file. NOTE: This endpoint does not sort on any particular field, so if a specific sort order is required you must fetch all items and sort them yourself. Ability to sort the result set within the call is being actively worked on.

Retrieve an Asset

import requests

response = requests.get("https://api.steg.ai/asset?media_id=30bbab94-5e0d-4639-9bdf-acbf55812d61",
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }
)

print(response.text)

curl "https://api.steg.ai/asset?media_id=30bbab94-5e0d-4639-9bdf-acbf55812d61" \
  -H "x-api-key: api_key_here"

fetch(
  "https://api.steg.ai/asset?media_id=30bbab94-5e0d-4639-9bdf-acbf55812d61",
  method: "GET",
  headers: {
    "x-api-key": "api_key_here"
  }
)

{
    "message": 1
    "data": [
        {
            "license": {
                "editorial": false,
                "commercial": true,
                "expiration": "2021-03-09T17:49:46.117Z",
                "type": "Royalty Free",
                "url": "https://en.wikipedia.org/wiki/Royalty-free",
                "info": "Royalty-free (RF) material subject to copyright or other intellectual property rights may be used without the need to pay royalties or license fees for each use, per each copy or volume sold or some time period of use or sales."
            },
            "media_id": "30bbab94-5e0d-4639-9bdf-acbf55812d61",
            "media_type": "image",
            "name": "download20211106144008.png",
            "original": "URL_TO_ORIGINAL_IMAGE",
            "owner": "steg.ai",
            "path" : "URL_TO_IMAGE",
            "size": 159779,
            "status": true,
            "thumbnail" : "URL_TO_THUMBNAIL",
            "ts": "11/19/2021 15:04:14",
            "upload_date": "11/19/2021 15:04:14",
            "version": 2
          },
    ]
}

This endpoint returns the data associated with a specific media.

Request body

Message

Contains the total number of media you have retrieved. Will always be 1.

Data object

Delete an Asset

import requests

response = requests.delete("https://api.steg.ai/asset",
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  },
  data=json.dumps({
    "media_id" : "EXAMPLE_MEDIA_ID"
  })
)

print(response.text)

curl "https://api.steg.ai/asset" \
  -X DELETE -H "x-api-key: api_key_here"
  --data-raw '{
    "media_id" : "EXAMPLE_MEDIA_ID"
  }'

fetch(
  "https://api.steg.ai/asset,
  method: "DELETE",
  headers: {
    "x-api-key": "api_key_here"
  },
  body: JSON.stringify({
    "media_id" : "EXAMPLE_MEDIA_ID"
  })
)

The above code returns JSON structured like this:

{
    "message": "True",
    "data": {}
}

This endpoint delete a media.

Request body

Data object

Returns an empty object.

Update an Asset

import requests

response = requests.post("https://api.steg.ai/asset",
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  },
  data=json.dumps({
    "media_id" : "EXAMPLE_MEDIA_ID",
    "owner" : "new owner"
  })
)

print(response.text)

curl "https://api.steg.ai/asset" \
  -X POST -H "x-api-key: api_key_here" \
  --data-raw '{ \
    "media_id" : "EXAMPLE_MEDIA_ID", \
    "owner" : "new owner' \
  }'

fetch(
  "https://api.steg.ai/asset,
  method: "POST",
  headers: {
    "x-api-key": "api_key_here"
  },
  body: JSON.stringify({
    "media_id" : "EXAMPLE_MEDIA_ID",
    "owner" : "new owner"
  })
)

The above code returns JSON structured like this:

{
    "message": "Successfully updated data",
    "data": {
        "media_id": "EXAMPLE_MEDIA_ID",
    }
}

This endpoint updates data associated with a media. Any parameter listed below (except media_id) can be updated.

Request body

Data object

History API

Get the History of an Asset

import requests

response = requests.get("https://api.steg.ai/history?media_id=EXAMPLE_MEDIA_ID", 
  headers={
    "Content-Type" : "application/json",
    "x-api-key" : "api_key_here"
  }
)

print(response.text) # Returns 200

curl "https://api.steg.ai/history?media_id=EXAMPLE_MEDIA_ID" \
  -H "x-api-key: api_key_here"

fetch(
  "https://api.steg.ai/history?media_id=EXAMPLE_MEDIA_ID",
  method: "GET",
  headers: {
    "x-api-key": "api_key_here"
  }
)

{
    "message": 1
    "data": [
        {
            "change": {
                "owner": {
                    "new": "Joe", 
                    "old": "Evan"
                }
            },
            "new" : {},
            "ts": "03/12/2021 15:58:03",
            "license": {
                "editorial": false,
                "commercial": true,
                "expiration": "2021-03-09T17:49:46.117Z",
                "type": "Royalty Free",
                "url": "https://en.wikipedia.org/wiki/Royalty-free",
                "info": "Royalty-free (RF) material subject to copyright or other intellectual property rights may be used without the need to pay royalties or license fees for each use, per each copy or volume sold or some time period of use or sales."
            },
            "size": 159779,
            "version": 2,
            "path" : "URL_TO_IMAGE",
            "status": true,
            "owner": "Among Us",
            "id": "30bbab94-5e0d-4639-9bdf-acbf55812d61"
        },
    ]
}

This endpoint returns the history of an asset. It will show all the new and updated data associated with an asset.

Querystring

Data object

Returns an array of objects with the following attributes:

Change object

The change object is a key-value object where the key is the field that's been changed and the value is the structured in the following:

WebSockets API

steg.ai presents a WebSocket api in order to receive real-time messages from actions such as protecting/authenticating images or videos. For example, clients connected to the WebSocket will receive messages when a video is done protecting.

List of available actions

The WebSocket has a limited set of actions compared to the REST API.

• auth
• decode
• ping
• subscribe

Auth

Use this route to authenticate the WebSocket connection. Required to use the rest of actions.

Send the following message to the WebSocket:

{
    "action": "auth", 
    "apiKey": "api_key_here"
}

Returns

{
    "statusCode": 200, 
    "body": "{"message": "Authenicated"}"
}

Decode

Use this route to decode a media. This route will continue to update you on the progress as long as you're still connected to the WebSocket connection.

Send the following message to the WebSocket:

{
    "action":"decode", 
    "media_id": "30bbab94-5e0d-4639-9bdf-acbf55812d61", 
    "media_type": "image", 
    "method": 0, 
    "force": true
}

Ping

Use this route to keep the WebSocket connection alive.

Send the following message to the WebSocket:

{
    "action": "ping"
}

Returns

{
    "statusCode": 200, 
    "body": "{"message": "pong"}"
}

Subscribe

Use this route to keep track of an event (encode, decode) of an asset.

Send the following message to the WebSocket:

{
    "action": "subscribe", 
    "id": "c7deb911-2c7e-498f-91be-eaee25721c49"
}

Returns the following if the request_id is from an encode event:

{
    "statusCode": 200,
    "body": "{
        "request_id": "c7deb911-2c7e-498f-91be-eaee25721c49",
        "data": {
            "image": "url_to_encode_image_here",
        },
        "status": "Completed."
    }"
}

Returns the following if the request_id is from a decode event:

{
    "statusCode": 200,
    "body": "{
        "request_id": "c7deb911-2c7e-498f-91be-eaee25721c49",
        "data": {
            "license": {
                "editorial": false,
                "expiration": "12/20/2025",
                "commercial": true,
                "type": "Creative Commons",
                "url": "http://creativecommons.org/licenses/by/4.0/",
                "info": "Creative Commons licenses give everyone from individual creators to large institutions a standardized way to grant the public permission to use their creative work under copyright law."
            },
            "ts": "11/19/2021 15:04:14",
            "upload_date": "11/19/2021 15:04:14",           
            "owner": "danny",
        },
        "status": "Completed."
    }"
}

Non-existent Routes

If the action parameter in the messages is not one of the above or mispelled, the following error would appear

{
    "statusCode": 400,
    "body": "Route doesn't exist. Check docs for more information."
}

License Object

The license object contains the data related to the licensing of a particular media.

The object has the following attributes:

Content Types

The following table are the file content types we currently support to encode:

Errors

The steg.ai API uses the standard HTTP response codes to indicate success or failure of an API request. A 200 shows a successful request. But a 4xx range means an error from the client (e.g. invalid parameters for a request). Codes in 5xx range means there's an error on steg.ai API's.

The steg.ai API uses the following error structure:

{
    "error": {
        "message": "Image is not a valid base64 string.",
        "type": "params_invalid"
    }
}

The above error code would return a 400 status code.

Attributes

HTTP Status Codes

Error Types