# Create a clip

This operation creates (or replaces) a video object in Wowza Video by clipping a video or live stream or, clipping and stitching together video or live stream clips.


Create a clip

To create a clip off of an existing video or live stream, send the id of the video or live stream you want to clip along with the asset_type, mode, start, and stop parameters.

Create clips and stitch the clips

To create multiple clips and stitch the clips together as one clip, send the id of the videos or live streams you want to clip along with the asset_type, mode, start, and stop parameters.

Create a clip and replace the original video

To create a clip and replace the original video with the clip, send the replace_video_id parameter where replace_video_id is the video id of the video to be replaced, along with the asset_type, mode, start, and stop parameters.

Note: The replace option works only with videos and not live streams. The replace_video_id is specifically a video ID and not a live stream ID.

Caution! Once you replace the original video with the clip, you will no longer be able to retrieve the original video.

Endpoint: POST /clipping
Version: v2.0

## Request fields (application/json):

  - `clipping` (object)

  - `clipping.clips` (array, required)
    Represents an array of videos or live streams to be included in the clip/stitch operation. If you include only one video or live stream, it is clipped based on start and stop. If you include more than one video or live stream, they are clipped based on start and stop, and stitched as one clip.

  - `clipping.clips.id` (string, required)
    Specifies the id of the video or live stream to be clipped and/or stitched.
    Example: "73a0c613-8972-14cd-9d0c-3c993bddb388"

  - `clipping.clips.asset_type` (string, required)
    Specifies the asset type.
    Enum: "VOD", "LIVE_STREAM"

  - `clipping.clips.start` (string)
    Starting time of the video segment in 24-hour format with frame precision (HH:MM:SS:FF). If omitted, video starts from the beginning.

If you are clipping a live stream, the start time of the stream must be in ISO-8601 format, which is YYYY-MM-DDThh:mm:ssZ.
    Example: "00:01:20:00"

  - `clipping.clips.stop` (string)
    Ending time of the video segment in 24-hour format with frame precision (HH:MM:SS:FF). If omitted, video continues until its natural end.

