Media - Create

Two API endpoints can be used to upload media to Cogniac manually:

1. Traditional upload

2. Multi-Part/Resumable upload

We recommend using the traditional upload method on smaller, single-frame images and generally using the resumable upload for large images or video files.

• Recommend use of multi-part for media larger than 10MB.

• Require use of multi-part for media larger than 16MB.

• Recommend use of multi-part when the duration of upload is expected to take longer than 60 seconds.

Supported Media Types

The following media types are supported. Please contact Cogniac support if an alternate media format needs to be accommodated.

Cogniac also supports the following video file formats and streaming formats:

Create Media - Single Upload

When uploading a media file to the Cogniac system, Cogniac will pre-populate most media object meta data fields based on the data received, however, several optional parameters can be stored with the media object as well.

POST /1/media/
Host: https://api.cogniac.io

Example: Upload Media - Single Upload

curl -F 'cat.jpg=@path/to/local/file/cat.jpg' https://api.cogniac.io/1/media \
-H "Authorization: Bearer abcdefg.hijklmnop.qrstuvwxyz" \
-f '{
  "media_src":"command_line",
  "meta_tags": [
    "test@cogniac.co",
    "mobile",
    "iPhone 6+",
    "9.2",
    "v2.1"
    ],
  "force_set": "validation"
}'  | json_pp

import requests
from pprint import pprint

my_headers = {"Authorization":"Bearer abcdefg.hijklmnop.qrstuvwxyz"}

# define the file bits and associated meta data
file = {'cat.jpg': open('path/to/local/file/cat.jpg', 'rb')}
media_data = {
  "media_src":"command_line",
  "meta_tags": [
    "test@cogniac.co",
    "mobile",
    "iPhone 6+",
    "9.2",
    "v2.1"
 	],
  "force_set": "validation"
}

res = requests.post("https://api.cogniac.io/1/media",
                    data=media_data,
                    headers=my_headers,
                    files=file)

# Check if the request was successful
if res.status_code == 200:
    pprint(res.json())
else:
    print(f"Error: {res.status_code}")
    print(res.content)

{
  "set_assignment": "validation",
  "num_frames": null,
  "frame": null,
  "video": false,
  "frame_durations": [],
  "duration": null,
  "size": 829491,
  "network_camera_id": null,
  "resize_urls": {
    "454": "https://cogniac-media.s3.amazonaws.com/NUNIQ0V3U8P_max_454",
    "750": "https://cogniac-media.s3.amazonaws.com/NUNIQ0V3U8P_max_750",
    "1334": "https://cogniac-media.s3.amazonaws.com/NUNIQ0V3U8P_max_1334"
  },
  "original_url": null,
  "image_width": 1803,
  "filename": "cat.jpg",
  "original_landing_url": null,
  "fps": null,
  "uploaded_by_user": "test@cogniac.co",
  "media_timestamp": null,
  "media_url": "https://cogniac-media.s3.amazonaws.com/NUNIQ0V3U8P",
  "status": "success",
  "media_id": "NUNIQ0V3U8P",
  "external_media_id": null,
  "time_base": null,
  "source_url": null,
  "author_profile_url": null,
  "media_src": "command_line",
  "parent_media_id": null,
  "md5": "48447b8fe40c16a4a71f2234",
  "parent_media_ids": [],
  "meta_tags": [
    "test@cogniac.co",
    "mobile",
    "iPhone 6+",
    "9.2",
    "v2.1"
    ],
  "license": null,
  "tenant_id": "63QhzFLc9tg4",
  "created_at": 1515782701.981747,
  "author": null,
  "preview_url": null,
  "image_height": 2404,
  "media_format": "JPEG",
  "title": null
}

Media can be directly uploaded to a gateway using a modified URL - the local gateway should be localhost name assigned to the gateway or it's ip address.

POST /1/media/
Host: http://localgateway

Create Media - Multipart/Resumable Upload

Video or other large media files can be uploaded via a resumable, multi-part upload protocol. The upload sequence consists of 3 phases:
Start - Initialize The Upload Session
Transfer - Upload Video Chunks
Finish - Finalize The Upload Session

Limitations:

Cogniac multipart uploads are limited to file sizes of 20GB or less and upload durations of 7 days or less. Saving video is not subject to any known format constraints.

Beginning a resumable upload requires extra parameters in addition to the optional media upload parameters defined above.

Upon successfully completing a resumable upload "start" phase, a unique upload session ID will be returned and must be passed in any additional phases to complete the file transfer.

POST /1/media/resumable
Host: https://api.cogniac.io

Example: Resumable Upload - Start

Step 1: Determine MD5 Hash and File Size

