{"_id":"59796d1140a3a2001f068cba","category":{"_id":"59796d1140a3a2001f068cb6","version":"59796d1140a3a2001f068cb4","project":"5669937dfc5abf2300afe7de","__v":0,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-12-23T15:52:27.836Z","from_sync":false,"order":1,"slug":"foo","title":"Core"},"user":"543532513513400800a144f4","parentDoc":null,"project":"5669937dfc5abf2300afe7de","version":{"_id":"59796d1140a3a2001f068cb4","project":"5669937dfc5abf2300afe7de","__v":2,"createdAt":"2017-07-27T04:33:21.278Z","releaseDate":"2017-07-27T04:33:21.278Z","categories":["59796d1140a3a2001f068cb5","59796d1140a3a2001f068cb6","59796d1140a3a2001f068cb7","59796d1140a3a2001f068cb8","5acb7bc606a2ce0003f28da4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"githubsync":"","__v":35,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-23T15:53:27.122Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n  \"id\": \"de62d33f-2bf6-4a03-af94-5e11b1807c23\",\n  \"scope\": \"ds7uej83l0s9o2\",\n  \"sourceUrl\": \"https://myvideos.com/myvideo.mp4\",\n  \"key\": \"https://myvideos.com/myvideo.mp4\",\n  \"filename\": \"My Video\",\n\t\"description\": \"This is a sample description for my video.\",\n  \"encrypt\": true,\n  \"allowHmacAuth\": true,\n  \"enableForensic\": true,\n  \"posterFrameUrl\": \"https://s3.amazonaws.com/videos.safestream.com/dujeme85jsu/4b3c7c70-4ccd-43e3-803e-60sdckr7294_large.jpg\",\n  \"posterFrameTimeCode\": 0,\n  \"status\": \"PENDING\",\n  \"bitRates\": [\n    \"4000k\"\n  ],\n  \"targetBitRate\": \"4000k\",\n  \"title\": \"\",\n  \"createdBy\": \"50825ae6-e3d7-4f8c-a38d-ce1632623805\",\n  \"createdOn\": 1477492322081,\n  \"updatedBy\": \"50825ae6-e3d7-4f8c-a38d-ce1632623805\",\n  \"updatedOn\": 1477492322081,\n  \"metadata\": [\n    {\n      \"id\": \"9955f051-b863-4f4d-9z51-37c7a8b9c59w\",\n      \"key\": \"some key\",\n      \"value\": \"best video\",\n      \"createdOn\": 1524495500507,\n      \"updatedOn\": 1524495500507\n    }\n\t]\n}"},{"code":"{ message: [Array of error messages] }","name":"","status":400,"language":"json"},{"code":"{\n  \"message\": \"A video with the key http://solarsystem.nasa.gov/docs/video/JPL-20151208-DAWNm-0001-180.mp4 already exists.\"\n}","language":"json","status":409},{"code":"{\n  \"message\": \"Access Denied\"\n}","language":"json","status":401},{"code":"{\n  \"message\": \"Access Denied\"\n}","status":403,"language":"json"}]},"settings":"","examples":{"codes":[{"language":"curl","code":"curl -X \"POST\" \"https://s2-api.safestream.com/2.0/videos\" \\\n     -H \"Content-Type: application/json\" \\\n     -H \"x-api-key: [[app:apiKey]]\" \\\n     -H \"x-api-client-id: [[app:apiClientId]]\" \\\n     -d $'{\n  \"sourceUrl\": \"https://d123mqjywc428u.cloudfront.net/562287910ZJXE/94405a32-0fd5-40d4-a94c-e01aacde88f0.mp4\",\n  \"key\": \"EPqrolKmdhpOLj57tSmWrjxpqlH5DxTl\",\n  \"allowHmacAuth\": true,\n  \"enableForensic\": true,\n  \"encrypt\": false,\n\t\"metadata\": [{\"key\": \"some key\", \"value\": \"best video\"}]\n}'\n"}]},"method":"post","auth":"required","params":[{"_id":"567aca9a76cd370d003c1255","ref":"","in":"body","required":true,"desc":"This is where SafeStream can find the video that you'd like to watermark.","default":"http://solarsystem.nasa.gov/docs/video/JPL-20151208-DAWNm-0001-180.mp4","type":"string","name":"sourceUrl"},{"_id":"567ace1c76cd370d003c1259","ref":"","in":"body","required":false,"desc":"Optional: Could be your internal asset id or reference id.","default":"my-internal-id","type":"string","name":"key"},{"_id":"56980d1c8d2a770d00d2fd5c","ref":"","in":"body","required":false,"desc":"Optional: Enable end-to-end encryption. Only use this if you are using the SafeStream default video player or if your own player supports AES decryption of HLS segments","default":"true","type":"boolean","name":"encrypt"},{"_id":"56980d1c8d2a770d00d2fd5b","ref":"","in":"body","required":false,"desc":"Optional: HMAC signatures with expiration. Disabling this in not recommended.","default":"true","type":"boolean","name":"allowhmacauth"},{"_id":"5810bec3fc38fd0f00ca1c8a","ref":"","in":"body","required":false,"desc":"Optional: Prepares this video for subsequent forensic watermarking. Recommended for high-value content that is longer than 10 mins. (NOTE:  This will lengthen the video ingest time)","default":"false","type":"boolean","name":"enableForensic"},{"_id":"599b5087aea509000fe91096","ref":"","in":"body","required":false,"desc":"Optional: Enables ingest result to be posted back to the specified url. See callback section below for more details, this covers sample responses, authentication, etc.","default":"https://my-domain/path/to/my/callback/listener","type":"string","name":"callbackUrl"},{"_id":"599b5087aea509000fe91095","ref":"","in":"body","required":false,"desc":"Optional: Name of the file.","default":"ceres-rotation.mp4","type":"string","name":"filename"},{"_id":"599b5087aea509000fe91094","ref":"","in":"body","required":false,"desc":"Optional: Description of the video. Max 1020 characters","default":"A description of the Ceres Rotation video","type":"string","name":"description"},{"_id":"5a256986b48f88001e7a646d","ref":"","in":"body","required":false,"desc":"Optional: The display name of the video","default":"","type":"string","name":"title"},{"_id":"5addf4ebf88e4100038eb8be","ref":"","in":"body","required":false,"desc":"Optional: Array of objects with key values. Keys must be unique.","default":"[{\"key\": \"some key\", \"value\": \"best video\"}]","type":"array_object","name":"metadata"}],"url":"/videos"},"isReference":true,"order":1,"body":"[block:api-header]\n{\n  \"type\": \"link\",\n  \"title\": \"SafeStream Ingest Overview\"\n}\n[/block]\nIngesting a video allows SafeStream to prepare the video for watermarking. The source of the file is discarded but SafeStream keeps a version of the file in its secure storage for use in watermarking video. Each video only needs to be ingested once.\n\nIngesting a video requires you to include an http reference to the video file. We recommend that you use our [Upload endpoint](doc:upload-a-video-for-ingest). Alternatively, SafeStream can ingest videos from any publicly accessible URL.\n\nThe initial file ingest will typically take between 25%-75% of the source video duration to complete. If forensic watermarking is enabled expect ingest to take longer. \n\nOnce SafeStream has ingested your video its ready to begin accepting on-demand watermarking requests. This means that you can use the ingested video to watermark videos on the fly in a fraction of the time of traditional watermarking methods. While the video ingest take ~25% of playback time, real-time watermarking can be completed in seconds.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Enabling Forensic Watermarking\",\n  \"body\": \"For videos that you'd like to apply a forensic watermark to you need to set the payload property \\\"enableForensic\\\" to true. See above for the full request payload documentation.\\n\\n***Embedding a forensic watermark in videos of less than 5 minutes in duration is not supported.*** \"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If a callback url was specified the final result will be posted back to the specified url. We will only attempt to post the results once.\\n\\n***Note we will only attempt to send results when the video is no longer in the `PENDING` state.***\\n\\nPlease see [here](getting-your-videos#video-encoding-status-overview) for encoding status overview.\\n\\nCallbackUrls can contain any query parameters you choose. E.g. an HMAC signature with an expiration parameter for authentication purposes. This prevents the need for unauthenticated resources on the system receiving the callback.\\n\\nWe recommend configuring the expiration of an HMAC signature to be double the video length, plus a 3-4 hour buffer time. This buffer times allows for the callback to succeed despite long running jobs and/or temporary backups in ingest processing. E.g. an expiration signature for a 1 hour video would be 2 (double the video length) + 3 which is 5 hours.\",\n  \"title\": \"If callback url is specified\"\n}\n[/block]\n##Sample Callback Response\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"  {\\n    \\\"id\\\": \\\"038b6df7-9f5f-4de7-9517-2c8c8be9d7bc\\\",\\n    \\\"scope\\\": \\\"ds7uej83l0s9o2\\\",\\n    \\\"sourceUrl\\\": \\\"http://safestream.com/short-2.mp4\\\",\\n    \\\"key\\\": \\\"short-2\\\",\\n    \\\"encrypt\\\": true,\\n    \\\"allowHmacAuth\\\": true,\\n    \\\"enableForensic\\\": true,\\n    \\\"posterFrameUrl\\\": \\\"https://s3.amazonaws.com/videos.safestream.com/sdcujr849ksi/4b3c7c70-4ccd-43e3-803e-605136fdsdv94_large.jpg\\\",\\n    \\\"posterFrameTimeCode\\\": 0,\\n    \\\"status\\\": \\\"INGESTED\\\",\\n    \\\"bitRates\\\": [\\n      \\\"4000k\\\"\\n    ],\\n    \\\"targetBitRate\\\": \\\"4000k\\\",\\n    \\\"groupId\\\": \\\"\\\",\\n    \\\"filename\\\": \\\"\\\",\\n    \\\"description\\\": \\\"\\\",\\n    \\\"title\\\": \\\"\\\",\\n    \\\"width\\\": 1280,\\n    \\\"height\\\": 720,\\n    \\\"createdBy\\\": \\\"c56e21ee-b0c6-4948-9e20-eab170758c3a\\\",\\n    \\\"createdOn\\\": 1492639705000,\\n    \\\"updatedBy\\\": \\\"c56e21ee-b0c6-4948-9e20-eab170758c3a\\\",\\n    \\\"updatedOn\\\": 1492640198000,\\n\\t\\t\\\"metadata\\\": []\\n  }\",\n      \"language\": \"json\",\n      \"name\": \"200 OK\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Width and Height\",\n  \"body\": \"We determine the width and height of a video during our ingest process. Until the video has a status of \\\"INGESTED\\\" the width and height will be 0.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Next: Learn how to watermark your videos\",\n  \"body\": \"[Watermarking Documentation](watermark-a-video)\"\n}\n[/block]","excerpt":"Make SafeStream aware of your video files","slug":"video","type":"endpoint","title":"Ingest a Video"}

