{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/watermark","auth":"required","settings":"","results":{"codes":[{"status":200,"language":"json","code":"{\n  \"status\": \"READY\",\n  \"containers\": {\n    \"href\": \"https://api.safestream.com/player/1.0/?href=https%3A%2F%2Fsafestream-api.shiftplatform.io%2F1.0%2Fwatermark%2F1741b0ce-71d7-439e-a52b-f1dc61ee7f0c%2F42d9f235443bdea89139a3243594389abe5f9b46%3Fcontainers%3Dmp4%26containers%3Dm3u8%26expiration%3D1478877353611%26signature%3DaRO9RIF1uuhXiss3lKMxIrUqCjI%253D\",\n    \"m3u8\": \"https://api.safestream.com/1.0/watermark/1741b0ce-71d7-439e-a52b-f1dc61ee7f0c/42d9f235443bdea89139a3243594389abe5f9b46/video.m3u8?x=y&expiration=1478877353611&signature=Wgbr4AKZFCzo877Nz78Jf84TCFo%3D\"\n  },\n  \"href\": \"https://api.safestream.com/1.0/watermark/1741b0ce-71d7-439e-a52b-f1dc61ee7f0c/42d9f235443bdea89139a3243594389abe5f9b46?containers=mp4&containers=m3u8&expiration=1478877353611&signature=aRO9RIF1uuhXiss3lKMxIrUqCjI%3D\"\n}","name":""},{"status":400,"language":"json","code":"{ message: [Array of error messages] }","name":""},{"status":401,"language":"json","code":"{\n  \"message\": \"Access Denied\"\n}"},{"code":"{\n  \"message\": \"Access Denied\"\n}","status":403,"language":"json"}]},"method":"post","examples":{"codes":[{"language":"curl","code":"curl -X \"POST\" \"https://s2-api.safestream.com/2.0/watermark\" \\\n     -H \"Content-Type: application/json\" \\\n     -H \"x-api-key: [[app:apiKey]]\" \\\n     -H \"x-api-client-id: [[app:apiClientId]]\" \\\n     -d $'{\n  \"videoId\": \"831623c0-72ff-4a91-aa6b-323d7ef2ab9a\",\n  \"settings\": [\n     {\n      \"content\": \"Any publically accessible image url\",\n      \"type\": \"IMAGE\",\n      \"x\":0.2,\n      \"y\":0.2,\n      \"align\": \"LEFT\",\n      \"verticalAlign\": \"middle\",\n      }\n  ],\n  \"viewLimit\" : 5,\n  \"expiration\" : 1523640477 //Friday, April 13, 2018 5:27:57 PM. This should be updated to a date in the future.\n}'\n"}]},"params":[{"name":"key","type":"string","default":"","desc":"Optional: The key of the video that you'd like to watermark.","required":false,"in":"body","ref":"","_id":"568a7b50bf86800d00fe310c"},{"name":"videoId","type":"string","default":"","desc":"Optional: Use the ID SafeStream assigned to this asset during ingest","required":false,"in":"body","ref":"","_id":"568a7bd18360c00d00a0e72b"},{"name":"settings","type":"array_object","default":"{\"content\": \"Joe Smith\",                 \"type\": \"IMAGE\",                \"align\":\"center\",                 \"verticalAlign\":\"middle\"             }","desc":"An array of watermark settings to be applied to the video that should be watermarked. See below for details on the watermark setting properties.","required":false,"in":"body","ref":"","_id":"568a7c40d4e2360d0098002b"},{"name":"containers","type":"array_string","default":"[\"m3u8\",\"mp4\"]","desc":"Defaults to m3u8 for HLS playback but also supports MP4 to specifically request a watermarked mp4 video for download.","required":false,"in":"body","ref":"","_id":"58248f95d90fa027009b2597"},{"name":"settingsTemplateMapping","type":"object","default":"\"settingsTemplateMapping\": {         \"id\": \"74fc00c8-847d-4631-94a4-f4ac7d1e4748\",         \"mappings\": {             \"name\": \"User Name\"         }     }","desc":"A mapping object that references an existing watermark template and maps values to placeholders.","required":false,"in":"body","ref":"","_id":"582494658d0ac71b00780e89"},{"name":"viewLimit","type":"int","default":"null","desc":"The max number of times the POST /watermark call can be made for a watermarked video. Watermarked video refers to a specific video with specific watermark settings. For security purposes, viewLimit can only be set on the initial request for watermarking a video.","required":false,"in":"body","ref":"","_id":"5ad0e908f672e80003ad5c11"},{"name":"expiration","type":"long","default":"null","desc":"Epoch time in SECONDS for a future date when the POST /watermark endpoint will no longer return a valid M3U8 for a given watermarked video. Watermarked video refers to a specific video with specific watermark settings. For security purposes, expiration can only be set on the initial request for watermarking a video.","required":false,"in":"body","ref":"","_id":"5ad0e908f672e80003ad5c10"}]},"next":{"description":"","pages":[]},"title":"Watermark a Video with an Image","type":"endpoint","slug":"watermark-a-video-with-an-image","excerpt":"Add a visual or forensic watermark to you video","body":"[block:api-header]\n{\n  \"title\": \"Watermark Expiration Overview\"\n}\n[/block]\nExpiration:\n- This does not affect the expiration on AWS signed urls returned from the POST /watermark endpoint.\n- This only applies to the specified watermarked video.\n- Expiration must be set on the initial watermark request made for a video with specified watermark settings.\n- Once a video has been watermarked with specified watermark settings, the expiration property cannot be updated.\n- Changing the watermark settings even in the slightest way will create a new watermark for a video, which would allow you to set a new expiration. \nExample: If you are using a template to watermark videos, you could change the shadowOpacity from .33 -> .34 and that would allow you to set the expiration on the new watermarked video.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Watermarking Overview\"\n}\n[/block]\nOnce a video has been [ingested](doc:video), you can request a watermark for the video using this endpoint. At it's simplest you just need the ID or KEY of the video and the text that you'd like you have as your watermark. SafeStream will locate the video that you've already ingested and it will apply the watermark to the file.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"key\\\": \\\"my-internal-id\\\",\\n    \\\"settings\\\": [\\n           {\\n        \\\"content\\\": \\\"https://s3-us-west-1.amazonaws.com/watermark-api/stormtrooper.jpg\\\",\\n      \\\"type\\\": \\\"IMAGE\\\",\\n      \\\"x\\\":0.2,\\n      \\\"y\\\":0.2,\\n      \\\"align\\\": \\\"LEFT\\\",\\n      \\\"verticalAlign\\\": \\\"middle\\\",\\n      }\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","updates":[],"order":4,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"59a6f06ba675c0000fbaa4a9","project":"5669937dfc5abf2300afe7de","version":{"version":"2.0","version_clean":"2.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["59796d1140a3a2001f068cb5","59796d1140a3a2001f068cb6","59796d1140a3a2001f068cb7","59796d1140a3a2001f068cb8","5acb7bc606a2ce0003f28da4"],"_id":"59796d1140a3a2001f068cb4","project":"5669937dfc5abf2300afe7de","createdAt":"2017-07-27T04:33:21.278Z","releaseDate":"2017-07-27T04:33:21.278Z","__v":2},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Core","slug":"foo","order":1,"from_sync":false,"reference":true,"_id":"59796d1140a3a2001f068cb6","version":"59796d1140a3a2001f068cb4","project":"5669937dfc5abf2300afe7de","createdAt":"2015-12-23T15:52:27.836Z","__v":0},"user":"599b4786eac604000fedaf43","createdAt":"2017-08-30T17:05:47.092Z","githubsync":"","__v":12,"parentDoc":null}

