Create category

Available in Classic and VPC

Create a category. Encoding video files can be done by creating a category and then adding the source file.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/api/v2/category

Request headers

For information about the headers common to all VOD Station APIs, see VOD Station request headers.

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`name`	String	Required	Category name Folder with category name automatically created in `output.bucketName`
`encodingOptions`	Array	Optional	Encoding options to set for the category See Get encoding option list. When using a template, see Get template. If you enter a value of `encodingOptionTemplateId`, you can't set any other ID other than the `encodingOptionId` contained in the template ID.
`encodingOptionTemplateId`	Integer	Optional	Encoding template ID See Get template. Set the `encodingOptionId` value contained in the corresponding template ID to the `encodingOptions` value.
`thumbnail`	Boolean	Optional	Thumbnail extraction settings `true` \| `false` (default) `true`: Enable `false`: Disable
`notificationUrl`	String	Optional	Callback URL See Use category callback.
`output`	Object	Required	Category output settings
`output.bucketName`	String	Required	Bucket name to save the output file
`output.filePath`	String	Required	Detailed path to save the output file Enter 1 to 256 characters, including English letters, numbers, and special characters. Special characters "<', '>", ":", """, "/", "", "?", "*", "%" can't be used.
`output.thumbnailBucketName`	String	Optional	Name of bucket to store thumbnail extract files in If not entered, the `output.bucketName` setting is followed.
`output.thumbnailFilePath`	String	Optional	Detailed path to store thumbnail extract files to If not entered, the `output.filePath` setting is followed.
`output.accessControl`	String	Optional	Output file disclosure scope `PUBLIC_READ` \| `PRIVATE` (default) `PUBLIC_READ`: Public read `PRIVATE`: Private
`output.thumbnailAccessControl`	String	Optional	Extracted thumbnail disclosure scope `PUBLIC_READ` \| `PRIVATE` (default) `PUBLIC_READ`: Public read `PRIVATE`: Private
`advancedOptions`	Object	Optional	Advanced settings
`advancedOptions.trimming`	Object	Optional	Output file trimming (playback section) settings
`advancedOptions.trimming.startTimeCode`	String	Required	Trimming start point (HH:MM:SS.S)
`advancedOptions.trimming.endTimeCode`	String	Required	Trimming end point (HH:MM:SS.S) Value smaller than `advancedOptions.trimming.startTimeCode` can't be entered.
`advancedOptions.imageOverlay`	Object	Optional	Image overlay (insertion) settings
`advancedOptions.imageOverlay.input`	Object	Required	Image settings
`advancedOptions.imageOverlay.input.bucketName`	String	Required	Name of the bucket where the image is saved
`advancedOptions.imageOverlay.input.filePath`	String	Required	Detailed path of the image including the file name
`advancedOptions.imageOverlay.position`	Object	Required	Image location settings
`advancedOptions.imageOverlay.position.x`	Integer	Required	Location of x-axis (pixel)
`advancedOptions.imageOverlay.position.y`	Integer	Required	Location of y-axis (pixel)
`advancedOptions.imageOverlay.size`	Object	Required	Image size settings
`advancedOptions.imageOverlay.size.width`	Integer	Required	Image width (pixel)
`advancedOptions.imageOverlay.size.height`	Integer	Required	Image height (pixel)

Request example

The request example is as follows:

curl --location --request POST 'https://vodstation.apigw.ntruss.com/api/v2/category' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
--data '{
    "name": "VOD-Category",
    "encodingOptions": [1, 2, 3],
    "encodingOptionTemplateId": 1,
    "thumbnail": true,
    "notificationUrl": "https://example.com/vodstation/callback",
    "output": {
        "bucketName": "station-000",
        "filePath": "/",
        "thumbnailBucketName": "station-000",
        "thumbnailFilePath": "/thumbnail",
        "accessControl": "PUBLIC_READ",
        "thumbnailAccessControl": "PUBLIC_READ"
    },
    "advancedOptions": {
        "trimming": {
            "startTimeCode": "00:00:00.0",
            "endTimeCode": "00:08:00.9"
        },
        "imageOverlay": {
            "input": {
                "bucketName": "station-000",
                "filePath": "/VODStation.png"
            },
            "position": {
                "x": 50,
                "y": 50
            },
            "size": {
                "width": 50,
                "height": 50
            }
        }
    }
}'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`content`	Object	-	Response result
`content.disabled`	Boolean	-	Whether Sub Account is disabled `true` \| `false` `true`: Disabled `false`: Enabled
`content.id`	Integer	-	Category ID
`content.name`	String	-	Category name
`content.thumbnail`	Boolean	-	Thumbnail extraction settings `true` \| `false` `true`: Extract `false`: Not extract
`content.notificationUrl`	String	-	Callback URL
`content.output`	Object	-	Output settings information
`content.output.bucketName`	String	-	Bucket name to save the output file
`content.output.filePath`	String	-	Detailed path to save the output file
`content.output.accessControl`	String	-	Disclosure scope of the output file
`content.output.thumbnailAccessControl`	String	-	Disclosure scope of the output thumbnail
`content.output.thumbnailBucketName`	String	-	Bucket name to save the output thumbnail
`content.output.thumbnailFilePath`	String	-	Detailed path to save the output thumbnail
`content.createTime`	Integer	-	Category creation date and time (millisecond) Unix timestamp format
`content.updateTime`	Integer	-	Category modification date and time (millisecond) Unix timestamp format
`content.status`	String	-	Category status `CREATED` \| `DELETED` \| `RUNNING` `CREATED`: Creation completed `DELETED`: Deletion completed `RUNNING`: In use
`content.advancedOptions`	Object	-	Advanced settings information
`content.advancedOptions.trimming`	Object	-	Output file trimming (playback section) settings
`content.advancedOptions.trimming.startTimeCode`	String	-	Trimming start point (HH:MM:SS.S)
`content.advancedOptions.trimming.endTimeCode`	String	-	Trimming end point (HH:MM:SS.S)
`content.advancedOptions.imageOverlay`	Object	-	Image overlay (insertion) settings
`content.advancedOptions.imageOverlay.input`	Object	-	Image settings information
`content.advancedOptions.imageOverlay.input.bucketName`	String	-	Name of the bucket where the image is saved
`content.advancedOptions.imageOverlay.input.filePath`	String	-	Detailed path of the image including the file name
`content.advancedOptions.imageOverlay.size`	Object	-	Image size information
`content.advancedOptions.imageOverlay.size.width`	Integer	-	Image width (pixel)
`content.advancedOptions.imageOverlay.size.height`	Integer	-	Image height (pixel)
`content.advancedOptions.imageOverlay.position`	Object	-	Location settings of image to be inserted
`content.advancedOptions.imageOverlay.position.x`	Integer	-	Location of x-axis (pixel)
`content.advancedOptions.imageOverlay.position.y`	Integer	-	Location of y-axis (pixel)
`content.encodingOptionTemplateId`	Integer	-	Encoding template ID

Response status codes

For information about the HTTP status codes common to all VOD Station APIs, see VOD Station response status codes.

Response example

The response example is as follows:

{
    "content": {
        "disabled": false,
        "id": *****,
        "name": "VOD-Category",
        "thumbnail": true,
        "notificationUrl": "https://example.com/vodstation/callback",
        "output": {
            "bucketName": "station-000",
            "filePath": "/",
            "accessControl": "PUBLIC_READ",
            "thumbnailAccessControl": "PUBLIC_READ",
            "thumbnailBucketName": "station-000",
            "thumbnailFilePath": "/thumbnail"
        },
        "createTime": 1755569622000,
        "updateTime": 1755569622000,
        "status": "CREATED",
        "advancedOptions": {
            "trimming": {
                "startTimeCode": "00:00:00.0",
                "endTimeCode": "00:08:00.9"
            },
            "imageOverlay": {
                "input": {
                    "bucketName": "station-000",
                    "filePath": "/VODStation.png"
                },
                "size": {
                    "width": 50,
                    "height": 50
                },
                "position": {
                    "x": 50,
                    "y": 50
                }
            }
        },
        "encodingOptionTemplateId": 1
    }
}