Package: shotstack-sdk
Shotstack Python SDKPython SDK for the ShotstackPython video editorand cloud video editing API.Shotstack is a cloud based video editing platform that enables the editing of videos using code.The platform uses an API and a JSON format for specifying how videos should be edited and what assets and titles should be used.A server based render farm takes care of rendering the videos allowing multiple videos to be created simultaneously.For examples of how to use the SDK to create videos using code checkout the Python demo repo:https://github.com/shotstack/python-demosContentsUsing the Python SDKInstallationVideo EditingVideo Editing ExampleStatus Check ExampleSave a Template ExampleRender a Template ExampleVideo Editing SchemasEditArguments:TimelineSoundtrackFontTrackClipVideoAssetImageAssetTitleAssetHtmlAssetAudioAssetLumaAssetTransitionOffsetCropTransformationRotateTransformationSkewTransformationFlipTransformationMergeFieldTemplate SchemasTemplateTemplateRenderOutput SchemasOutputSizeRangePosterThumbnailDestinationsShotstackDestinationMuxDestinationMuxDestinationOptionsS3DestinationS3DestinationOptionsRender Response SchemasQueuedResponseQueuedResponseDataRenderResponseRenderResponseDataTemplate Response SchemasTemplateResponseTemplateResponseDataTemplateDataResponseTemplateDataResponseDataTemplateListResponseTemplateListResponseDataTemplateListResponseItemInspecting MediaProbe ExampleProbe SchemasProbeResponseManaging AssetsAssets by Render ID ExampleAssets by Asset ID ExampleAsset SchemasAssetResponseAssetRenderResponseAssetResponseDataAssetResponseAttributesAPI Documentation and GuidesUsing the Python SDKInstallationpipinstallshotstack-sdkVideo EditingThe Shotstack SDK enables programmatic video editing via the Edit APIrenderendpoint. Prepare JSON edits using the
provided schema classes andPOSTto the API for rendering.Video Editing ExampleThe example below trims the start of a video clip and plays it for 8 seconds. The edit is prepared using the SDK models
and then sent to the API for rendering.importshotstack_sdkasshotstackfromshotstack_sdk.apiimportedit_apifromshotstack_sdk.model.video_assetimportVideoAssetfromshotstack_sdk.model.clipimportClipfromshotstack_sdk.model.trackimportTrackfromshotstack_sdk.model.timelineimportTimelinefromshotstack_sdk.model.outputimportOutputfromshotstack_sdk.model.editimportEdithost='https://api.shotstack.io/stage'configuration=shotstack.Configuration(host=host)configuration.api_key['DeveloperKey']='H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'withshotstack.ApiClient(configuration)asapi_client:api_instance=edit_api.EditApi(api_client)video_asset=VideoAsset(src='https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/skater.hd.mp4',trim=3.0)video_clip=Clip(asset=video_asset,start=0.0,length=8.0)track=Track(clips=[video_clip])timeline=Timeline(tracks=[track])timeline['tracks']=[another_track]output=Output(format='mp4',resolution='sd')edit=Edit(timeline=timeline,output=output)try:api_response=api_instance.post_render(edit)print(f"{api_response['response']['id']}")exceptExceptionase:print(f"Unable to resolve API call:{e}")Status Check ExampleThe example request below can be called a few seconds after the render above is posted. It will return the status of
the render, which can take several seconds to process.importshotstack_sdkasshotstackfromshotstack_sdk.apiimportedit_apihost='https://api.shotstack.io/stage'configuration=shotstack.Configuration(host=host)configuration.api_key['DeveloperKey']='H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'withshotstack.ApiClient(configuration)asapi_client:api_instance=edit_api.EditApi(api_client)id='75143ec6-4b72-46f8-a67a-fd7284546935'try:api_response=api_instance.get_render(id,data=False,merged=True)status=api_response['response']['status']ifstatus=='done':print(f"{api_response['response']['url']}")exceptExceptionase:print(f"Unable to resolve API call:{e}")Save a Template ExampleThe example below uses the Edit we create in theVideo Editing Exampleand saves it as a
template. The template can be rendered at a later date and can include placeholders. Placeholders can be replaced
when rendered usingmerge fields.This example uses a placeholder for the video src (URL), trim (TRIM), and length (LENGTH) to allow you to trim any video
using a template.importshotstack_sdkasshotstackimportosfromshotstack_sdk.apiimportedit_apifromshotstack_sdk.model.video_assetimportVideoAssetfromshotstack_sdk.model.clipimportClipfromshotstack_sdk.model.trackimportTrackfromshotstack_sdk.model.timelineimportTimelinefromshotstack_sdk.model.outputimportOutputfromshotstack_sdk.model.editimportEditfromshotstack_sdk.model.templateimportTemplatehost="https://api.shotstack.io/stage"configuration=shotstack.Configuration(host=host)configuration.api_key['DeveloperKey']=os.getenv("SHOTSTACK_KEY")withshotstack.ApiClient(configuration)asapi_client:api_instance=edit_api.EditApi(api_client)video_asset=VideoAsset(src='{{ URL }}',trim='{{ TRIM }}')video_clip=Clip(asset=video_asset,start=0.0,length='{{ LENGTH }}')track=Track(clips=[video_clip])timeline=Timeline(background='#000000',tracks=[track])output=Output(format='mp4',resolution='sd')edit=Edit(timeline=timeline,output=output)template=Template(name='Trim Template',template=edit)try:api_response=api_instance.post_template(template)print(f"{api_response['response']['id']}")exceptExceptionase:print(f"Unable to resolve API call:{e}")Render a Template ExampleThe example below renders the template we created in the previous example and includes merge fields that will replace
the placeholders. Once submitted use the returned render ID and call theStatus Check Exampleto get the render progress.importshotstack_sdkasshotstackimportosfromshotstack_sdk.apiimportedit_apifromshotstack_sdk.model.template_renderimportTemplateRenderfromshotstack_sdk.model.merge_fieldimportMergeFieldhost="https://api.shotstack.io/stage"configuration=shotstack.Configuration(host=host)configuration.api_key['DeveloperKey']=os.getenv("SHOTSTACK_KEY")withshotstack.ApiClient(configuration)asapi_client:api_instance=edit_api.EditApi(api_client)merge_field_url=MergeField(find='URL',replace='https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/footage/skater.hd.mp4')merge_field_trim=MergeField(find='TRIM',replace=3)merge_field_length=MergeField(find='LENGTH',replace=6)template=TemplateRender(id=id,merge=[merge_field_url,merge_field_trim,merge_field_length])try:api_response=api_instance.post_template_render(template)print(f"{api_response['response']['id']}")exceptExceptionase:print(f"Unable to resolve API call:{e}")Video Editing SchemasThe following schemas are used to prepare a video edit.EditAnEditdefines the arrangement of a video on a timeline, an audio edit or an image design and the output format.Example:fromshotstack_sdk.model.editimportEditedit=Edit(timeline=timeline,output=output,merge=merge,callback="https://my-server.com/callback.php",disk="local")Arguments:ArgumentTypeDescriptionRequiredtimelineTimelineA timeline represents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to as clips which are placed along the track at specific starting point and lasting for a specific amount of time.-outputOutputThe output format, render range and type of media to generate.YmergeMergeField[]An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder{{NAME}}and replace it with the valueJane.-callbackstringAn optional webhook callback URL used to receive status notifications when a render completes or fails. Seewebhooksfor  more details.-diskstring(Deprecated)The disk type to use for storing footage and asset for each render. Seedisk typesfor more details. [default tolocal]local- optimized for high speed rendering with up to 512MB storagemount- optimized for larger file sizes and longer videos with 5GB for source footage and 512MB for output render-TimelineATimelinerepresents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to
as clips which are placed along the track at specific starting point and lasting for a specific amount of time.Example:fromshotstack_sdk.model.timelineimportTimelinetimeline=Timeline(soundtrack=soundtrack,background='#000000',fonts=fonts,tracks=tracks,cache=True,)Arguments:ArgumentTypeDescriptionRequiredsoundtrackSoundtrackA music or audio soundtrack file in mp3 format.-backgroundstringA hexadecimal value for the timeline background colour. Defaults to#000000(black).-fontsFont[]An array of custom fonts to be downloaded for use by the HTML assets.-tracks[TrackA timeline consists of an array of tracks, each track containing clips. Tracks are layered on top of each other in the same order they are added to the array with the top most track layered over the top of those below it. Ensure that a track containing titles is the top most track so that it is displayed above videos and images.YcacheboolDisable the caching of ingested source footage and assets. Seecachingfor more details. [default toTrue]-SoundtrackA music or audio file in mp3 format that plays for the duration of the rendered video or the length of the audio file, which ever is shortest.Example:fromshotstack_sdk.model.soundtrackimportSoundtracksoundtrack=Soundtrack(src='https://s3-ap-southeast-2.amazonaws.com/shotstack-assets/music/disco.mp3',effect='fadeIn',volume=1.0)Arguments:ArgumentTypeDescriptionRequiredsrcstringThe URL of the mp3 audio file. The URL must be publicly accessible or include credentials.YeffectstringThe effect to apply to the audio filefadeIn- fade volume in onlyfadeOut- fade volume out onlyfadeInFadeOut- fade volume in and out-volumefloatSet the volume for the soundtrack between 0 and 1 where 0 is muted and 1 is full volume (defaults to1).-FontDownload a custom font to use with the HTML asset type, using the font name in the CSS or font tag. See ourcustom fontsgetting started guide for more details.Example:fromshotstack_sdk.model.fontimportFontfont=Font(src='https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/fonts/OpenSans-Regular.ttf')Arguments:ArgumentTypeDescriptionRequiredsrcstringThe URL of the font file. The URL must be publicly accessible or include credentials.YTrackA track contains an array of clips. Tracks are layered on top of each other in the order in the array. The top most track will render on top of those below it.Example:fromshotstack_sdk.model.trackimportTracktrack=Track(clips=clips)Arguments:ArgumentTypeDescriptionRequiredclipsClip[]An array of Clips comprising of TitleClip, ImageClip or VideoClip.YClipAClipis a container for a specific type of asset, i.e. a title, image, video, audio or html. You use a Clip to define when an asset will display on the timeline, how long it will play for and transitions, filters and effects to apply to it.Example:fromshotstack_sdk.model.clipimportClipclip=Clip(asset=asset,start=2.0,length=5.0,fit='crop',scale=0.0,position='center',offset=offset,transition=transition,effect='zoomIn',filter='greyscale',opacity=1.0,transform=transform,)Arguments:ArgumentTypeDescriptionRequiredassetassetThe type of asset to display for the duration of this Clip. Value must be one of:VideoAssetImageAssetTitleAssetHtmlAssetAudioAssetLumaAssetYstartfloatThe start position of the Clip on the timeline, in seconds.YlengthfloatThe length, in seconds, the Clip should play for.Yfitstring fitSet how the asset should be scaled to fit the viewport using one of the following options [default tocrop]:cover- stretch the asset to fill the viewport without maintaining the aspect ratio.contain- fit the entire asset within the viewport while maintaining the original aspect ratio.crop- scale the asset to fill the viewport while maintaining the aspect ratio. The asset will be cropped if it exceeds the bounds of the viewport.none- preserves the original asset dimensions and does not apply any scaling.-scalefloatScale the asset to a fraction of the viewport size - i.e. ting the scale to 0.5 will scale asset to half the size of the viewport. This is useful for picture-in-picture video and  scaling images such as logos and watermarks.-positionstringPlace the asset in one of nine predefined positions of the viewport. This is most effective for when the asset is scaled and you want to position the element to a specific position [default tocenter].top- top (center)topRight- top rightright- right (center)bottomRight- bottom rightbottom- bottom (center)bottomLeft- bottom leftleft- left (center)topLeft- top leftcenter- center-offsetOffsetOffset the location of the asset relative to its position on the viewport. The offset distance is relative to the width of the viewport - for example an x offset of 0.5 will move the asset half the viewport width to the right.-transitionTransitionIn and out transitions for a clip - i.e. fade in and fade out-effectstringA motion effect to apply to the Clip.zoomIn- slow zoom inzoomOut- slow zoom outslideLeft- slow slide (pan) leftslideRight- slow slide (pan) rightslideUp- slow slide (pan) upslideDown- slow slide (pan) downThe motion effect speed can also be controlled by appendingFastorSlowto the effect, e.g.zoomInFastorslideRightSlow.-filterstringA filter effect to apply to the Clip.boost- boost contrast and saturationcontrast- increase contrastdarken- darken the scenegreyscale- remove colourlighten- lighten the scenemuted- reduce saturation and contrastnegative- invert colors-opacityfloats the opacity of the Clip where 1 is opaque and 0 is transparent. [default to1]-transformTransformationA transformation lets you modify the visual properties of a clip. Available transformations areRotateTransformation,SkewTransformationandFlipTransformation. Transformations can be combined to create interesting new shapes and effects.-VideoAssetTheVideoAssetis used to create video sequences from video files. The src must be a publicly accessible URL to a video
resource such as an mp4 file.Example:fromshotstack_sdk.model.video_assetimportVideoAssetvideo_asset=VideoAsset(src='https://shotstack-assets.s3.aws.com/mountain.mp4',trim=5.0,volume=0.5,volumeEffect='fadeIn'crop=crop)Arguments:ArgumentTypeDescriptionRequiredsrcstringThe video source URL. The URL must be publicly accessible or include credentials.YtrimfloatThe start trim point of the video clip, in seconds (defaults to 0). Videos will start from the in trim point. The video will play until the file ends or the Clip length is reached.-volumefloatSet the volume for the video clip between 0 and 1 where 0 is muted and 1 is full volume (defaults to 0).-volumeEffecteffectThe volume effect to apply to the video asset.fadeIn- fade volume in onlyfadeOut- fade volume out onlyfadeInFadeOut- fade volume in and out-cropCropCrop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e. a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.-ImageAssetTheImageAssetis used to create video from images to compose an image. The src must be a publicly accessible URL to an image resource such as a jpg or png file.Example:fromshotstack_sdk.model.image_assetimportImageAssetimage_asset=ImageAsset(src='https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/images/earth.jpg',crop=crop)Arguments:ArgumentTypeDescriptionRequiredsrcstringThe image source URL. The URL must be publicly accessible or include credentials.YcropCropCrop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e. a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top by quarter of the asset.-TitleAssetTheTitleAssetclip type lets you create video titles from a text string and apply styling and positioning.Example:fromshotstack_sdk.model.title_assetimportTitleAssettitle_asset=TitleAsset(text='My Title',style='minimal',color='#ffffff',size='medium',background='#000000',position='center',offset=offset)Arguments:ArgumentTypeDescriptionRequiredtextstringThe title text string.YstylestringUses a preset to apply font properties and styling to the title.minimalblockbustervoguesketchyskinnychunkchunkLightmarkerfuturesubtitle-colorstringSet the text color using hexadecimal color notation. Transparency is supported by ting the first two characters of the hex string (opposite to HTML),  i.e. #80ffffff will be white with  50% transparency [default to#ffffff].-sizestringSet the relative size of the text using predefined sizes from xx-small to xx-large [default to 'medium'].xx-smallx-smallsmallmediumlargex-largexx-large-backgroundstringApply a background color behind the text. Set the text color using hexadecimal color notation. Transparency is supported by ting the first two characters of the hex string (opposite to HTML),  i.e. #80ffffff will be white with 50% transparency. Omit to use transparent background.-positionstringPlace the title in one of nine predefined positions of the viewport [default tocenter.top- top (center)topRight- top rightright- right (center)bottomRight- bottom rightbottom- bottom (center)bottomLeft- bottom leftleft- left (center)topLeft- top leftcenter- center-offsetOffsetOffset the location of the title relative to its position on the screen.-HtmlAssetTheHtmlAssetclip type lets you create text based layout and formatting using HTML and CSS. You can also set the height and width of a bounding box for the HTML content to sit within. Text and elements will wrap within the bounding box.Example:fromshotstack_sdk.model.html_assetimportHtmlAssethtml_asset=HtmlAsset(html='<p>Hello <b>World</b></p>',css='p { color: #ffffff; } b { color: #ffff00; }',width=400,height=200,background='transparent',position='center')Arguments:ArgumentTypeDescriptionRequiredhtmlstringThe HTML text string. See list ofsupported HTML tags.YcssstringThe CSS text string to apply styling to the HTML. See list ofsupport CSS properties.-widthintSet the width of the HTML asset bounding box in pixels. Text will wrap to fill the bounding box.-heightintSet the height of the HTML asset bounding box in pixels. Text and elements will be masked if they exceed the  height of the bounding box.-backgroundstringApply a background color behind the HTML bounding box using. Set the text color using hexadecimal  color notation. Transparency is supported by ting the first two characters of the hex string  (opposite to HTML), i.e. #80ffffff will be white with 80% transparency [default totransparent].-positionstringPlace the HTML in one of nine predefined positions within the HTML area [default tocenter].top- top (center)topRight- top rightright- right (center)bottomRight- bottom rightbottom- bottom (center)bottomLeft- bottom leftleft- left (center)topLeft- top leftcenter- center-AudioAssetTheAudioAssetis used to add sound effects and audio at specific intervals on the timeline. The src must be a
publicly accessible URL to an audio resource such as an mp3 file.Example:fromshotstack_sdk.model.audio_assetimportAudioAssetaudio_asset=AudioAsset(src='https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/unminus/lit.mp3',trim=2.0,volume=0.5,effect='fadeInFadeOut')Arguments:ArgumentTypeDescriptionRequiredsrcstringThe audio source URL. The URL must be publicly accessible or include credentials.YtrimfloatThe start trim point of the audio clip, in seconds (defaults to 0). Audio will start from the trim point. The audio will play until the file ends or the Clip length is reached.-volumefloatSet the volume for the audio clip between 0 and 1 where 0 is muted and 1 is full volume (defaults to 1).-effectstringThe effect to apply to the audio asset:fadeIn- fade volume in onlyfadeOut- fade volume out onlyfadeInFadeOut- fade volume in and out-LumaAssetTheLumaAssetis used to create luma matte masks, transitions and effects between other assets. A luma matte is a grey scale image or animated video where the black areas are transparent and the white areas solid. The luma matte animation
should be provided as an mp4 video file. The src must be a publicly accessible URL to the file.Example:fromshotstack_sdk.model.luma_assetimportLumaAssetluma_asset=LumaAsset(src='https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/examples/luma-mattes/paint-left.mp4',trim=5.0)Arguments:ArgumentTypeDescriptionRequiredsrcstringThe luma matte source URL. The URL must be publicly accessible or include credentials.YtrimfloatThe start trim point of the luma matte clip, in seconds (defaults to 0). Videos will start from the in trim point. A luma matte video will play until the file ends or the Clip length is reached.-TransitionTheTransitionclip type lets you define in and out transitions for a clip - i.e. fade in and fade outExample:fromshotstack_sdk.model.transitionimportTransitiontransition=Transition(_in='fade',out='fade')Arguments:ArgumentTypeDescriptionRequiredinstringThe transition in. Available transitions are:fade- fade inreveal- reveal from left to rightwipeLeft- fade across screen to the leftwipeRight- fade across screen to the rightslideLeft- move slightly left and fade inslideRight- move slightly right and fade inslideUp- move slightly up and fade inslideDown- move slightly down and fade incarouselLeft- slide in from right to leftcarouselRight- slide in from left to rightcarouselUp- slide in from bottom to topcarouselDown- slide in from top to bottomshuffleTopRight- rotate in from top rightshuffleRightTop- rotate in from right topshuffleRightBottom- rotate in from right bottomshuffleBottomRight- rotate in from bottom rightshuffleBottomLeft- rotate in from bottom leftshuffleLeftBottom- rotate in from left bottomshuffleLeftTop- rotate in from left topshuffleTopLeft- rotate in from top leftzoom- fast zoom inThe transition speed can also be controlled by appendingFastorSlowto the transition, e.g.fadeFastorCarouselLeftSlow.-outstringThe transition out. Available transitions are:fade- fade outreveal- reveal from right to leftwipeLeft- fade across screen to the leftwipeRight- fade across screen to the rightslideLeft- move slightly left and fade outslideRight- move slightly right and fade outslideUp- move slightly up and fade outslideDown- move slightly down and fade outcarouselLeft- slide out from right to leftcarouselRight- slide out from left to rightcarouselUp- slide out from bottom to topcarouselDown- slide out from top  to bottomshuffleTopRight- rotate out from top rightshuffleRightTop- rotate out from right topshuffleRightBottom- rotate out from right bottomshuffleBottomRight- rotate out from bottom rightshuffleBottomLeft- rotate out from bottom leftshuffleLeftBottom- rotate out from left bottomshuffleLeftTop- rotate out from left topshuffleTopLeft- rotate out from top leftzoom- fast zoom outThe transition speed can also be controlled by appendingFastorSlowto the transition, e.g.fadeFastorCarouselLeftSlow.-OffsetOffsets the position of an asset horizontally or vertically by a relative distance.Example:fromshotstack_sdk.model.offsetimportOffsetoffset=Offset(x=0.1,y=-0.2)Arguments:ArgumentTypeDescriptionRequiredxfloatOffset an asset on the horizontal axis (left or right), range varies from -10 to 10. Positive numbers move the asset right, negative left. For all asset except titles the distance moved is relative to the width  of the viewport - i.e. an X offset of 0.5 will move the asset half the  screen width to the right. [default to0]-yfloatOffset an asset on the vertical axis (up or down), range varies from -10 to 10. Positive numbers move the asset up, negative down. For all asset except titles the distance moved is relative to the height of the viewport - i.e. an Y offset of 0.5 will move the asset up half the screen height. [default to0]-CropCrop the sides of an asset by a relative amount. The size of the crop is specified using a scale between 0 and 1, relative to the screen width - i.e a left crop of 0.5 will crop half of the asset from the left, a top crop of 0.25 will crop the top
by quarter of the asset.Example:fromshotstack_sdk.model.cropimportCropcrop=Crop(top=0.15,bottom=0.15,left=0.0,right=0.0)Arguments:ArgumentTypeDescriptionRequiredtopfloatCrop from the top of the asset-bottomfloatCrop from the bottom of the asset-leftfloatCrop from the left of the asset-rightfloatCrop from the right of the asset-TransformationApply one or more transformations to a clip.Transformationsalter the visual properties of a clip and can be combined to create new shapes and effects.Example:fromshotstack_sdk.model.transformationimportTransformationtransformation=Transformation(rotate=rotate,skew=skew,flip=flip)Arguments:ArgumentTypeDescriptionRequiredrotateRotateTransformationRotate a clip by the specified angle in degrees. Rotation origin is set based on the clipsposition.-skewSkewTransformationSkew a clip so its edges are sheared at an angle. Use values between 0 and 3. Over 3 the clip will be skewed almost flat.-flipFlipTransformationFlip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane.-RotateTransformationRotate a clip by the specified angle in degrees. Rotation origin is set based on the clipsposition.Example:fromshotstack_sdk.model.rotate_transformationimportRotateTransformationrotate_transformation=RotateTransformation(angle=45.0)Arguments:ArgumentTypeDescriptionRequiredangleintThe angle to rotate the clip. Can be 0 to 360, or 0 to -360. Using a positive number rotates the clip clockwise, negative numbers counter-clockwise.-SkewTransformationSkew a clip so its edges are sheared at an angle. Use values between 0 and 3. Over 3 the clip will be skewed almost flat.Example:fromshotstack_sdk.model.skew_transformationimportSkewTransformationskew_transformation=SkewTransformation(x=0.5,y=0.5)Arguments:ArgumentTypeDescriptionRequiredxfloatSkew the clip along it's x axis. [default to0]-yfloatSkew the clip along it's y axis. [default to0]-FlipTransformationFlip a clip vertically or horizontally. Acts as a mirror effect of the clip along the selected plane.Example:fromshotstack_sdk.model.flip_transformationimportFlipTransformationflip_transformation=FlipTransformation(horizontal=True,vertical=True)Arguments:ArgumentTypeDescriptionRequiredhorizontalboolFlip a clip horizontally. [default toFalse]-verticalboolFlip a clip vertically. [default toFalse]-MergeFieldA merge field consists of a key;find, and avalue; replace. Merge fields can be used to replace placeholders within the JSON edit to create re-usable templates. Placeholders should be a string with double brace delimiters, i.e."{{NAME}}". A
placeholder can be used for any value within the JSON edit.Example:fromshotstack_sdk.model.merge_fieldimportMergeFieldmerge_field=MergeField(find='NAME',replace='Jane')Arguments:ArgumentTypeDescriptionRequiredfindstringThe string to find without delimiters.YreplacereplaceThe replacement value. The replacement can be any valid JSON type - string, boolean, number, etc...YTemplate SchemasThe following schemas specify how to use templates to store and render templates. A template lets you save anEditthat can be rendered by its template ID and optionally include merge fields that are merged with the
template when rendered.TemplateA template is a savedEditthan can be loaded and re-used.Example:fromshotstack_sdk.model.templateimportTemplatetemplate=Template(name='My Template',template=edit)Arguments:ArgumentTypeDescriptionRequirednamestringThe template name.YtemplateEditAn edit defines the arrangement of a video on a timeline, an audio edit or an image design and the output format.YTemplateRenderConfigure the id and optional merge fields to render a template by id.Example:fromshotstack_sdk.model.template_renderimportTemplateRendertemplate_render=TemplateRender(id='21e781c0-8232-4418-fec1-cc99f0280c21',merge=merge)Arguments:ArgumentTypeDescriptionRequiredidstring idThe id of the template to render in UUID format.YmergeMergeField[]An array of key/value pairs that provides an easy way to create templates with placeholders. The placeholders can be used to find and replace keys with values. For example you can search for the placeholder{{NAME}}and replace it with the valueJane.-Output SchemasThe following schemas specify the output format and settings.OutputThe output format, render range and type of media to generate.Example:fromshotstack_sdk.model.outputimportOutputoutput=Output(format='mp4',resolution='sd',aspectRatio='16:9',size=size,fps=25.0,scaleTo='preview',quality='mediue',repeat=True,mute=False,_range=_range,poster=poster,thumbnail=thumbnail,destinations=destinations)Arguments:ArgumentTypeDescriptionRequiredformatstringThe output format and type of media file to generate.mp4- mp4 video filegif- animated gifjpg- jpg image filepng- png image filebmp- bmp image filemp3- mp3 audio file (audio only)YresolutionstringThe output resolution of the video or image.preview- 512px x 288px @ 15fpsmobile- 640px x 360px @ 25fpssd- 1024px x 576px @ 25fpshd- 1280px x 720px @ 25fps1080- 1920px x 1080px @ 25fps-aspectRatiostringThe aspect ratio (shape) of the video or image. Useful for social media output formats. Options are:16:9- regular landscape/horizontal aspect ratio (default)9:16- vertical/portrait aspect ratio1:1- square aspect ratio4:5- short vertical/portrait aspect ratio4:3- legacy TV aspect ratio-sizeSizeSet a custom size for a video or image. When using a custom size omit theresolutionandaspectRatio. Custom sizes must be divisible by 2 based on the encoder specifications.-fpsfloatOverride the default frames per second. Useful for when the source footage is recorded at 30fps, i.e. on  mobile devices. Lower frame rates can be used to add cinematic quality (24fps) or to create smaller file size/faster render times or animated gifs (12 or 15fps). Default is 25fps.12- 12fps15- 15fps23.976- 23.976fps24- 24fps29.97- 29.97fps25- 25fps30- 30fps-scaleTostringOverride the resolution and scale the video or image to render at a different size. When using scaleTo the asset should be edited at the resolution dimensions, i.e. use font sizes that look best at HD, then use scaleTo to output the file at SD and the text will be scaled to the correct size. This is useful if you want to create multiple asset sizes.preview- 512px x 288px @ 15fpsmobile- 640px x 360px @ 25fpssd- 1024px x 576px @25fpshd- 1280px x 720px @25fps1080- 1920px x 1080px @25fps-qualitystringAdjust the output quality of the video, image or audio. Adjusting quality affects  render speed, download speeds and storage requirements due to file size. The defaultmediumprovides the most optimized choice for all three  factors.low- slightly reduced quality, smaller file sizemedium- optimized quality, render speeds and file sizehigh- slightly increased quality, larger file size-repeatboolLoop tings for gif files. Set toTrueto loop,Falseto play only once. [default toTrue]-mutemuteMute the audio track of the output video. Set toTrueto mute,Falseto un-mute.-rangeRangeSpecify a time range to render, i.e. to render only a portion of a video or audio file. Omit this ting to export the entire video. Range can also be used to render a frame at a specific time point - ting a range and output format asjpgwill output a single frame image at the rangestartpoint.-posterPosterGenerate a poster image from a specific point on the timeline.-thumbnailThumbnailGenerate a thumbnail image from a specific point on the timeline.-destinationsDestinations[]A destination is a location where output files can be sent to for serving or hosting. By default all rendered assets are automatically sent to the Shotstack hosting destination.-SizeSet a custom size for a video or image. When using a custom size omit theresolutionandaspectRatio. Custom sizes must be divisible by 2 based on the encoder specifications.Example:fromshotstack_sdk.model.sizeimportSizesize=Size(width=1200,height=800)Arguments:ArgumentTypeDescriptionRequiredwidthintSet a custom width for the video or image file. Value must be divisible by 2. Maximum video width is 1920px, maximum image width is 4096px.-heightintSet a custom height for the video or image file. Value must be divisible by 2. Maximum video height is 1920px, maximum image height is 4096px.-RangeSpecify a time range to render, i.e. to render only a portion of a video or audio file. Omit this setting to export the entire video. Range can also be used to render a frame at a specific time point - setting a range and output format asjpgwill output a single frame image at the rangestartpoint.Example:fromshotstack_sdk.model.rangeimportRange_range=Range(start=3.0,length=6.0)Arguments:ArgumentTypeDescriptionRequiredstartfloatThe point on the timeline, in seconds, to start the render from - i.e. start at second 3.-lengthfloatThe length of the portion of the video or audio to render - i.e. render 6 seconds of the video.-PosterGenerate aPosterimage for the video at a specific point from the timeline. The poster image size will match the size of the output video.Example:fromshotstack_sdk.model.posterimportPosterposter=Poster(capture=1.0)Arguments:ArgumentTypeDescriptionRequiredcapturefloatThe point on the timeline in seconds to capture a single frame to use as the poster image.YThumbnailGenerate a thumbnail image for the video or image at a specific point from the timeline.Example:fromshotstack_sdk.model.thumbnailimportThumbnailthumbnail=Thumbnail(capture=1.0,scale=0.3)Arguments:ArgumentTypeDescriptionRequiredcapturefloatThe point on the timeline in seconds to capture a single frame to use as the thumbnail image.YscalefloatScale the thumbnail size to a fraction of the viewport size - i.e. ting the scale to 0.5 will scale  the thumbnail to half the size of the viewport.YDestinationsShotstackDestinationSend rendered assets to the Shotstack hosting and CDN service. This destination is enabled by default.Example:fromshotstack_sdk.model.shotstack_destinationimportShotstackDestinationshotstack_destination=ShotstackDestination(provider='shotstack',exclude=False)Arguments:ArgumentTypeDescriptionRequiredproviderstringThe destination to send rendered asset to - set toshotstackfor Shotstack hosting and CDN. [default toshotstack]YexcludeboolSet toTrueto opt-out from the Shotstack hosting and CDN service. All files must be downloaded within 24 hours of rendering. [default toFalse]-MuxDestinationSend rendered videos to theMuxvideo hosting and
streaming service. Mux credentials are required and added via thedashboard, not in the request.Example:fromshotstack_sdk.model.mux_destinationimportMuxDestinationmux_destination=MuxDestination(provider='mux',options=options)Arguments:ArgumentTypeDescriptionRequiredproviderstringThe destination to send rendered assets to - set tomuxfor Mux.YoptionsMuxDestinationOptionsAdditional Mux configuration and features.-MuxDestinationOptionsPass additional options to control how Mux processes video. Currently supports playback policy option.Example:fromshotstack_sdk.model.mux_destination_optionsimportMuxDestinationOptionsmux_destination_options=MuxDestinationOptions(playback_policy=['public'])Arguments:ArgumentTypeDescriptionRequiredplayback_policystringSets the Muxplayback_policyoption. Value is an array of strings - usepublic,signed, or both.-S3DestinationSend rendered videos to anAmazon S3bucket. Send
files to any region with your own prefix and filename. AWS credentials are required and added via thedashboard, not in the request.Example:fromshotstack_sdk.model.s3_destinationimportS3Destinations3_destination=S3Destination(provider='s3',options=options)Arguments:ArgumentTypeDescriptionRequiredproviderstringThe destination to send rendered assets to - set tos3for S3.YoptionsS3DestinationOptionsAdditional S3 configuration options.-S3DestinationOptionsPass additional options to control how files are stored in S3.Example:fromshotstack_sdk.model.s3_destination_optionsimportS3DestinationOptionss3_destination_options=S3DestinationOptions(region='us-east-1',bucket='my-bucket',prefix='my-renders',filename='my-file',acl='public-read')Arguments:ArgumentTypeDescriptionRequiredregionstringChoose the region to send the file to. Must be a validAWS regionstring likeus-east-1orap-southeast-2YbucketstringThe bucket name to send files to. The bucket must exist in the AWS account before files can be sent.YprefixstringA prefix for the file being sent. This is typically a folder name, i.e.videosorcustomerId/videos.-filenamestringUse your own filename instead of the default render ID filename. Note: omit the file extension as this will be appended depending on the output format. Also-poster.jpgand-thumb.jpgwill be appended for poster and thumbnail images.-aclstringSets the S3 Access Control List (acl) permissions. Default isprivate. Must use a valid  S3Canned ACL.-Render Response SchemasThe following schemas are returned by the render request and status request.QueuedResponseThe response received after arender requestis submitted. The render task is queued for rendering and a unique render id is returned.Attributes:AttributeTypeDescriptionRequiredsuccessboolTrueif successfully queued, elseFalse.YmessagestringCreated,Bad Requestor an error message.YresponseQueuedResponseDataQueuedResponseDataor an error message.YQueuedResponseDataTheQueuedResponseDatais the response data returned with theQueuedResponse.Attributes:AttributeTypeDescriptionRequiredmessagestringSuccess response message or error details.YidstringThe id of the render task in UUID format.YRenderResponseTheRenderResponseis the response received after arender status requestis submitted. The response includes details about status of a render and the output URL.Attributes:AttributeTypeDescriptionRequiredsuccessboolTrueif status available, elseFalse.YmessagestringOKor an error message.YresponseRenderResponseDataRenderResponseor an error message.YRenderResponseDataTheRenderResponseDatais the response data returned with theRenderResponserequest including status and URL.Arguments:ArgumentTypeDescriptionRequiredidstringThe id of the render task in UUID format.YownerstringThe owner id of the render task.YplanstringThe customer subscription plan.-statusstringThe status of the render task.queued- render is queued waiting to be renderedfetching- asset are being fetchedrendering- the asset is being renderedsaving- the final asset is being saved to storagedone- the asset is ready to be downloadedfailed- there was an error rendering the assetYerrorstringAn error message, only displayed if an error occurred.-durationfloatThe output video or audio length in seconds.-render_timefloatThe time taken to render the asset in milliseconds.-urlstringThe URL of the final asset. This will only be available if status is done. This is a temporary URL and will be deleted after 24 hours. By default all asset are copied to the Shotstack hosting and CDN destination.-posterstringThe URL of the poster image if requested. This will only be available if status is done.-thumbnailstringThe URL of the thumbnail image if requested. This will only be available if status is done.-dataEditThe timeline and output data to be rendered.YcreatedstringThe time the render task was initially queued.YupdatedstringThe time the render status was last updated.YTemplate Response SchemasThe following schemas are returned by the templates endpoint, including create, update and rendering a template.TemplateResponseThe response received after atemplateis submitted. The template is saved and a unique
template id is returned.Attributes:AttributeTypeDescriptionRequiredsuccessboolTrueif successfully queued, elseFalse.YmessagestringCreated,Bad Requestor an error message.YresponseTemplateResponseDataTemplateResponseDataor an error message.YTemplateResponseDataThe response data returned with theTemplateResponse.Attributes:AttributeTypeDescriptionRequiredmessagestringSuccess response message or error details.YidstringThe unique id of the template in UUID format.YTemplateDataResponseThe template data including the template name andEdit.Attributes:AttributeTypeDescriptionRequiredsuccessboolTrueif successfully queued, elseFalse.YmessagestringCreated,Bad Requestor an error message.YresponseTemplateDataResponseDataTemplateDataResponseDataor an error message.YTemplateDataResponseDataThe response data returned with theTemplateDataResponse.Attributes:AttributeTypeDescriptionRequiredidstringThe unique id of the template in UUID format.YnamestringThe template name.YownerstringThe owner id of the templates.YtemplateEditEditor an error message.YTemplateListResponseA list of previously saved templates.Attributes:AttributeTypeDescriptionRequiredsuccessboolTrueif successfully queued, elseFalse.YmessagestringCreated,Bad Requestor an error message.YresponseTemplateListResponseDataTemplateListResponseDataor an error message.YTemplateListResponseDataThe response data returned with theTemplateListResponse.Attributes:AttributeTypeDescriptionRequiredownerboolThe owner id of the templates.YtemplatesTemplateListResponseItem[]The list of templates.YTemplateListResponseItemThe individual template item returned with theTemplateListResponseDatatemplates
list.Attributes:AttributeTypeDescriptionRequiredidstringThe unique id of the template in UUID format.YnamestringThe template nameYcreatedstringThe time the template was created.-updatedstringThe time the template was last updated.-Inspecting MediaThe SDKprobeendpoint can be used to inspect media hosted online. Simply pass the URL of an asset to inspect.Probe ExampleThe example below inspects (probes) a video hosted on GitHub and returns metadata about the file.importshotstack_sdkasshotstackfromshotstack_sdk.apiimportedit_apihost="https://api.shotstack.io/stage"configuration=shotstack.Configuration(host=host)configuration.api_key['DeveloperKey']="H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD"withshotstack.ApiClient(configuration)asapi_client:api_instance=edit_api.EditApi(api_client)url='https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4'try:api_response=api_instance.probe(url)streams=api_response['response']['metadata']['streams']forstreaminstreams:ifstream['codec_type']=='video':print(f"Example settings for:{api_response['response']['metadata']['format']['filename']}")print(f"Width:{stream['width']}px")print(f"Height:{stream['height']}px")print(f"Framerate:{stream['r_frame_rate']}fps")print(f"Duration:{stream['duration']}secs")exceptExceptionase:print(f"Unable to resolve API call:{e}")Probe SchemasThe following schemas are returned by the probe request.ProbeResponseTheProbeResponseis the response returned after aprobe requestis submitted. The probe requests returns data from FFprobe formatted as JSON.Arguments:ArgumentTypeDescriptionRequiredsuccessboolTrueif media successfully read, elseFalse.YmessagestringCreated,Bad Requestor an error message.YresponseobjectThe response from FFprobe in JSON formatYManaging AssetsBy default, all assets generated by the editing API are hosted by Shotstack and served via our CDN. The SDK provides
access to the Serve API to retrieve information about hosted files. Files can also be deleted.Assets by Render ID ExampleThe example below uses a render ID to look up hosted assets associated with the render. Note that multiple assets can be
created for a render, i.e. video, thumb and poster. Each asset has a unique asset ID different to the render ID.importshotstack_sdkasshotstackfromshotstack_sdk.apiimportserve_apihost='https://api.shotstack.io/stage'configuration=shotstack.Configuration(host=host)configuration.api_key['DeveloperKey']='H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'withshotstack.ApiClient(configuration)asapi_client:api_instance=serve_api.ServeApi(api_client)id='140924c6-077d-4334-a89f-94befcfc0155'try:api_response=api_instance.get_asset_by_render_id(id)data=api_response['data']ifdata['attributes']['status']=='ready':print(f">> Asset CDN URL:{data['attributes']['url']}")print(f">> Asset ID:{data['attributes']['id']}")print(f">> Render ID:{data['attributes']['render_id']}")exceptExceptionase:print(f"Unable to resolve API call:{e}")Assets by Asset ID ExampleEvery asset has a unique asset ID, the example below looks up an asset by its asset ID.importshotstack_sdkasshotstackfromshotstack_sdk.apiimportserve_apihost='https://api.shotstack.io/stage'configuration=shotstack.Configuration(host=host)configuration.api_key['DeveloperKey']='H7jKyj90kd09lbLOF7J900jNbSWS67X87xs9j0cD'withshotstack.ApiClient(configuration)asapi_client:api_instance=serve_api.ServeApi(api_client)id='ed43eae3-4825-4c03-979d-f7dc47b9997c'try:api_response=api_instance.get_asset(id)data=api_response['data']ifdata['attributes']['status']=='ready':print(">> Something went wrong, asset could not be copied.")else:print(f">> Asset CDN URL:{data['attributes']['url']}")print(f">> Asset ID:{data['attributes']['id']}")print(f">> Render ID:{data['attributes']['render_id']}")exceptExceptionase:print(f"Unable to resolve API call:{e}")Asset SchemasThe following schemas are returned by requests to the Serve API.AssetResponseTheAssetResponseis the response returned by the Serve APIget assetrequest. Includes details of a hosted video, image, audio file, thumbnail or poster image. The response follows  thejson:apispecification.Arguments:ArgumentTypeDescriptionRequireddataAssetResponseDataReturns an asset resource.-AssetRenderResponseTheAssetRenderResponseis the response returned by the Serve APIget asset by render idrequest. The response is an array of asset resources, including video, image, audio, thumbnail and
poster image. The response follows  thejson:apispecification.Arguments:ArgumentTypeDescriptionRequireddataAssetResponseData[]Returns an array of asset resources grouped by render id.-AssetResponseDataTheAssetResponseDatacontains the type of resource (an asset) and attributes of the asset.Arguments:ArgumentTypeDescriptionRequiredtypestringThe type of resource, in this case it is anasset.-attributesAssetResponseAttributesThe asset attributes including render id, url, filename, file size, etc...-AssetResponseAttributesTheAssetResponseAttributescontains the list of asset attributes and their values.Arguments:ArgumentTypeDescriptionRequiredidstringThe unique id of the hosted asset in UUID format.-ownerstringThe owner id of the render task.-regionstringThe region the asset is hosted, currently onlyau(Australia).-renderIdstringThe original render id that created the asset in UUID format. Multiple asset can share the same render id.-filenamestringThe asset file name.-urlstringThe asset file name.-statusstringThe status of the asset.importing- the asset is being copied to the hosting serviceready- the asset is ready to be served to usersfailed- the asset failed to copy or deletedeleted- the asset has been deleted-createdstringThe time the asset was created.-updatedstringThe time the asset status was last updated.-API Documentation and GuidesGetting Started GuideAPI ReferenceExamplesShotstack Website