postIngest a Video

Make SafeStream aware of your video files

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

sourceUrl:
required
stringhttp://solarsystem.nasa.gov/docs/video/JPL-20151208-DAWNm-0001-180.mp4
This is where SafeStream can find the video that you'd like to watermark.
key:
stringmy-internal-id
Optional: Could be your internal asset id or reference id.
encrypt:
booleantrue
Optional: Enable end-to-end encryption. Only use this if you are using the SafeStream default video player or if your own player supports AES decryption of HLS segments
allowhmacauth:
booleantrue
Optional: HMAC signatures with expiration. Disabling this in not recommended.
enableForensic:
booleanfalse
Optional: Prepares this video for subsequent forensic watermarking. Recommended for high-value content that is longer than 10 mins. (NOTE: This will lengthen the video ingest time)
callbackUrl:
stringhttps://my-domain/path/to/my/callback/listener
Optional: Enables ingest result to be posted back to the specified url. See callback section below for more details, this covers sample responses, authentication, etc.
filename:
stringceres-rotation.mp4
Optional: Name of the file.
description:
stringA description of the Ceres Rotation video
Optional: Description of the video. Max 1020 characters
title:
string
Optional: The display name of the video
metadata:
array of objects[{"key": "some key", "value": "best video"}]
Optional: Array of objects with key values. Keys must be unique.

