NAV
shell python javascript

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:

Attribute Type Description
message string A message about the response.
data object/array Contains the data to the response. See each section's "Data object" to see what properties it contains.

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, iptc] in the encode api isn'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

Parameter Type Required Description
media_id string true The id of the media you want to encode. The value is obtained from the upload api.
owner string false The owner of the image.
license object false The license information related to the image. See license for more info.
method integer false Which method you want to encode the image with. Default is 0.
custom object false Any key-value pair objects. See custom-data for more info.

Data object

Parameter Type Description
encode_media_id string The id of the media that is being encoded.
request_id string The id of the request. Use for get media status.

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"
    "return_residual": true
  })
)

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"
    "return_residual": true
  }'
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"
    "return_residual": true
  })
)

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

Parameter Type Required Description
media_id string true The id of the media you want to encode. The value is obtained from the upload api.
owner string false The owner of the image.
license object false The license information related to the image. See license for more info.
method integer false Which method you want to encode the video with. Default is 0.
custom object false Any key-value pair objects. See custom-data for more info.
return_residual boolean false Get back the residual of the video after encoding.

Data object

Parameter Type Description
encode_media_id string The id of the media that is being encoded.
request_id string The id of the request. Use for get media status.

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

Parameter Type Required Description
media_id string true The id associated with the image. Obtained from the Upload API.

Data object

Parameter Type Description
request_id string The id of the request. Use for get media status.

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

Parameter Type Required Description
media_id string true The id associated with the video. Obtained from the Upload API.

Data object

Parameter Type Description
request_id string The id of the request. Use for get media status.

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

Parameter Type Required Description
name string true The name of the media file.
content_type string true The type of content the media file is. See the available types here.
request_type string false The type of request using the upload api for. The value is either "encode" or "decode".
owner string false* The license information related to the media. See license for more info.
license object false* A unique identifier for the media.

Data object

Returns an object with the following attributes:

Attribute Type Description
media_id string A unique identifier for the media.
post_to object Contains the url and form fields to make the POST request
ts datetime The time the presigned url link is generated.
expires datetime The tine the presigned url link will expire.

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 '=@"/path/to/image"' \
--form '<PRESIGNED_FIELDS>'
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",
          "residual_url": "URL_TO_RESIDUAL"
        }
    }
}

Querystring

Parameter Type Required Description
request_id string true The request id obtained from asynchronous endpoints.

Message values

Message string Status code
request_id found. 200
Query string parameter "request_id" is required. 400
Unable to find request item. 404
Unable to find media item associated with request. 404

Data object

Parameter Type Description
status string The status of the request. Can be the following values: "In progress.", "Error.", "Completed.".
message string Information about the get status or related to the image. Note: This is different from the message values in the section above.
request_type string The type of request being run on the media. Can be the following values: "encode" or "decode".
media_data object Data return from a completed encode, decode, or detect operation of the media. See section below for its attributes.

Media data object

Parameter request_type Type Description
image_url encode string The url to download the encode image.
residual_url encode string The url to download the residual image.
owner decode string The owner of the image.
license decode object The license information related to the image. See license for more info.
iptc decode object The iptc fields of the image. See iptc for more info.
custom decode object Any custom fields of the image. See custom for more info.

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.

Parameter Type Required Description
start string false The start date to view the usage of. Format needs to be YYYY-MM-DD.
end string false The end date to view the usage of. Format needs to be YYYY-MM-DD.

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

Attribute Type Required Description
message integer true The total number of items in the data array.
endpoint string true The name of the endpoint.
status_code integer true The status code returned when the endpoint was called.
ts date true The date and time the endpoint was accessed. Format: YYYY-MM-DD HH:MM:SS.
media_id string false A unique identifier for the media. Only appears if the request was success.

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"
        },
        . . . 
    ]
}

This endpoint returns all media files you have uploaded and its data associated with each media.

Message

Contains the total number of media you have uploaded.

Data object

Attribute Type Description
iptc object The IPTC values related to the media. See [IPTC] for more info.
license object The license information related to the media. See license for more info.
media_id string A unique identifier for the media.
media_type string Whether the media is an image or video.
name string The filename of the media.
owner string The owner of the media.
path string The url of the media.
size integer The size of the media.
status boolean If the media have been encoded or not.
thumbnail string The thumbnail url of the media.
ts date The date and time the media have been last edited. Format: YYYY-MM-DD HH:MM:SS.
upload_date date The date and time the media have been uploaded.
version integer The current version of the media.

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": [
        {
            "iptc": {},
            "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",
            "residual" : "URL_TO_RESIDUAL_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

Parameter Type Required Description
media_id string true The unique identifier for the media.

Message

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

Data object

Attribute Type Description
iptc object The IPTC values related to the media. See [IPTC] for more info.
license object The license information related to the media. See license for more info.
media_id string A unique identifier for the media.
media_type string Whether the media is an image or video.
name string The filename of the media.
original string The url path of the original media.
owner string The owner of the media.
path string The url of the encoded media.
residual string The url of the residual after encoding media.
size integer The size of the media.
status boolean If the media have been encoded or not.
thumbnail string The thumbnail url of the media.
ts date The date and time the media have been last edited. Format: MM/DD/YYYY HH:MM:SS.
upload_date date The date and time the media have been uploaded. Format: MM/DD/YYYY HH:MM:SS.
version integer The current version of the media.

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

Parameter Type Required Description
media_id string true A unique identifier for the media.

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

Parameter Type Required Description
media_id string true A unique identifier for the media.
owner string false The owner of the image.
license object false The license information related to the image. See license for more info.
iptc object false The IPTC values related to the media. See [IPTC] for more info.

Data object

Parameter Type Description
media_id string A unique identifier for the media.

History API

Get the History of an Asset

import requests

response = requests.get("https://api.steg.ai/history?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?id=EXAMPLE_MEDIA_ID" \
  -H "x-api-key: api_key_here"
fetch(
  "https://api.steg.ai/history?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

Parameter Type Required Description
media_id string true A unique identifier for the media.

Data object

Returns an array of objects with the following attributes:

Attribute Type Description
change object An object contains the changes of the media's version number compared to its previous version. See change for more info.
license object The license information related to the media. See license for more info.
new object An object contains all the new data associated with the media's version number.
ts date The date and time the media have been edited/uploaded. Format: YYYY-MM-DD HH:MM:SS.
version integer The current version of the media.
path string The url of the media's version number.
status boolean If the media have been encoded or not.
owner string The owner of the media's version number.
media_id string A unique identifier for the media.

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:

Attribute Type Description
new string The current value of the field.
old string The previous value of the field.

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

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",
            "residual": "url_to_residual_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",
            "iptc": {}
        },
        "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:

Attribute Type Description
editorial boolean If the media can be used for editorial purposes.
commercial boolean If the media can be used for commercial purposes.
expiration date The date when the license expires.
type string The type of license. Can be one of the following: Creative Commons, Royalty Free, Copyright Free, Public Domain
url string The url to the license.
info string Additional info about the license.

Content Types

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

Name MIME Type Extension
Bitmap (BMP) image/bmp .bmp
Joint Photographic Expert Group image (JPEG) image/jpeg .jpg, .jpeg, .jfif, .pjpeg, .pjp
Portable Network Graphics (PNG) image/png .png
TIF image (TIF) image/tiff .tif, .tiff
Web Picture format (WEBP) image/webp .webp

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

Attribute Type Description
message string The error message. Contains a helpful message on why the request failed.
type string The error type. Scroll to Error Types for more information.

HTTP Status Codes

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The method requested is hidden for administrators only.
404 Not Found -- The specified method could not be found.
405 Method Not Allowed -- You tried to access an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.

Error Types

Error Type Meaning
params_invalid The parameters included in the request are invalid. Make sure the parameters are the correct type and value.
invalid_request The request you made doesn't support this method. Make sure the request method is correct.
authenication_error The api key included in the request is invalid or not set. Make sure the api key is correct and in the headers.
api_error API errors cover any other type of problem (e.g., a temporary problem with steg.ai's servers), and are extremely uncommon.