openapi: 3.0.3
info:
  title: Wowza Streaming Engine REST advanced_token_authentication clipping API
  description: Complete REST API for Wowza Streaming Engine. Auto-converted from Swagger 1.2 (http://localhost:8089/swagger.json) to OpenAPI 3.0.3 for public documentation.
  version: 2.0.0
  contact:
    name: Wowza Media Systems
    url: https://www.wowza.com/docs/wowza-streaming-engine-rest-api
  license:
    name: Wowza Media Systems
    url: https://www.wowza.com
servers:
- url: http://localhost:8087
  description: Wowza Streaming Engine Server
security:
- basicAuth: []
tags:
- name: clipping
  description: Operations related to clipping and stitching videos and live streams.
  x-displayName: Clipping
paths:
  /clipping:
    post:
      tags:
      - clipping
      summary: Create a clip
      description: '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.'
      operationId: createClipStitch
      x-codeSamples:
      - lang: Shell
        source: "// Using cURL\ncurl -H \"Authorization: Bearer ${WV_JWT}\" \\\n  \n  -H \"Content-Type: application/json\" \\\n  -X \"POST\" \\\n  \"${WV_HOST}/api/2.0/clipping\" \\\n  -d $'{\n  \"clips\": [\n    \"id\": \"73a0c613-8972-14cd-9d0c-3c993bddb388\",\n    \"asset_type\": \"VOD\",\n    \"start\": \"00:01:20:00\",\n    \"stop\": \"00:05:25:00\"\n    ],\n  \"name\": \"My video\",\n  \"description\": \"A new video for my business.\",\n  \"unpublish\": true,\n  \"unpublished_at\": \"2025-01-01T12:33:22Z\",\n  \"published\": true,\n  \"published_at\": \"2024-05-01T12:33:22Z\",\n  \"tags\": [\n    \"foo\",\n    \"bar\"\n  ],\n  \"category_id\": \"<The default category>\",\n  \"no_ads\": true,\n  \"ad_keywords\": \"special_ads\",\n}'\n"
      - lang: JavaScript
        source: "// Using Node.js\nconst https = require('https');\nconst crypto = require('crypto');\nvar hostname = 'api.video.wowza.com'\nvar path = '/api/beta/clipping';\n//For security, never reveal API token in client-side code\nvar wvJWT = 'Bearer [your JWT]';\n\nconst options = {\n  hostname: hostname,\n  path: path,\n  method: 'POST',\n  headers: {\n    'Authorization': wvJWT,\n    'Content-Type': 'application/json'\n  }\n};\nconst req = https.request(options, function(res) {\n  var body = '';\n  res.on('data', function(data) {\n    body += data;\n  });\n  res.on('end', function() {\n    console.log(JSON.parse(body));\n  });\n}).on('error', function(e) {\n  console.log(e.message);\n});\nreq.write(JSON.stringify({\n    \"clips\": [\n      \"id\": \"73a0c613-8972-14cd-9d0c-3c993bddb388\",\n      \"asset_type\": \"VOD\",\n      \"start\": \"00:01:20:00\",\n      \"stop\": \"00:05:25:00\"\n      ],\n  \"name\": \"My New Video\",\n  \"description\": \"A new video for my business.\",\n  \"unpublish\": true,\n  \"unpublished_at\": \"2025-01-01T12:33:22Z\",\n  \"published\": true,\n  \"published_at\": \"2024-05-01T12:33:22Z\",\n  \"tags\": [\n    \"foo\",\n    \"bar\"\n  ]\n  \"category_id\": \"<The default category>\",\n  \"no_ads\": true,\n  \"ad_keywords\": \"special_ads\",\n}));\nreq.end();\n"
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClipStitchRequestModel'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateClipStitchResponseModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error410'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422'
components:
  schemas:
    Error403:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 403
            code: ERR-403-RecordUnaccessible
            title: Record Unaccessible Error
            message: The requested resource isn't accessible.
            description: ''
            links: []
    Error401:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 401
            code: ERR-401-NoApiKey
            title: No API Key Error
            message: No API key sent in header.
            description: ''
            links: []
        Example Response 2:
          meta:
            status: 401
            code: ERR-401-NoAccessKey
            title: No Access Key Error
            message: No access key sent in header.
            description: ''
            links: []
        Example Response 3:
          meta:
            status: 401
            code: ERR-401-InvalidApiKey
            title: Invalid Api Key Error
            message: Invalid API key.
            description: ''
            links: []
        Example Response 4:
          meta:
            status: 401
            code: ERR-401-InvalidAccessKey
            title: Invalid Access Key Error
            message: Invalid access key.
            description: ''
            links: []
        Example Response 5:
          meta:
            status: 401
            code: ERR-401-BadAccountStatus
            title: Bad Account Status Error
            message: Your account's status doesn't allow this action.
            description: ''
            links: []
        Example Response 6:
          meta:
            status: 401
            code: ERR-401-FeatureNotEnabled
            title: Feature Not Enabled Error
            message: This feature isn't enabled.
            description: ''
            links: []
        Example Response 7:
          meta:
            status: 401
            code: ERR-401-TrialExceeded
            title: Bad Billing Status Error
            message: Your billing status needs attention. You can't start or add live streams until your billing status is updated.
            description: ''
            links: []
        Example Response 8:
          meta:
            status: 401
            code: ERR-401-ExpiredToken
            title: JWT is expired
            message: Token has exired.
            description: ''
            links: []
        Example Response 9:
          meta:
            status: 401
            code: ERR-401-InvalidToken
            title: JWT is invalid
            message: Token is invalid.
            description: ''
            links: []
    CreateClipStitch:
      required:
      - mode
      - clips
      type: object
      properties:
        clips:
          type: array
          description: 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.
          items:
            required:
            - id
            - asset_type
            type: object
            title: clips
            properties:
              id:
                type: string
                description: Specifies the id of the video or live stream to be clipped and/or stitched.
                example: 73a0c613-8972-14cd-9d0c-3c993bddb388
              asset_type:
                type: string
                description: Specifies the asset type.
                example: VOD
                enum:
                - VOD
                - LIVE_STREAM
              start:
                type: string
                description: '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
              stop:
                type: string
                description: '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
        mode:
          type: string
          description: '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.'
          example: PRECISE
          enum:
          - QUICK
          - PRECISE
        name:
          type: string
          description: 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
        description:
          type: string
          description: A description of the video that's displayed in the player.
          example: A new video for my business.
        category_id:
          type: string
          description: The unique identifier for the category that the video belongs to.
          default: <The account's default category>
        tags:
          type: array
          description: A list of tags.
          example:
          - foo
          - bar
          items:
            type: string
            description: A list of tags.
            example:
            - foo
            - bar
        published_at:
          type: string
          description: 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.
          format: date-time
          example: '2024-05-01T12:33:22Z'
        published:
          type: boolean
          description: 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.
        unpublish:
          type: boolean
          description: 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.
          default: false
        unpublished_at:
          type: string
          description: 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.
          format: date-time
          example: '2025-01-01T12:33:22Z'
        no_ads:
          type: boolean
          description: "When set to `true`, no ads will be displayed during this video. \n\n**Note**: This feature only works for Iframe embeds."
        ad_keywords:
          type: string
          description: 'Used for replacing the `ad_keywords` macro in the VAST-tag in any player that plays the video. '
          example: special_ads
        replace_video_id:
          type: string
          description: '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.'
    EncodingModel:
      type: object
      properties:
        audio_bitrate_in_kbps:
          type: integer
          description: Audio bitrate in kb/s.
          format: int32
          example: 2300
        audio_channel:
          type: integer
          description: Number of audio channels.
          format: int32
          example: 2
        audio_codec:
          type: string
          description: Audio codec used in the file.
          example: aac
        audio_sample_rate:
          type: integer
          description: 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.
          format: int32
          example: 44100
        height:
          type: integer
          description: Height of the video in pixels.
          format: int32
          example: 1080
        width:
          type: integer
          description: Width of the video in pixels.
          format: int32
          example: 1920
        video_file_url:
          type: string
          description: URL to the video file. We accept HTTP and HTTPS addresses.
          example: https://flowplayer.com/video.mp4
        video_container:
          type: string
          description: Video container type used for this video file.
          example: mp4
        video_codec:
          type: string
          description: Video codec used in this video file.
          example: h264
        total_bitrate_in_kbps:
          type: integer
          description: Total bitrate, video+audio, for the file in kb/s.
          format: int32
          example: 1023
        created_at:
          type: string
          description: Creation timestamp of the file.
          format: date-time
        size_in_bytes:
          type: integer
          description: 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.
          format: int64
          example: 8325555
      description: Array containing all available Video files and their metadata
    Error422:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 422
            code: ERR-422-RecordInvalid
            title: Record Invalid Error
            message: The request couldn't be processed. ... can't be blank
            description: ''
            links: []
        Example Response 2:
          meta:
            status: 422
            code: ERR-422-RecordInvalid
            title: Record Invalid Error
            message: The request couldn't be processed. Provider wowza_video is not allowed
            description: ''
            links: []
        Example Response 3:
          meta:
            status: 422
            code: ERR-422-InvalidStateChange
            title: Invalid State Change Error
            message: The request couldn't be processed. There must be at least one WebRTC output for this transcoder.
            description: ''
            links: []
        Example Response 4:
          meta:
            status: 422
            code: ERR-422-RecordInvalid
            title: Record Invalid Error
            message: API cannot remove the primary Output Stream Target with the ID of <output id> from the Live Stream <livestream id><livestream name>.
            description: ''
            links: []
        Example Response 5:
          meta:
            status: 422
            code: ERR-422-InvalidStateChange
            title: Invalid State Change Error
            message: The request couldn't be processed. The broadcast location can't be updated when using autostart.
            description: ''
            links: []
    Error410:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 410
            code: ERR-410-RecordDeleted
            title: Record Deleted Error
            message: The requested resource has been deleted.
            description: ''
            links: []
    CreateClipStitchRequestModel:
      type: object
      description: Create clip/stitch request for the Wowza Video REST API
      properties:
        clipping:
          type: object
          $ref: '#/components/schemas/CreateClipStitch'
    ImageModel:
      type: object
      properties:
        type:
          type: string
          description: 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
        url:
          type: string
          description: The URL to the image. We accept HTTP and HTTPS addresses.
          example: https://example.com/image.jpg
      description: '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 just passed along to the player using the URL specified in the request.

        '
    CreateClipStitchResponseModel:
      type: object
      properties:
        video:
          type: object
          title: video
          description: ''
          properties:
            id:
              type: string
              description: 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
            name:
              type: string
              description: 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
            description:
              type: string
              description: A description of the video that's displayed in the player.
              example: A new video for my business.
            duration_in_ms:
              type: integer
              description: Duration of the video in milliseconds.
              format: int64
            unpublish:
              type: boolean
              description: 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.
              default: false
            unpublished_at:
              type: string
              description: 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.
              format: date-time
              example: '2025-01-01T12:33:22Z'
            published:
              type: boolean
              description: 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.
            published_at:
              type: string
              description: 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.
              format: date-time
              example: '2024-05-01T12:33:22Z'
            tags:
              type: array
              description: A list of tags.
              example:
              - foo
              - bar
              items:
                type: string
                description: A list of tags.
                example:
                - foo
                - bar
            remote:
              type: boolean
              description: If true, it indicated that the source file of the video is hosted in an external storage location.
              default: false
              example: false
            category_id:
              type: string
              description: The unique identifier for the category that the video belongs to.
              default: <The account's default category>
            no_ads:
              type: boolean
              description: "When set to `true`, no ads will be displayed during this video. \n\n**Note**: This feature only works for Iframe embeds."
            ad_keywords:
              type: string
              description: Used for replacing the `ad_keywords` macro in the VAST-tag in any player that plays the video.
              example: special_ads
            created_at:
              type: string
              description: Date and time, in ISO-8601 format, when video was created.
              format: date-time
              example: '2024-05-15T12:33:22Z'
            updated_at:
              type: string
              description: Date and time, in ISO-8601 format, when video was updated.
              format: date-time
              example: '2024-05-16T12:33:22Z'
            state:
              type: string
              description: '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
            encoding_progress:
              type: number
              description: Progress of video encoding, in percentage. The max value, `100`, is reached when all video files have been encoded.
              format: double
            upload_progress:
              type: number
              description: Progress of source file upload, in percentage. If the value is `100`, the source file is uploaded.
              format: double
            error_message:
              type: string
              description: 'If the platform failed to encode the source file, a message describing the error reason will be presented in this property.  '
            deactivated:
              type: boolean
              description: 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.
              default: false
            images:
              type: array
              description: '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.

                '
              items:
                $ref: '#/components/schemas/ImageModel'
            encodings:
              type: array
              description: Array containing all available video files and their metadata.
              items:
                $ref: '#/components/schemas/EncodingModel'
            shallow_copy:
              type: boolean
              description: '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.

                '
            shallow_copy_source_id:
              type: string
              description: '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`.'
            multiple_audio_tracks:
              type: boolean
              description: If `true`, this video has several different audio tracks available for the player. For example, there may be audio tracks in different languages.
            audio_only:
              type: boolean
              description: If `true`, this video has no video track but only audio tracks.
            version:
              type: integer
              description: 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.
              format: int32
    Error404:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 404
            code: ERR-404-RecordNotFound
            title: Record Not Found Error
            message: The requested resource couldn't be found.
            description: ''
            links: []
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Wowza Streaming Engine admin credentials
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication