Media - Create

There are two API endpoints that can be used to manually upload media to Cogniac:

Traditional upload
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 then 10MB.
Require use of multi-part for media larger than 16MB.
Recommend use of multi-part when duration of upload is expected to take longer than 60 seconds.

📘
Tenant Media
The tenant ID and user ID are saved with the media, user_id is stored as uploaded_by_user and. Users may only retrieve and update media belonging to their tenant.

Supported Media Types

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

File Types	File Name
JPEG files	.jpeg, .jpg, *.jpe
Portable Network Graphics	*.png
Bitmap image file	*.bmp

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

File Type	File Name
MPEG-4	.mp4, .m4a, .m4p, .m4b, .m4r and .m4v
MOV	.mov, .qt
MJPEG	*.mjpeg
H.264	*.h264

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, there are several optional parameters that can be stored with the media object as well.

Name	Example	Description
force_set string	"validation"	(optional) One of "training" or "validation". Denotes whether the media will be used as training or validation data for model development. If `null` the set will be randomly assigned.
media_timestamp float	1234567890	(optional) User-specified image timestamp
media_src string	"Twitter"	(optional) Origin of this media, such as google, facebook, flickr, etc, or describes mobile_app, command_line, web_app
filename string	"my_image.jpg"	(optional) Filename of the uploaded media.
meta_tags array	"meta_tags": [ "[email protected]", "mobile", "iPhone 6+", "9.2", "v2.1" ],	(optional) Other associated metadata.
external_media_id string	"000060e3121c7305"	(optional) A unique ID for this media from it's external data source. E.g., the ImageID field from the OpenImages dataset.
network_camera_id string	97654rtyh	(optional) ID of the Cogniac Network Camera that captured the media.
original_url string	"https://c1.staticflickr.com/5/4129/5215831864_46f356962f_o.jpg"	(optional) The original URL for this media. E.g., the OriginalURL field from the OpenImages dataset.
original_landing_url string	"https://www.flickr.com/photos/brokentaco/5215831864"	(optional) The original landing URL for this media. E.g., the OriginalLandingURL field from the OpenImages dataset.
license string	"https://creativecommons.org/licenses/by/2.0/"	(optional) License information about this media. E.g., the URL in the License field of the OpenImages dataset.
author_profile_url string	"https://www.flickr.com/people/brokentaco/"	(optional) URL of the media owner. E.g., the AuthorProfileURL field from the OpenImages dataset.
author string	"David"	(optional) Name of the media owner. E.g., the Author field from the OpenImages dataset.
title string	"28 Nov 2010 Our new house."	(optional) Title of this media. E.g., the Title field from the OpenImages dataset.
source_url string	"https://c1.staticflickr.com/5/4129/5215831864_46f356962f_o.jpg"	(optional) Can pass an optional URL to the media to be created instead of a file.
preview_url string	"https://c1.staticflickr.com/5/4129/5215831864_46f356962f_o.jpg"	(optional) URL for media preview image for display.

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": [
    "[email protected]",
    "mobile",
    "iPhone 6+",
    "9.2",
    "v2.1"
 	],
  "force_set": "validation"
}'

import requests
from pprint import pprint

# define request headers
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": [
    "[email protected]",
    "mobile",
    "iPhone 6+",
    "9.2",
    "v2.1"
 	],
  "force_set": "validation"
}

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

pprint(res.json())

{
  "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": "[email protected]",
  "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": [
    "[email protected]",
    "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.

Name	Example	Description
upload_phase string	start	(required) One of start, transfer, or finish. The phase of the multipart upload. There can be many transfer stages in a single upload session.
file_size integer	213123	(required) Size of the media file in bytes.
filename string	videoplayback.mp4	(required) Filename of the media file.
md5 string	c7299866d9a68aa6735dd10	(required) md5 hash of the media file. See Media - Subjects for an example of generating the md5 hash.
video_file_chunk_no integer	1	(required) The index (starting from 1) of the chunk of the media file that is current being uploaded.

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

Name	Example	Description
upload_session_id string	D5Aa9zLN25B2W	_(read_only)_The session id for the resumable upload. Multipart media upload session IDs are stored for up to 7 days. After 7 days any upload not completed will need to be reinitialized.

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

Example: Resumable Upload - Start

Step 1: Determine MD5 Hash and File Size

📘
Media MD5 Hash and File Size
Resumable Media upload requires file size, in bytes, and a valid MD5 checksum for the media file.

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 -f%z /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)

pprint(res.json())

{
   '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.

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)
  assert res.status_code == 200

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

Step 3: Finalize The Upload Session

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

media_data = {'upload_phase': 'finish',
              'upload_session_id': session_id,
              "media_src":"command_line",
              "meta_tags": ["[email protected]", "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="[email protected]", 
                               password="myPassword", 
                               tenant_id="63QhzFLc9tg4")

meta_tags = [
  "[email protected]",
  "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

Media - Create

📘
Tenant Media

Supported Media Types

Create Media - Single Upload

Example: Upload Media - Single Upload

Create Media - Multipart/Resumable Upload

Example: Resumable Upload - Start

Step 1: Determine MD5 Hash and File Size

📘
Media MD5 Hash and File Size

Step 2: Split Media Into Chunks and Transfer

Step 3: Finalize The Upload Session

Media Upload with Cogniac SDK

📘Tenant Media

Supported Media Types

Create Media - Single Upload

Example: Upload Media - Single Upload

Create Media - Multipart/Resumable Upload

Example: Resumable Upload - Start

Step 1: Determine MD5 Hash and File Size

📘Media MD5 Hash and File Size

Step 2: Split Media Into Chunks and Transfer

Step 3: Finalize The Upload Session

Media Upload with Cogniac SDK

📘
Tenant Media

📘
Media MD5 Hash and File Size