API.Video Watermarks API

openapi: 3.2.0
info:
  title: api.video Watermarks API
  description: api.video is an API that encodes on the go to facilitate immediate playback, enhancing viewer streaming experiences across multiple devices and platforms. You can stream live or on-demand online videos within minutes.
  version: '1'
servers:
- url: https://ws.api.video
  description: Production server
- url: https://sandbox.api.video
  description: Test server `all videos are watermarked, and deleted after 24 hours.
tags:
- name: Watermarks
paths:
  /watermarks:
    post:
      tags:
      - Watermarks
      summary: Upload a watermark
      description: Create a new watermark by uploading a `JPG` or a `PNG` image.
      operationId: POST_watermark
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/watermark-upload-payload'
      responses:
        '200':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/watermark'
              examples:
                response:
                  value:
                    watermarkId: watermark_1BWr2L5MTQwxGkuxKjzh6i
                    createdAt: '2020-03-03T12:52:03+00:00'
        '400':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad-request'
              examples:
                response:
                  value:
                    status: 400
                    type: https://docs.api.video/reference/uploaded-file-extension-invalid
                    title: Only [jpeg, jpg, JPG, JPEG, png, PNG] extensions are supported.
                    name: file
        '429':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/too-many-requests'
              examples:
                Too many requests:
                  value:
                    type: https://docs.api.video/reference/too-many-requests
                    title: Too many requests.
                    status: 429
      security:
      - apiKey: []
      x-client-action: upload
      x-doctave:
        code-samples:
        - language: go
          code: "// First install the go client with \"go get github.com/apivideo/api.video-go-client\"\n// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/WatermarksApi.md#upload\n\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"os\"\n    apivideosdk \"github.com/apivideo/api.video-go-client\"\n)\n\nfunc main() {\n    client := apivideosdk.ClientBuilder(\"YOUR_API_KEY\").Build()\n    // if you rather like to use the sandbox environment:\n    // client := apivideosdk.SandboxClientBuilder(\"YOUR_SANDBOX_API_KEY\").Build()\n\n    file, _ := os.Open(\"./watermark.jpg\")\n    \n    res, err := client.Watermarks.UploadFile(file)\n\n    if err != nil {\n        fmt.Fprintf(os.Stderr, \"Error when calling `Watermarks.UploadFile``: %v\", err)\n    }\n    // response from `UploadFile`: Watermark\n    fmt.Fprintf(os.Stdout, \"Response from `Watermarks.UploadFile`: %v\", res)\n}\n"
        - language: node
          code: "// First install the \"@api.video/nodejs-client\" npm package\n// Documentation: https://github.com/apivideo/api.video-nodejs-client/blob/main/doc/api/WatermarksApi.md#upload\n\nconst client = new ApiVideoClient({ apiKey: \"YOUR_API_KEY\" });\n\n// Upload a watermark\nconst watermark = await client.watermarks.upload('test/data/test.jpg');\n\n// create a video with watermark\nconst watermarkVideo = await client.videos.create({\n  title: 'Nodejs - watermark',\n  watermark: {\n    id: watermark.watermarkId,\n    top: '0px',\n    left: '0px',\n    width: '100px',\n    height: '100px',\n  },\n});\n"
        - language: php
          code: "<?php\n// First install the api client: \"composer require api-video/php-api-client\"\n// Documentation: https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/WatermarksApi.md#upload\n\nrequire __DIR__ . '/vendor/autoload.php';\n\n$client = new \\ApiVideo\\Client\\Client(\n    'https://ws.api.video',\n    'YOUR_API_KEY',\n    new \\Symfony\\Component\\HttpClient\\Psr18Client()\n);\n\n// upload the watermark\n$watermark = $client->watermarks()->upload(new SplFileObject(__DIR__ . '/watermark.png'));\n\n// create a new video with the watermark\n$video = $client->videos()->create((new VideoCreationPayload())\n        ->setWatermark((new VideoWatermark())\n                ->setId($watermark->getWatermarkId())\n                ->setTop(\"0px\")\n                ->setLeft(\"0px\")\n                ->setWidth(\"100px\")\n                ->setHeight(\"100px\"))\n        ->setTitle(\"Test PHP watermark\")\n);\n\n// upload the video\n$client->videos()->upload($video->getVideoId(), new SplFileObject(__DIR__ . '/558k.mp4')); \n"
        - language: python
          code: "# First install the api client with \"pip install api.video\"\n# Documentation: https://github.com/apivideo/api.video-python-client/blob/main/docs/WatermarksApi.md#upload\n\nimport apivideo\nfrom apivideo.api import videos_api\nfrom apivideo.model.bad_request import BadRequest\nfrom apivideo.model.not_found import NotFound\nfrom pprint import pprint\n\n# Enter a context with an instance of the API client\nwith apivideo.AuthenticatedApiClient(__API_KEY__) as api_client:\n    # Create an instance of the API class\n    api_instance = videos_api.WatermarksApi(api_client)\n    file = open('/path/to/file', 'rb') # file_type | The watermark image.\n\n    # example passing only required values which don't have defaults set\n    try:\n        # Upload a watermark\n        api_response = api_instance.upload(file)\n        pprint(api_response)\n    except apivideo.ApiException as e:\n        print(\"Exception when calling WatermarksApi->upload: %s\\\n\" % e)\n"
        - language: java
          code: "// First add the \"video.api:java-api-client\" maven dependency to your project\n// Documentation: https://github.com/apivideo/api.video-java-client/blob/main/docs/WatermarksApi.md#upload\n\nimport video.api.client.ApiVideoClient;\nimport video.api.client.api.ApiException;\nimport video.api.client.api.models.*;\nimport video.api.client.api.clients.WatermarksApi;\nimport java.util.*;\n\npublic class Example {\n public static void main(String[] args) {\n   ApiVideoClient client = new ApiVideoClient(\"YOUR_API_KEY\");\n   // if you rather like to use the sandbox environment:\n   // ApiVideoClient client = new ApiVideoClient(\"YOUR_SANDBOX_API_KEY\", ApiVideoClient.Environment.SANDBOX);\n\n   WatermarksApi watermarkApi = apiClient.watermarks();\n\n   File file = new File(\"/path/to/file\"); // The watermark image.\n\n   try {\n     Watermark result = watermarkApi.upload(file);\n     System.out.println(result);\n   } catch (ApiException e) {\n     System.err.println(\"Exception when calling WatermarksApi#upload\");\n     System.err.println(\"Status code: \" + e.getCode());\n     System.err.println(\"Reason: \" + e.getMessage());\n     System.err.println(\"Response headers: \" + e.getResponseHeaders());\n     e.printStackTrace();\n   }\n }\n}\n"
        - language: csharp
          code: "// First add the \"ApiVideo\" NuGet package to your project\n// Documentation: https://github.com/apivideo/api.video-csharp-client/blob/main/docs/WatermarksApi.md#upload\n\nusing System.Diagnostics;\nusing ApiVideo.Client;\n\nnamespace Example\n{\n    public class uploadWatermarkExample\n    {\n        public static void Main()\n        {\n            var basePath = ApiVideoClient.Client.Environment.SANDBOX;\n            var apiKey = \"YOUR_API_KEY\";\n\n            var apiInstance = new ApiVideoClient(apiKey,basePath);\n\n            var file = File.OpenRead(\"watermark.jpg\");  // The watermark image.\n            var apiWatermarksInstance = apiInstance.Watermarks();\n\n            try\n            {\n                // Upload a watermark\n                Video result = apiWatermarksInstance.upload(videoId, file);\n                Debug.WriteLine(result);\n            }\n            catch (ApiException  e)\n            {\n                Debug.Print(\"Exception when calling WatermarksApi.upload: \" + e.Message );\n                Debug.Print(\"Status Code: \"+ e.ErrorCode);\n                Debug.Print(e.StackTrace);\n            }\n        }\n    }\n}\n"
        - language: swift
          code: '// First install the api client: https://github.com/apivideo/api.video-swift-client#getting-started

            // Documentation: https://github.com/apivideo/api.video-swift-client/blob/main/docs/WatermarksAPI.md#upload

            '
    get:
      tags:
      - Watermarks
      summary: List all watermarks
      description: List all watermarks associated with your workspace.
      operationId: LIST-watermarks
      x-client-action: list
      parameters:
      - name: sortBy
        in: query
        description: 'Allowed: createdAt. You can search by the time watermark were created at.'
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: createdAt
      - name: sortOrder
        in: query
        description: 'Allowed: asc, desc. asc is ascending and sorts from A to Z. desc is descending and sorts from Z to A.'
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: asc
      - $ref: '#/components/parameters/current-page'
      - $ref: '#/components/parameters/page-size'
      responses:
        '200':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/watermarks-list-response'
              examples:
                response:
                  value:
                    data:
                    - watermarkId: watermark_1BWr2L5MTQwxGkuxKjzh6i
                      createdAt: '2019-12-16T08:25:51+00:00'
                    - watermarkId: watermark_3BWC2L5MTQwxGkuxKjzh7g
                      createdAt: '2019-12-16T08:25:51+00:00'
                    pagination:
                      currentPage: 1
                      pageSize: 25
                      pagesTotal: 1
                      itemsTotal: 11
                      currentPageItems: 11
                      links:
                      - rel: self
                        uri: https://ws.api.video/watermarks?currentPage=1
                      - rel: first
                        uri: https://ws.api.video/watermarks?currentPage=1
                      - rel: last
                        uri: https://ws.api.video/watermarks?currentPage=1
        '400':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad-request'
              examples:
                response:
                  value:
                    title: This parameter is out of the allowed range of values.
                    name: page
                    status: 400
                    range:
                      min: 1
                    problems:
                    - title: This parameter is out of the allowed range of values.
                      name: page
                      range:
                        min: 1
                    - title: This parameter is out of the allowed range of values.
                      name: pageSize
                      range:
                        min: 10
                        max: 100
        '429':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/too-many-requests'
              examples:
                Too many requests:
                  value:
                    type: https://docs.api.video/reference/too-many-requests
                    title: Too many requests.
                    status: 429
      security:
      - apiKey: []
      x-group-parameters: true
      x-client-paginated: true
      x-doctave:
        code-samples:
        - language: node
          code: "// First install the \"@api.video/nodejs-client\" npm package\n// Documentation: https://github.com/apivideo/api.video-nodejs-client/blob/main/doc/api/WatermarksApi.md#list\n\nconst client = new ApiVideoClient({ apiKey: \"YOUR_API_KEY\" }); \n\n// retrieve the first page of all watermarks\nconst watermarks = await client.watermarks.list({});\n\n// retrieve the 5 first watermarks, ordered by creation date\nconst watermarks2 = await client.watermarks.list({});\ncreatedAt\n"
        - language: csharp
          code: '// First add the "ApiVideo" NuGet package to your project

            // Documentation: https://github.com/apivideo/api.video-csharp-client/blob/main/docs/WatermarksApi.md#list

            '
        - language: go
          code: '// First install the go client with "go get github.com/apivideo/api.video-go-client"

            // Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/WatermarksApi.md#list

            '
        - language: java
          code: '// First add the "video.api:java-api-client" maven dependency to your project

            // Documentation: https://github.com/apivideo/api.video-java-client/blob/main/docs/WatermarksApi.md#list

            '
        - language: php
          code: "<?php\n// First install the api client: \"composer require api-video/php-api-client\"\n// Documentation: https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/WatermarksApi.md#list\n\nrequire __DIR__ . '/vendor/autoload.php';\n\n$client = new \\ApiVideo\\Client\\Client(\n    'https://ws.api.video',\n    'YOUR_API_KEY',\n    new \\Symfony\\Component\\HttpClient\\Psr18Client()\n); \n\n// retrieve the first page of all watermarks\n$watermarks =  client->watermarks()->list();\n\n// retrieve the 5 first watermarks, ordered by creation date\n$watermarks2 = $client->watermarks()->list(array(\n    'pageSize' => 5,\n    'sortBy' => 'createdAt',\n    'sortOrder' => 'asc'\n)); "
        - language: python
          code: '# First install the api client with "pip install api.video"

            # Documentation: https://github.com/apivideo/api.video-python-client/blob/main/docs/WatermarksApi.md#list

            '
        - language: swift
          code: '// First install the api client: https://github.com/apivideo/api.video-swift-client#getting-started

            // Documentation: https://github.com/apivideo/api.video-swift-client/blob/main/docs/WatermarksAPI.md#list

            '
  /watermarks/{watermarkId}:
    delete:
      tags:
      - Watermarks
      summary: Delete a watermark
      description: Delete a watermark.
      operationId: DELETE_watermark
      parameters:
      - name: watermarkId
        in: path
        description: The watermark ID for the watermark you want to delete.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: watermark_1BWr2L5MTQwxGkuxKjzh6i
      responses:
        '204':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: No Content
        '404':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/not-found'
              examples:
                response:
                  value:
                    type: https://docs.api.video/reference/resource-not-found
                    title: The requested resource was not found.
                    name: watermarkId
                    status: 404
        '429':
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: The request limit per minute.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of available requests left for the current time window.
            X-RateLimit-Retry-After:
              schema:
                type: integer
              description: The number of seconds left until the current rate limit window resets.
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/too-many-requests'
              examples:
                Too many requests:
                  value:
                    type: https://docs.api.video/reference/too-many-requests
                    title: Too many requests.
                    status: 429
      security:
      - apiKey: []
      x-client-action: delete
      x-doctave:
        code-samples:
        - language: node
          code: "// First install the \"@api.video/nodejs-client\" npm package\n// Documentation: https://github.com/apivideo/api.video-nodejs-client/blob/main/doc/api/WatermarksApi.md#delete\n\nconst client = new ApiVideoClient({ apiKey: \"YOUR_API_KEY\" }); \n\nconst watermarkId = 'watermark_1Bji68oeAAwR44dAb5ZhML'; // The watermark ID for the watermark you want to delete.\n\nclient.watermarks.delete(watermarkId);"
        - language: csharp
          code: '// First add the "ApiVideo" NuGet package to your project

            // Documentation: https://github.com/apivideo/api.video-csharp-client/blob/main/docs/WatermarksApi.md#delete

            '
        - language: go
          code: '// First install the go client with "go get github.com/apivideo/api.video-go-client"

            // Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/WatermarksApi.md#delete

            '
        - language: java
          code: '// First add the "video.api:java-api-client" maven dependency to your project

            // Documentation: https://github.com/apivideo/api.video-java-client/blob/main/docs/WatermarksApi.md#delete

            '
        - language: php
          code: "<?php\n// First install the api client: \"composer require api-video/php-api-client\"\n// Documentation: https://github.com/apivideo/api.video-php-client/blob/main/docs/Api/WatermarksApi.md#list\n\nrequire __DIR__ . '/vendor/autoload.php';\n\n$client = new \\ApiVideo\\Client\\Client(\n    'https://ws.api.video',\n    'YOUR_API_KEY',\n    new \\Symfony\\Component\\HttpClient\\Psr18Client()\n); \n\n$watermarkId = 'watermark_1Bji68oeAAwR44dAb5ZhML'; // The watermark ID for the watermark you want to delete.\n\n$client->watermarks->delete(watermarkId);"
        - language: python
          code: '# First install the api client with "pip install api.video"

            # Documentation: https://github.com/apivideo/api.video-python-client/blob/main/docs/WatermarksApi.md#delete

            '
        - language: swift
          code: '// First install the api client: https://github.com/apivideo/api.video-swift-client#getting-started

            // Documentation: https://github.com/apivideo/api.video-swift-client/blob/main/docs/WatermarksAPI.md#delete

            '