To begin multipart upload, the file size, in bytes, and md5 hash must be passed. To determine these values (on MacOS):

md5sum=`md5 /path/to/local/file/cat.jpg | awk '{ print $4 }'`
echo $md5sum

filesize=`stat -c %s /path/to/local/file/cat.jpg`
echo $filesize

import hashlib
import os

filename = "/path/to/local/file/cat.jpg"

# get the md5 hash
md5 = hashlib.md5(open(filename, 'rb').read()).hexdigest()

# get the file size
filesize = int(os.stat(filename).st_size)

curl -X POST https:api.cogniac.io/1/media/resumable \
-H "Authorization: Bearer abcdefg.hijklmnop.qrstuvwxyz" \
-d '{
 	"upload_phase": "start",
 	"file_size": "'"$filesize"'",
 	"filename": "cat.jpg",
 	"md5": "'"$md5sum"'"
 }'

import requests

# define request headers
my_headers = {"Authorization":"Bearer abcdefg.hijklmnop.qrstuvwxyz"}

# define the file bits and associated meta data
media_data = {
 	"upload_phase": "start",
 	"file_size": filesize,
 	"filename": "cat.jpg",
 	"md5": md5
 }

res = requests.post("https://api.cogniac.io/1/media/resumable",
                    data=media_data,
                    headers=headers)

# Check if the request was successful
if res.status_code == 200:
    pprint(res.json())
else:
    print(f"Error: {res.status_code}")
    print(res.content)

{
   'filename': 'cat.jpg', 
   'upload_session_id': 'MD5Aa9zLN25B2WxBNppJRX3I', 
   'media_id': '6HWK93NCT4OBYQ5VEVEKK', 
   'result': 'Video Upload Initiated', 
   'chunk_size': 10485760
 }

Step 2: Split Media Into Chunks and Transfer

Prepare media file "chunks" using the split function. Once the chunks are prepared for upload, make a sequence of transfer requests to upload each chunk.

import requests
from pprint import pprint
import json
import os


retobj = res.json()
session_id = retobj['upload_session_id']
chunk_size = retobj['chunk_size']

# prepare the file chunks
os.system('/usr/bin/split -a 4 -b %s %s chunk_' % (str(chunk_size), filename))
chunkfiles = [f for f in os.listdir('.') if os.path.isfile(os.path.join('.', f)) and 'chunk' in f]

for i, f in enumerate(chunkfiles):
  media_data = {'upload_phase': 'transfer', 
                'upload_session_id': session_id, 
                'video_file_chunk_no': i + 1}
  
  res = requests.post("https://api.cogniac.io/1/media/resumable",
                      data=media_data,
                      files={filename: open(f, 'rb')},
                      headers=my_headers)
  # Check if the request was successful
if res.status_code == 200:
    pprint(res.json())
else:
    print(f"Error: {res.status_code}")
    print(res.content)

{
  "checksum": "48447b8fe40c16a4a71f2234", 
  "upload_session_id": "MD5Aa9zLN25B2WxBNppJRX3I", 
  "result": "chunk uploaded successfull", 
  "chunk_no": 1
}

Step 3: Finalize The Upload Session

Optional media metadata (defined above) can be passed when finalizing the upload.

import requests
from pprint import pprint
import json

media_data = {'upload_phase': 'finish',
              'upload_session_id': session_id,
              "media_src":"command_line",
              "meta_tags": ["test@cogniac.co", "mobile", "iPhone 6+", "9.2", "v2.1"],
              "force_set": "validation"
             }

  res = requests.post("https://api.cogniac.io/1/media/resumable",
                      data=media_data,
                      headers=my_headers)
  
assert res.status_code == 200
retobj = res.json()

# verify the system determined MD5 checksum 
# matches the MD5 hash ID we provided 
assert str(retobj['md5']) == md5

{
 'media_id': 'NUNIQ0V3U8P',
 'result': 'upload complete',
 'upload_session_id': 'MD5Aa9zLN25B2WxBNppJRX3IS3T'
}

Media Upload with Cogniac SDK

The Cogniac Python SDK determines the most efficient upload media endpoint based on file size, single upload, or multipart upload.

import cogniac

# connect to the tenant
cc = cogniac.CogniacConnection(username="test@cogniac.co", 
                               password="myPassword", 
                               tenant_id="63QhzFLc9tg4")

meta_tags = [
  "test@cogniac.co",
  "mobile",
  "iPhone 6+",
  "9.2",
  "v2.1"
]

# create the media by filename
media = cc.create_media("/path/to/local/file/cat.jpg",
                  meta_tags=meta_tags,
                  force_set="validation")

print(media.media_id)