--- title: "카테고리 파일 추가" slug: "vodstation-category-addfiles" tags: ["Category", "VOD Station"] updated: 2026-09-17T09:16:48Z published: 2026-09-17T09:16:48Z canonical: "api.ncloud-docs.com/vodstation-category-addfiles" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 카테고리 파일 추가 Classic/VPC 환경에서 이용 가능합니다. 카테고리에 인코딩 파일을 추가합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | PUT | /api/v2/category/{categoryId}/add-files | ### 요청 헤더 VOD Station API에서 공통으로 사용하는 헤더에 대한 정보는 [VOD Station 요청 헤더](/docs/vodstation#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 경로 파라미터 요청 경로 파라미터에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `categoryId` | String | Required | 카테고리 아이디 - [카테고리 목록 조회](/docs/vodstation-category-list) 참조 | ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `bucketName` | String | Conditional | 입력 파일이 저장되어 있는 버킷 이름 - `pathList`를 설정하는 경우, 필수 입력 - `httpDownloadURL`과 함께 사용 불가 - `httpDownloadURL`을 사용하지 않는 경우, 필수 입력 | | `pathList` | Array | Conditional | 파일명을 포함한 입력 파일의 버킷 상세 경로 - 100개 이내로 입력 - `bucketName`을 설정하는 경우, 필수 입력 - `httpDownloadURL`과 함께 사용 불가 - `bucketName`과 `pathList`를 사용하지 않는 경우, 필수 입력 | | `httpDownloadUrlList` | Array | Conditional | 파일명을 포함한 입력 파일의 HTTP URL 경로 - HTTP URL 형식으로 100개 이내 입력 - `bucketName`, `pathList`와 함께 사용 불가 - 입력 가능 확장자: AVI, MOV, MP4, MP3, 3GP, MPG, MPEG, M4V, VOB, WMV, ASF, MKV, FLV, WEBM, GIF, AV1, MXF - 출력 파일의 공개 범위가 비공개인 경우, 접근 불가능 가능성 존재 | | `notification` | String | Optional | 입력 파일에 대한 콜백(Callback) URL 설정 - 설정 시 추가하는 인코딩 파일에 한해 카테고리의 콜백 설정보다 우선 적용 | | `output` | Object | Optional | 입력 파일에 대한 출력 설정 | | `output.bucketName` | String | Required | 출력 파일을 저장할 버킷 이름 | | `output.filePath` | String | Required | 출력 파일을 저장할 상세 경로 - 영문자, 숫자, 특수문자를 조합하여 1~256자 이내로 입력 - 특수문자 '<, >, :, ", /, \, ?, *, %' 입력 불가 | | `output.thumbnailBucketName` | String | Optional | 섬네일 추출 파일을 저장할 버킷 이름 - 미입력 시 `output.bucketName` 설정을 따름 | | `output.thumbnailFilePath` | String | Optional | 섬네일 추출 파일을 저장할 상세 경로 - 미입력 시 `output.filePath` 설정을 따름 | | `output.accessControl` | String | Optional | 출력 파일 공개 범위 - `PUBLIC_READ` \| `PRIVATE` (기본값) - `PUBLIC_READ`: 공개 - `PRIVATE`: 비공개 | | `output.thumbnailAccessControl` | String | Optional | 추출 섬네일 공개 범위 - `PUBLIC_READ` \| `PRIVATE` (기본값) - `PUBLIC_READ`: 공개 - `PRIVATE`: 비공개 | | `output.withoutCategoryName` | Boolean | Optional | 출력 경로에 카테고리 이름의 폴더 생성 여부 - `true` \| `false` (기본값) - `true`: 생성 - `false`: 생성 안 함 | | `setAdvancedOptions` | Boolean | Optional | 고급 설정 여부 - `true` \| `false` (기본값) - `true`: 설정 - `false`: 설정 안 함 | | `advancedOptions` | Object | Optional | 고급 설정 | | `advancedOptions.trimming` | Object | Optional | 출력 파일 트리밍(재생 구간) 설정 | | `advancedOptions.trimming.startTimeCode` | String | Required | 트리밍 시작 시점 - HH:MM:SS.S 형식 | | `advancedOptions.trimming.endTimeCode` | String | Required | 트리밍 종료 시점 - HH:MM:SS.S 형식 - `advancedOptions.trimming.startTimeCode`보다 작은 값 입력 불가 | | `advancedOptions.imageOverlay` | Object | Optional | 이미지 오버레이(삽입) 설정 | | `advancedOptions.imageOverlay.input` | Object | Required | 이미지 설정 | | `advancedOptions.imageOverlay.input.bucketName` | String | Required | 이미지가 저장되어 있는 버킷 이름 | | `advancedOptions.imageOverlay.input.filePath` | String | Required | 파일명을 포함한 이미지의 상세 경로 | | `advancedOptions.imageOverlay.position` | Object | Required | 이미지 위치 설정 | | `advancedOptions.imageOverlay.position.x` | Integer | Required | x축 위치(픽셀) | | `advancedOptions.imageOverlay.position.y` | Integer | Required | y축 위치(픽셀) | | `advancedOptions.imageOverlay.size` | Object | Required | 이미지 크기 설정 | | `advancedOptions.imageOverlay.size.width` | Integer | Required | 이미지 너비(픽셀) | | `advancedOptions.imageOverlay.size.height` | Integer | Required | 이미지 높이(픽셀) | ### 요청 예시 요청 예시는 다음과 같습니다. ``` curl --location --request PUT 'https://vodstation.apigw.ntruss.com/api/v2/category/*****/add-files' \ --header 'x-ncp-apigw-timestamp: {Timestamp}' \ --header 'x-ncp-iam-access-key: {Access Key}' \ --header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \ --data '{ "httpDownloadUrlList": [ "https://kr.object.ncloudstorage.com/station-000-input/VODStation2.mp4" ], "notification": "https://example.com/callback", "output": { "bucketName": "station-000", "filePath": "/", "thumbnailBucketName": "station-000", "thumbnailFilePath": "/thumbnail", "accessControl": "PUBLIC_READ", "thumbnailAccessControl": "PUBLIC_READ", "withoutCategoryName": false }, "setAdvancedOptions": true, "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 } } } }' ``` ## 응답 응답 형식을 설명합니다. ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `content` | Array | - | 카테고리에 인코딩 파일 추가 결과: [content](/docs/vodstation-category-addfiles#content) | #### `content` `content`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `id` | Integer | - | 파일 인코딩 작업 아이디 - 콜백 메시지의 `fileId`와 동일 - [카테고리 콜백 사용](/docs/vodstation-category-callback) 참조 - 콜백 기능(`notification`)을 사용하지 않는 경우, [카테고리 상태 정보 조회](/docs/vodstation-status-info-list) 시 사용될 수 있으므로 별도 기록 권장 | | `status` | String | - | 파일 인코딩 상태 - `COMPLETE` \| `WAITING` \| `RUNNING` \| `FAILURE` - `COMPLETE`: 완료 - `WAITING`: 대기 - `RUNNING`: 진행 중 - `FAILURE`: 실패 - `CANCELED`: 취소 | | `output` | Object | Required | 카테고리 출력 설정 | | `output.bucketName` | String | Required | 출력 파일을 저장할 버킷 이름 | | `output.filePath` | String | Required | 출력 파일을 저장할 상세 경로 | | `output.accessControl` | String | - | 출력 파일 공개 범위 - `PUBLIC_READ` \| `PRIVATE` - `PUBLIC_READ`: 공개 - `PRIVATE`: 비공개 | | `output.thumbnailAccessControl` | String | - | 추출 섬네일 공개 범위 - `PUBLIC_READ` \| `PRIVATE` - `PUBLIC_READ`: 공개 - `PRIVATE`: 비공개 | | `output.withoutCategoryName` | Boolean | - | 출력 경로에 카테고리 이름의 폴더 생성 여부 - `true` \| `false` - `true`: 생성 - `false`: 생성 안 함 | | `output.thumbnailOutput` | Object | - | 섬네일 추출 설정 정보 | | `output.thumbnailOutput.bucketName` | String | - | 섬네일 추출 파일을 저장할 버킷 이름 | | `output.thumbnailOutput.filePath` | String | - | 섬네일 추출 파일을 저장할 상세 경로 | | `setAdvancedOptions` | Boolean | - | 고급 설정 여부 | | `advancedOptions` | Object | - | 고급 설정 정보 - `setAdvancedOptions`가 `true`인 경우, 표시 | | `advancedOptions.trimming` | Object | - | 출력 파일 트리밍(재생 구간) 설정 | | `advancedOptions.trimming.startTimeCode` | String | - | 트리밍 시작 시점 - HH:MM:SS.S 형식 | | `advancedOptions.trimming.endTimeCode` | String | - | 트리밍 종료 시점 - HH:MM:SS.S 형식 | | `advancedOptions.imageOverlay` | Object | - | 이미지 오버레이(삽입) 설정 | | `advancedOptions.imageOverlay.input` | Object | - | 이미지 설정 정보 | | `advancedOptions.imageOverlay.input.bucketName` | String | - | 이미지가 저장되어 있는 버킷 이름 | | `advancedOptions.imageOverlay.input.filePath` | String | - | 파일명을 포함한 이미지의 상세 경로 | | `advancedOptions.imageOverlay.size` | Object | - | 이미지 크기 정보 | | `advancedOptions.imageOverlay.size.width` | Integer | - | 이미지 너비(픽셀) | | `advancedOptions.imageOverlay.size.height` | Integer | - | 이미지 높이(픽셀) | | `advancedOptions.imageOverlay.position` | Object | - | 삽입할 이미지 위치 설정 | | `advancedOptions.imageOverlay.position.x` | Integer | - | x축 위치(픽셀) | | `advancedOptions.imageOverlay.position.y` | Integer | - | y축 위치(픽셀) | | `httpDownloadUrl` | String | - | 외부로부터 다운 받을 HTTP URL | ### 응답 상태 코드 VOD Station API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [VOD Station 응답 상태 코드](/docs/vodstation#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오. ### 응답 예시 응답 예시는 다음과 같습니다. ``` { "content": [ { "id": *******, "status": "WAITING", "output": { "bucketName": "station-000", "filePath": "/", "accessControl": "PUBLIC_READ", "thumbnailAccessControl": "PUBLIC_READ", "withoutCategoryName": false, "thumbnailOutput": { "bucketName": "station-000", "filePath": "/thumbnail" } }, "setAdvancedOptions": true, "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 } } }, "httpDownloadUrl": "https://kr.object.ncloudstorage.com/station-000-input/VODStation2.mp4" } ] } ```