components:
  parameters:
    current-page:
      name: currentPage
      in: query
      description: 'Choose the number of search results to return per page. Minimum value: 1'
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 1
      example: 2
    page-size:
      name: pageSize
      in: query
      description: Results per page. Allowed values 1-100, default is 25.
      required: false
      style: form
      explode: true
      schema:
        type: integer
        default: 25
      example: 30
  schemas:
    watermarks-list-response:
      title: Watermarks
      required:
      - data
      - pagination
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/watermark'
        pagination:
          $ref: '#/components/schemas/pagination'
    watermark:
      title: Watermark
      type: object
      properties:
        watermarkId:
          type: string
          description: The unique identifier of the watermark.
          example: watermark_1BWr2L5MTQwxGkuxKjzh6i
        createdAt:
          type: string
          format: date-time
          description: When the watermark was created, presented in ATOM UTC format.
          example: '2019-06-24T11:45:01+00:00'
    bad-request:
      title: BadRequest
      type: object
      properties:
        type:
          description: A link to the error documentation.
          type: string
        title:
          description: A description of the error that occurred.
          type: string
        name:
          description: The name of the parameter that caused the error.
          type: string
        status:
          description: The HTTP status code.
          type: integer
        problems:
          description: Returns any additional problems in the request in an array of objects.
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/additional-bad-request-errors'
    too-many-requests:
      title: TooManyRequests
      type: object
      properties:
        type:
          description: A link to the error documentation.
          type: string
        title:
          description: A description of the error that occurred.
          type: string
        status:
          description: The HTTP status code.
          type: integer
    pagination-link:
      title: PaginationLink
      type: object
      properties:
        rel:
          type: string
        uri:
          type: string
          format: uri
    watermark-upload-payload:
      title: WatermarkUploadPayload
      required:
      - file
      type: object
      properties:
        file:
          type: string
          description: The `.jpg` or `.png` image to be added as a watermark.
          format: binary
    additional-bad-request-errors:
      title: BadRequest
      type: object
      properties:
        type:
          description: A link to the error documentation.
          type: string
        title:
          description: A description of the error that occurred.
          type: string
        name:
          description: The name of the parameter that caused the error.
          type: string
        status:
          description: The HTTP status code.
          type: integer
    pagination:
      title: Pagination
      required:
      - links
      type: object
      properties:
        itemsTotal:
          type: integer
          description: Total number of items that exist.
          readOnly: true
        pagesTotal:
          type: integer
          description: Number of items listed in the current page.
          readOnly: true
        pageSize:
          type: integer
          description: Maximum number of item per page.
          readOnly: true
        currentPage:
          type: integer
          description: The current page index.
          readOnly: true
        currentPageItems:
          type: integer
          description: The number of items on the current page.
          readOnly: true
        links:
          type: array
          items:
            $ref: '#/components/schemas/pagination-link'
      example:
        itemsTotal: 123
        pagesTotal: 7
        pageSize: 20
        currentPage: 3
        currentPageItems: 20
        links:
          first:
            rel: first
            uri: /videos/search?currentPage=1&pageSize=20
          previous:
            rel: previous
            uri: /videos/search?currentPage=2&pageSize=20
          next:
            rel: next
            uri: /videos/search?currentPage=4&pageSize=20
          last:
            rel: last
            uri: /videos/search?currentPage=6&pageSize=20
    not-found:
      title: NotFound
      type: object
      properties:
        type:
          description: A link to the error documentation.
          type: string
        title:
          description: A description of the error that occurred.
          type: string
        name:
          description: The name of the parameter that caused the error.
          type: string
        status:
          description: The HTTP status code.
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: http
      scheme: basic
x-stoplight:
  id: ybzk39fiws46g
x-client-base-paths:
  production: https://ws.api.video
  sandbox: https://sandbox.api.video
x-doctave:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true
  samples-languages:
  - curl
  - go
  - node
  - php
  - python
x-provenance:
  method: harvested
  publisher: API.Video
  source: https://docs.api.video/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)