VideoCreationPayload

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/api-video/json-schema/api-video-video-creation-payload-schema.json",
  "title": "VideoCreationPayload",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/api-video-videos-api-openapi.yml#/components/schemas/video-creation-payload",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of your new video."
    },
    "description": {
      "type": "string",
      "description": "A brief description of your video."
    },
    "source": {
      "type": "string",
      "description": "You can either add a video already on the web, by entering the URL of the video, or you can also enter the `videoId` of one of the videos you already have on your api.video acccount, and this will generate a copy of your video. Creating a copy of a video can be especially useful if you want to keep your original video and trim or apply a watermark onto the copy you would create."
    },
    "public": {
      "type": "boolean",
      "description": "Default: True. If set to `false` the video will become private. More information on private videos can be found [here](https://docs.api.video/delivery/video-privacy-access-management)",
      "default": true
    },
    "panoramic": {
      "type": "boolean",
      "description": "Indicates if your video is a 360/immersive video.",
      "default": false
    },
    "mp4Support": {
      "type": "boolean",
      "description": "Enables mp4 version in addition to streamed version.",
      "default": true
    },
    "playerId": {
      "type": "string",
      "description": "The unique identification number for your video player."
    },
    "tags": {
      "type": "array",
      "description": "A list of tags you want to use to describe your video.",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "type": "array",
      "description": "A list of key value pairs that you use to provide metadata for your video.",
      "items": {
        "$ref": "#/$defs/metadata"
      }
    },
    "clip": {
      "$ref": "#/$defs/video-clip"
    },
    "watermark": {
      "$ref": "#/$defs/video-watermark"
    },
    "language": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "ar",
        "ca",
        "cs",
        "da",
        "de",
        "el",
        "en",
        "es",
        "fa",
        "fi",
        "fr",
        "he",
        "hi",
        "hr",
        "hu",
        "it",
        "ja",
        "ko",
        "ml",
        "nl",
        "nn",
        "no",
        "pl",
        "pt",
        "ru",
        "sk",
        "sl",
        "te",
        "tr",
        "uk",
        "ur",
        "vi",
        "zh"
      ],
      "description": "Use this parameter to set the language of the video. When this parameter is set, the API creates a transcript of the video using the language you specify. You must use the [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format.\n\n`language` is a permanent attribute of the video. You can update it to another language using the [`PATCH /videos/{videoId}`](https://docs.api.video/reference/api/Videos#update-a-video-object) operation. This triggers the API to generate a new transcript using a different language."
    },
    "transcript": {
      "type": "boolean",
      "description": "Use this parameter to enable transcription. \n\n- When `true`, the API generates a transcript for the video.\n- The default value is `false`.\n- If you define a video language using the `language` parameter, the API uses that language to transcribe the video. If you do not define a language, the API detects it based on the video. \n- When the API generates a transcript, it will be available as a caption for the video."
    },
    "transcriptSummary": {
      "type": "boolean",
      "description": "Use this parameter to enable summarization. We recommend using this parameter together with `transcript: true`.\n\n- When `true`, the API generates a summary for the video, based on the transcription.\n- The default value is `false`.\n- If you define a video language using the `language` parameter, the API uses that language to summarize the video. If you do not define a language, the API detects it based on the video."
    },
    "transcriptSummaryAttributes": {
      "description": "Use this parameter to define the elements of a summary that you want to generate. If you do not define this parameter, the API generates a full summary with all attributes. The possible values are `abstract` and `takeaways`.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "abstract",
          "takeaways"
        ]
      }
    }
  },
  "required": [
    "title"
  ],
  "$defs": {
    "metadata": {
      "title": "Metadata",
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "The constant that defines the data set."
        },
        "value": {
          "type": "string",
          "description": "A variable which belongs to the data set."
        }
      },
      "x-client-all-args-constructor": true
    },
    "video-clip": {
      "type": "object",
      "description": "Use this object to create a smaller clip from a video you upload. \n- You can only create video clips in the same request where you create the video container.\n- You cannot update the starting or ending timestamps of a video clip after you created the video container.\n- When you upload a video file into a container where you defined a starting and ending timestamp, the API trims the video according to those timestamps to create a clip.",
      "properties": {
        "startTimecode": {
          "type": "string",
          "description": "The timestamp that defines the beginning of the video clip you want to create. The value must follow the `HH:MM:SS` format.",
          "pattern": "^(?:\\d{2,3}:[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3}|\\:\\d{1,2})?|\\d{1,7})$"
        },
        "endTimecode": {
          "type": "string",
          "description": "The timestamp that defines the end of the video clip you want to create. The value must follow the `HH:MM:SS` format.",
          "pattern": "^(?:\\d{2,3}:[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3}|\\:\\d{1,2})?|\\d{1,7})$"
        }
      }
    },
    "video-watermark": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "id of the watermark"
        },
        "top": {
          "type": "string",
          "description": "Distance expressed in px or % between the top-border of the video and the watermark-image."
        },
        "left": {
          "type": "string",
          "description": "Distance expressed in px or % between the left-border of the video and the watermark-image."
        },
        "bottom": {
          "type": "string",
          "description": "Distance expressed in px or % between the bottom-border of the video and the watermark-image."
        },
        "right": {
          "type": "string",
          "description": "Distance expressed in px or % between the right-border of the video and the watermark-image."
        },
        "width": {
          "type": "string",
          "description": "Width of the watermark-image relative to the video if expressed in %. Otherwise a fixed width. NOTE: To keep intrinsic watermark-image width use `initial`."
        },
        "height": {
          "type": "string",
          "description": "Height of the watermark-image relative to the video if expressed in %. Otherwise a fixed height. NOTE: To keep intrinsic watermark-image height use `initial`."
        },
        "opacity": {
          "type": "string",
          "description": "Opacity expressed in % only to specify the degree of the watermark-image transparency with the video."
        }
      }
    }
  }
}