postWatermark a Video with an Image

Add a visual or forensic watermark to you video

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

key:
string
Optional: The key of the video that you'd like to watermark.
videoId:
string
Optional: Use the ID SafeStream assigned to this asset during ingest
settings:
array of objects{"content": "Joe Smith", "type": "IMAGE", "align":"center", "verticalAlign":"middle" }
An array of watermark settings to be applied to the video that should be watermarked. See below for details on the watermark setting properties.
containers:
array of strings["m3u8","mp4"]
Defaults to m3u8 for HLS playback but also supports MP4 to specifically request a watermarked mp4 video for download.
settingsTemplateMapping:
object"settingsTemplateMapping": { "id": "74fc00c8-847d-4631-94a4-f4ac7d1e4748", "mappings": { "name": "User Name" } }
A mapping object that references an existing watermark template and maps values to placeholders.
viewLimit:
integernull
The max number of times the POST /watermark call can be made for a watermarked video. Watermarked video refers to a specific video with specific watermark settings. For security purposes, viewLimit can only be set on the initial request for watermarking a video.
expiration:
longnull
Epoch time in SECONDS for a future date when the POST /watermark endpoint will no longer return a valid M3U8 for a given watermarked video. Watermarked video refers to a specific video with specific watermark settings. For security purposes, expiration can only be set on the initial request for watermarking a video.

Examples


Result Format


Documentation

[block:api-header] { "title": "Watermark Expiration Overview" } [/block] Expiration: - This does not affect the expiration on AWS signed urls returned from the POST /watermark endpoint. - This only applies to the specified watermarked video. - Expiration must be set on the initial watermark request made for a video with specified watermark settings. - Once a video has been watermarked with specified watermark settings, the expiration property cannot be updated. - Changing the watermark settings even in the slightest way will create a new watermark for a video, which would allow you to set a new expiration. Example: If you are using a template to watermark videos, you could change the shadowOpacity from .33 -> .34 and that would allow you to set the expiration on the new watermarked video. [block:api-header] { "type": "basic", "title": "Watermarking Overview" } [/block] Once a video has been [ingested](doc:video), you can request a watermark for the video using this endpoint. At it's simplest you just need the ID or KEY of the video and the text that you'd like you have as your watermark. SafeStream will locate the video that you've already ingested and it will apply the watermark to the file. [block:code] { "codes": [ { "code": "{\n \"key\": \"my-internal-id\",\n \"settings\": [\n {\n \"content\": \"https://s3-us-west-1.amazonaws.com/watermark-api/stormtrooper.jpg\",\n \"type\": \"IMAGE\",\n \"x\":0.2,\n \"y\":0.2,\n \"align\": \"LEFT\",\n \"verticalAlign\": \"middle\",\n }\n ]\n}", "language": "json" } ] } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}