Examples


Result Format


Documentation

[block:api-header] { "type": "link", "title": "SafeStream Ingest Overview" } [/block] Ingesting a video allows SafeStream to prepare the video for watermarking. The source of the file is discarded but SafeStream keeps a version of the file in its secure storage for use in watermarking video. Each video only needs to be ingested once. Ingesting a video requires you to include an http reference to the video file. We recommend that you use our [Upload endpoint](doc:upload-a-video-for-ingest). Alternatively, SafeStream can ingest videos from any publicly accessible URL. The initial file ingest will typically take between 25%-75% of the source video duration to complete. If forensic watermarking is enabled expect ingest to take longer. Once SafeStream has ingested your video its ready to begin accepting on-demand watermarking requests. This means that you can use the ingested video to watermark videos on the fly in a fraction of the time of traditional watermarking methods. While the video ingest take ~25% of playback time, real-time watermarking can be completed in seconds. [block:callout] { "type": "warning", "title": "Enabling Forensic Watermarking", "body": "For videos that you'd like to apply a forensic watermark to you need to set the payload property \"enableForensic\" to true. See above for the full request payload documentation.\n\n***Embedding a forensic watermark in videos of less than 5 minutes in duration is not supported.*** " } [/block] [block:callout] { "type": "info", "body": "If a callback url was specified the final result will be posted back to the specified url. We will only attempt to post the results once.\n\n***Note we will only attempt to send results when the video is no longer in the `PENDING` state.***\n\nPlease see [here](getting-your-videos#video-encoding-status-overview) for encoding status overview.\n\nCallbackUrls can contain any query parameters you choose. E.g. an HMAC signature with an expiration parameter for authentication purposes. This prevents the need for unauthenticated resources on the system receiving the callback.\n\nWe recommend configuring the expiration of an HMAC signature to be double the video length, plus a 3-4 hour buffer time. This buffer times allows for the callback to succeed despite long running jobs and/or temporary backups in ingest processing. E.g. an expiration signature for a 1 hour video would be 2 (double the video length) + 3 which is 5 hours.", "title": "If callback url is specified" } [/block] ##Sample Callback Response [block:code] { "codes": [ { "code": " {\n \"id\": \"038b6df7-9f5f-4de7-9517-2c8c8be9d7bc\",\n \"scope\": \"ds7uej83l0s9o2\",\n \"sourceUrl\": \"http://safestream.com/short-2.mp4\",\n \"key\": \"short-2\",\n \"encrypt\": true,\n \"allowHmacAuth\": true,\n \"enableForensic\": true,\n \"posterFrameUrl\": \"https://s3.amazonaws.com/videos.safestream.com/sdcujr849ksi/4b3c7c70-4ccd-43e3-803e-605136fdsdv94_large.jpg\",\n \"posterFrameTimeCode\": 0,\n \"status\": \"INGESTED\",\n \"bitRates\": [\n \"4000k\"\n ],\n \"targetBitRate\": \"4000k\",\n \"groupId\": \"\",\n \"filename\": \"\",\n \"description\": \"\",\n \"title\": \"\",\n \"width\": 1280,\n \"height\": 720,\n \"createdBy\": \"c56e21ee-b0c6-4948-9e20-eab170758c3a\",\n \"createdOn\": 1492639705000,\n \"updatedBy\": \"c56e21ee-b0c6-4948-9e20-eab170758c3a\",\n \"updatedOn\": 1492640198000,\n\t\t\"metadata\": []\n }", "language": "json", "name": "200 OK" } ] } [/block] [block:callout] { "type": "warning", "title": "Width and Height", "body": "We determine the width and height of a video during our ingest process. Until the video has a status of \"INGESTED\" the width and height will be 0." } [/block] [block:callout] { "type": "success", "title": "Next: Learn how to watermark your videos", "body": "[Watermarking Documentation](watermark-a-video)" } [/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 }}