> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md).

# 비전 이벤트 비디오 업로드

작업 공간에 비디오 클립을 업로드하고 Vision 이벤트에 첨부하면 검토자가 대시보드에서 재생할 수 있습니다.

## 개요

비디오 클립에는 다음 상황이 발생한 순간 전후의 모습이 담겨 있습니다. [비전 이벤트](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events.md) 정지 이미지에는 놓칠 수 있는 장면입니다. 각 이벤트에 최대 4개의 클립을 첨부할 수 있습니다. 클립은 대시보드의 이벤트 세부정보 보기에서 재생됩니다(자세한 내용은 [이벤트 세부정보 보기](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#view-event-details)).

비디오는 최대 3GB의 MP4 또는 MOV 파일이어야 합니다. 비디오는 프로젝트가 아니라 워크스페이스에 업로드됩니다. 브라우저에서 재생할 수 있는 MP4 파일은 변환 없이 그대로 저장됩니다. 그 밖의 비디오는 H.264 MP4로 변환되며, 너무 긴 비디오는 변환에 실패할 수 있습니다.

[엣지 디바이스 백업](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/send-events.md#edge-device-backup) 에서는 디바이스에 녹화된 클립을 대신 업로드합니다. REST API를 통해 이벤트를 전송할 때는 이 페이지의 단계를 따르세요.

## HTTP API

비디오를 첨부하는 과정은 다음 세 단계로 이루어집니다.

1. 업로드를 준비합니다. 그러면 `videoId`,  `signedUrl`, 그리고 `requiredHeaders`.
2. 다음과 같이 동영상 파일을 전송합니다:  `PUT`  요청을  `signedUrl`에 보내고,  `requiredHeaders` URL은 60분 후 만료됩니다.
3. [이벤트를](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api) 다음 항목으로 `videoId` 의 `videos[].sourceId`.

이벤트를 만들기 전에 Roboflow가 동영상 처리를 완료할 때까지 기다릴 필요는 없습니다. 처리가 완료되는 즉시 대시보드에서 클립을 재생할 수 있습니다. 처리가 실패해도 이벤트는 유지되며, 대시보드에는 동영상이 실패한 것으로 표시됩니다. 파일이 전송되지 않으면 동영상은 `pending` 상태로 유지되고 대시보드에는 계속 처리 중인 것으로 표시됩니다.

필수 권한 범위: `vision-events:write` 또는 `device:update` 업로드를 준비하려면 `vision-events:read` 또는 `device:read` 상태를 읽거나 재생 URL을 가져오려면

### 업로드 준비

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/videos/prepare-upload" method="post" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

그런 다음 파일을 다음으로 전송합니다: `signedUrl`. 각 헤더를 다음에서 복사합니다. `requiredHeaders` 요청에 추가합니다:

```bash
curl -X PUT "SIGNED_URL" \
  -H "x-goog-content-length-range: 1,3221225472" \
  -H "x-goog-if-generation-match: 0" \
  --upload-file line-3-clip.mp4
```

다음 PUT 이후에는 `PUT`추가로 필요한 작업은 없습니다. 파일이 도착하면 Roboflow가 동영상 처리를 시작합니다.

### 비디오를 이벤트에 연결

이벤트의 `videoId` 를 `videos` 배열에 넣고 [Vision Event를 생성하거나](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api) 또는 [이벤트를 일괄 생성하세요](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/batch-create-vision-events.md).

이 엔드포인트로 준비한 비디오만 연결할 수 있습니다. 데이터셋 비디오 업로드 또는 다른 워크스페이스에서 가져온 `videoId` 는 이벤트에 저장되지만 경고가 반환되고 재생되지 않습니다.

### 업로드 상태 확인

`status` 는 `pending` 이며, 업로드를 준비한 시점부터 Roboflow가 파일 처리를 마칠 때까지 이 상태가 유지된 후 `uploaded` 또는 `failed`가 됩니다. 파일이 끝내 도착하지 않은 비디오는 `pending`.

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/videos/{videoId}" method="get" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 재생 URL 가져오기

[쿼리 결과에는](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/vision-events/query-events.md#http-api) 각 비디오의 `sourceId` 와 `label` 만 표시됩니다. 비디오를 재생하거나 다운로드할 수 있는 URL을 얻으려면 이 엔드포인트를 호출하세요. URL은 60분 동안 유효하며 `null` 입니다. 이는 `status` 가 `uploaded`가 될 때까지 적용됩니다. URL을 가진 사람은 누구나 클립을 재생할 수 있으므로 URL을 캐시하거나 공유하지 마세요.

{% openapi src="/files/07bb573a8b2a5a268b550bc4e2d87e5feae31c5d" path="/vision-events/videos/{videoId}/url" method="get" %}
[openapi.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}