If you are clipping a live stream, the end time of the stream must be in ISO-8601 format, which is YYYY-MM-DDThh:mm:ssZ.
    Example: "00:05:25:00"

  - `clipping.mode` (string, required)
    Specifies the mode for clipping/stitching operations. In QUICK mode, clipping can only be performed on segment breakpoints, optimizing for speed. For example, for a video or live stream that has 8-second interval breakpoint, if you specify a breakpoint outside the 8-second interval, the breakpoint is defaulted to the closest 8-second breakpoint. If you set your start as 00:00:10:00 (HH:MM:SS:FF), it will set your start to 00:00:08:00 ((HH:MM:SS:FF). In PRECISE mode, clipping can be performed on the frame level, ensuring higher accuracy but requiring more processing time. PRECISE mode incurs additional encoding time and cost.

Note: If you are clipping or stitching live streams, the start and stop times must be in ISO-8601 format, which is YYYY-MM-DDThh:mm:ssZ.
    Enum: "QUICK", "PRECISE"

  - `clipping.name` (string)
    A descriptive name of the video that's displayed in the player. If not specified, it will default to the input file's name.
    Example: "My video"

  - `clipping.description` (string)
    A description of the video that's displayed in the player.
    Example: "A new video for my business."

  - `clipping.category_id` (string)
    The unique identifier for the category that the video belongs to.

  - `clipping.tags` (array)
    A list of tags.
    Example: ["foo","bar"]

  - `clipping.published_at` (string)
    Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using [ovp-plugin](https://developer.wowza.com/docs/wowza-flowplayer/plugins/wowza-video-platform-integration/) to request the video.
    Example: "2024-05-01T12:33:22Z"

  - `clipping.published` (boolean)
    Determines, together with published_at and unpublished_at, if this video will be visible in public listings such as MRSS-feeds, endscreens, and playlists. If true, and if published_at and unpublished_at allow, the video will be visible.

  - `clipping.unpublish` (boolean)
    If true, the unpublished_at is respected and the video will not be available after unpublished_at. If false, the video will not be unpublished.

  - `clipping.unpublished_at` (string)
    Date and time, in ISO-8601, format when video no longer is available for publishing. After this date, the video is not visible in the player if using [ovp-plugin](https://developer.wowza.com/docs/wowza-flowplayer/plugins/wowza-video-platform-integration/) to request the video.
    Example: "2025-01-01T12:33:22Z"

  - `clipping.no_ads` (boolean)
    When set to true, no ads will be displayed during this video. 

Note: This feature only works for Iframe embeds.

  - `clipping.ad_keywords` (string)
    Used for replacing the ad_keywords macro in the VAST-tag in any player that plays the video.
    Example: "special_ads"

  - `clipping.replace_video_id` (string)
    Specifies the video id of the video to be replaced by the clip/stitch operation. If the video id is not provided, a new video will be created.

Caution! Once you replace the original video with the clip, you will no longer be able to retrieve the original video.

## Response 200 fields (application/json):

  - `video` (object)

  - `video.id` (string)
    Specifies the id of the video that is clipped or stitched based on the live stream(s) or video(s) sent in the request.
    Example: "73a0c613-8972-14cd-9d0c-3c993bddb388"

  - `video.name` (string)
    A descriptive name of the video that's displayed in the player. If not specified, it will default to the input file's name.
    Example: "My video"

  - `video.description` (string)
    A description of the video that's displayed in the player.
    Example: "A new video for my business."

  - `video.duration_in_ms` (integer)
    Duration of the video in milliseconds.

  - `video.unpublish` (boolean)
    If true, the unpublished_at is respected and the video will not be available after unpublished_at. If false, the video will not be unpublished.

  - `video.unpublished_at` (string)
    Date and time, in ISO-8601 format when video is no longer available for publishing. After this date, the video is not visible in the player if using [ovp-plugin](https://developer.wowza.com/docs/wowza-flowplayer/plugins/wowza-video-platform-integration/) to request the video.
    Example: "2025-01-01T12:33:22Z"

  - `video.published` (boolean)
    Determines, together with published_at and unpublished_at, if this video will be visible in public listings such as MRSS-feeds, endscreens, and playlists. If true, and if published_at and unpublished_at allow, the video will be visible.

  - `video.published_at` (string)
    Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using [ovp-plugin](https://developer.wowza.com/docs/wowza-flowplayer/plugins/wowza-video-platform-integration/) to request the video.
    Example: "2024-05-01T12:33:22Z"

  - `video.tags` (array)
    A list of tags.
    Example: ["foo","bar"]

  - `video.remote` (boolean)
    If true, it indicated that the source file of the video is hosted in an external storage location.

  - `video.category_id` (string)
    The unique identifier for the category that the video belongs to.

  - `video.no_ads` (boolean)
    When set to true, no ads will be displayed during this video. 

Note: This feature only works for Iframe embeds.

  - `video.ad_keywords` (string)
    Used for replacing the ad_keywords macro in the VAST-tag in any player that plays the video.
    Example: "special_ads"

  - `video.created_at` (string)
    Date and time, in ISO-8601 format, when video was created.
    Example: "2024-05-15T12:33:22Z"

  - `video.updated_at` (string)
    Date and time, in ISO-8601 format, when video was updated.
    Example: "2024-05-16T12:33:22Z"

  - `video.state` (string)
    The current state of the video. The state reflects the current status of the video files for the video asset. Possible states listed below:


| State | Description |
|-----------|-------|
| UPLOADING  | The source file is currently being uploaded or waiting to be downloaded by our API. |
| WAITING_FOR_ENCODER | The source file was successfully downloaded by the platform and is in queue to be encoded. |
| PROCESSING  | Source file for the asset is encoding. The current encoding progress can be found on encoding_progress property. |
| FINISHED | The encoding is done and the encoded files can be fetched. In this state it's possible to embed the video. |
| ERROR  | If the platform, for some reason, could not download the source file or failed during the encoding process. error_messsage property can give more information about why it errored.  |
| DELETED  | The video files have been deleted. Usually the Video asset have been deleted when this state is reached and because of that it's very uncommon to see assets with this state. |
    Example: "PROCESSING"

  - `video.encoding_progress` (number)
    Progress of video encoding, in percentage. The max value, 100, is reached when all video files have been encoded.

  - `video.upload_progress` (number)
    Progress of source file upload, in percentage. If the value is 100, the source file is uploaded.

  - `video.error_message` (string)
    If the platform failed to encode the source file, a message describing the error reason will be presented in this property.

  - `video.deactivated` (boolean)
    If true, this video has been deactivated and is no longer available for embedding. This usually happens if the account was cancelled or trial limits were exceeded.

  - `video.images` (array)
    Images used together with the video in the platform and the player.

For platform video images specified in create and update requests, these are uploaded and delivered through the platform. For remote assets, the specified image URLs are passed along to the player using the URL specified in the request.

  - `video.images.type` (string)
    Image type where valid values are thumbnail or image. thumbnail is a smaller image and image is larger. Size of the images depends on the size of the uploaded image.
    Enum: "thumbnail", "image", "image_0", "image_1", "image_2", "image_3", "image_4", "image_5"

  - `video.images.url` (string)
    The URL to the image. We accept HTTP and HTTPS addresses.
    Example: "https://example.com/image.jpg"

  - `video.encodings` (array)
    Array containing all available video files and their metadata.

  - `video.encodings.audio_bitrate_in_kbps` (integer)
    Audio bitrate in kb/s.
    Example: 2300

  - `video.encodings.audio_channel` (integer)
    Number of audio channels.
    Example: 2

  - `video.encodings.audio_codec` (string)
    Audio codec used in the file.
    Example: "aac"

  - `video.encodings.audio_sample_rate` (integer)
    Audio sample rate for this file. Refers to the number of samples of audio taken per second, measured in hertz (Hz). It determines the audio's frequency range and quality, where a higher sample rate captures more detail.
    Example: 44100

  - `video.encodings.height` (integer)
    Height of the video in pixels.
    Example: 1080

  - `video.encodings.width` (integer)
    Width of the video in pixels.
    Example: 1920

  - `video.encodings.video_file_url` (string)
    URL to the video file. We accept HTTP and HTTPS addresses.
    Example: "https://flowplayer.com/video.mp4"

  - `video.encodings.video_container` (string)
    Video container type used for this video file.
    Example: "mp4"

  - `video.encodings.video_codec` (string)
    Video codec used in this video file.
    Example: "h264"

  - `video.encodings.total_bitrate_in_kbps` (integer)
    Total bitrate, video+audio, for the file in kb/s.
    Example: 1023

  - `video.encodings.created_at` (string)
    Creation timestamp of the file.

  - `video.encodings.size_in_bytes` (integer)
    Total file size including both audio and video in bytes. For segmented files, such as DASH and HLS, this is the complete size covering all segments and renditions.
    Example: 8325555

  - `video.shallow_copy` (boolean)
    Specifies whether this video is a shallow copy of another video. A shallow copy uses video files controlled by another video, usually on another workspace.


Videos that are shallow copies can't use all features available for normal videos. For example, it's not possible to upload a new version of the video.


Another difference is that deleting the video will not delete any video files. If the video asset that is the source of the copy is deleted, the files will no longer be available for this asset.

  - `video.shallow_copy_source_id` (string)
    If the video is a shallow copy, this field contains the ID of the source video entity.

Note: There are cases where it is not possible to identify the source and in those cases this value will be null.

  - `video.multiple_audio_tracks` (boolean)
    If true, this video has several different audio tracks available for the player. For example, there may be audio tracks in different languages.

  - `video.audio_only` (boolean)
    If true, this video has no video track but only audio tracks.

  - `video.version` (integer)
    Tracks the number of times a new source file was uploaded for this video asset. For each time a new source file is uploaded, the value increases by one.

## Response 401 fields (application/json):

  - `meta` (object, required)

  - `meta.status` (integer)

  - `meta.code` (string)

  - `meta.title` (string)

  - `meta.message` (string)

  - `meta.description` (string)

  - `meta.links` (array)

## Response 403 fields (application/json):

  - `meta` (object, required)

  - `meta.status` (integer)

  - `meta.code` (string)

  - `meta.title` (string)

  - `meta.message` (string)

  - `meta.description` (string)

  - `meta.links` (array)

## Response 404 fields (application/json):

  - `meta` (object, required)

  - `meta.status` (integer)

  - `meta.code` (string)

  - `meta.title` (string)

  - `meta.message` (string)

  - `meta.description` (string)

  - `meta.links` (array)

## Response 410 fields (application/json):

  - `meta` (object, required)

  - `meta.status` (integer)

  - `meta.code` (string)

  - `meta.title` (string)

  - `meta.message` (string)

  - `meta.description` (string)

  - `meta.links` (array)

## Response 422 fields (application/json):

  - `meta` (object, required)

  - `meta.status` (integer)

  - `meta.code` (string)

  - `meta.title` (string)

  - `meta.message` (string)

  - `meta.description` (string)

  - `meta.links` (array)