> 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/datasets/ko/create-and-upload/adding-data.md).

# 이미지, 비디오, 주석 업로드

이미지, 비디오, 주석을 Roboflow에 업로드합니다.

Roboflow로 모델을 학습하고 배포하는 첫 단계는 Project에 데이터를 업로드하는 것입니다.

먼저 [Project를 생성해야 합니다](https://docs.roboflow.com/datasets/ko/create-and-upload/create-a-project.md).

그러면 데이터를 업로드할 수 있는 웹 페이지로 이동합니다. 프로젝트 사이드바에서 제공되는 "데이터 업로드" 버튼을 통해서도 이 페이지에 액세스할 수 있습니다.

## 데이터 추가 방법

다음 방법으로 Roboflow 계정에 데이터를 추가할 수 있습니다.

* 웹 애플리케이션 사용: 이미지가 1,000개 미만인 데이터세트에 권장됩니다.
* 명령줄 사용: 이미지가 1,000개를 초과하는 데이터세트에 권장됩니다.
* Dataset Upload Workflow Block 사용: 이미 프로덕션 환경에 배포된 모델을 사용하는 Workflow에서 데이터를 수집할 때 권장됩니다.

{% hint style="info" %}
이미지가 AWS S3, Google Cloud Storage, Azure Blob Storage와 같은 클라우드 스토리지에 있다면 스크립트로 업로드하는 대신 기본 방법인 [Datasources](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.md) 와 Bucket Mirror를 사용하세요. Datasource는 이미지와 메타데이터를 워크스페이스로 자동 가져오고, 수집하고, 동기화합니다. 서명된 URL 업로드나 로컬 다운로드는 일회성 또는 임시 가져오기에만 사용하세요.
{% endhint %}

웹 애플리케이션과 명령줄에서 다음을 업로드할 수 있습니다.

* JPG, PNG, WEBP, AVIF, BMP 및 HEIC/HEIF 이미지.\*
* MOV 및 MP4 동영상.
* PDF 파일.
* 다음 중 하나의 형식으로 된 주석 [40개 이상의 지원 형식](https://roboflow.com/formats). 사용할 수 있는 형식은 Project 유형에 따라 다릅니다.

\**최대 크기는 30MB이며, 한 변당 최대 16,384픽셀, 전체 최대 178,956,970픽셀(약 1억 7,900만 픽셀)입니다.*

주석은 해당 이미지와 함께만 업로드할 수 있습니다. 데이터세트에 이미 가져온 이미지에 대한 주석은 업로드할 수 없습니다.

<details>

<summary>파일 이름 처리 방식</summary>

Roboflow는 업로드, 가져오기, 내보내기 시 클래스 이름을 표준화합니다.

* 앞뒤 공백은 제거됩니다.
* 줄 바꿈과 탭을 포함한 모든 공백은 공백 하나로 바뀝니다.
* 연속된 공백 두 개는 제거됩니다.
* `/.[]#~*` 문자는 대시(로 바뀝니다.`-`).
* `|'"` 문자는 제거됩니다.

</details>

## 웹 앱

이미지, 동영상, 주석을 Upload Data 페이지 또는 Project 생성 시 표시되는 업로드 상자에 끌어다 놓으세요.

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-deb24c5aa34b10e1ccab8bec61e7f55ed2f8c273%2Fimage%20(426).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

### 카메라로 촬영

웹캠이나 웹캠으로 사용하는 휴대폰에서 이미지 또는 동영상을 추가하려면 Upload Data 페이지에서 "카메라 사용"을 클릭하고 카메라를 선택하세요. "사진"을 선택하면 한 번에 이미지 한 장을 촬영하고, "간격"을 선택하면 0.2\~60초마다 프레임 한 장을 캡처합니다(최대 1,000장). "동영상"을 선택하면 최대 300초 길이의 MP4 클립을 녹화합니다. 클립 녹화가 끝나면 "동영상 유지"를 클릭하세요. 그런 다음 추가 버튼(예: "12개 업로드에 추가", "동영상을 업로드에 추가")을 클릭해 캡처한 항목을 업로드에 추가합니다. 이미지 기반 Project에서는 클립을 추가하면 [추출 대화상자](#upload-video)가 열립니다. MP4 녹화를 지원하지 않는 브라우저(예: Firefox)에서는 동영상 모드를 사용할 수 없습니다.

### ZIP 파일 업로드

각 `.zip` 파일은 하나의 파일로 업로드되어 Roboflow 서버에서 처리됩니다. 먼저 페이지에 ZIP에 포함된 항목(이미지, 동영상, 주석 파일, 분할)이 표시됩니다. 비밀번호로 보호되었거나 손상되었거나 이미지가 없거나, 파일이 100,000개를 초과하거나 압축 또는 압축 해제 시 크기가 8GB를 초과하는 ZIP은 업로드할 수 없습니다. 용량이 큰 ZIP은 더 작은 파일로 나누세요.

"ZIP 업로드"를 클릭하세요. 각 ZIP은 별도의 배치가 되며, 배치 이름을 입력하지 않으면 ZIP 파일 이름이 배치 이름으로 사용됩니다. 업로드가 완료될 때까지 탭을 열어 두세요. 완료되면 각 ZIP의 진행 상황과 추가됨, 주석 처리됨, 건너뜀 개수를 보여 주는 카드가 표시됩니다. 이미지를 보려면 "주석 작업 열기" 또는 "주석 처리로 이동"을 클릭하세요.

기본적으로 Project에 이미 있는 이미지의 주석은 유지됩니다. 주석을 교체하려면 "이 프로젝트에 이미 있는 이미지의 주석 교체"를 선택한 다음 "ZIP 업로드"를 클릭하세요. Classification Project에서는 항상 레이블이 교체됩니다.

아카이브에 주석이 포함되어 있으면 같은 ZIP을 다시 업로드하더라도 해당 이미지가 사용자에게 할당된 새 주석 작업으로 들어갑니다. [검토 모드](https://docs.roboflow.com/datasets/ko/annotate/annotate/team-collaboration.md#review-mode) 가 켜져 있으면 검토자가 승인할 때까지 이미지가 검토 대기 상태에 머뭅니다. 꺼져 있으면 즉시 데이터세트에 추가됩니다.

### 동영상 업로드

이미지 기반 Project에서는 주석을 달 수 있도록 각 동영상을 프레임으로 분할합니다. Action Recognition Project에서는 각 동영상을 원본 그대로 유지하므로 다음과 같이 동작에 레이블을 지정할 수 있습니다. [동영상 세그먼트](https://docs.roboflow.com/datasets/ko/annotate/annotate/annotate-video-segments.md).

저장할 때까지 동영상은 업로드 대기열에 남아 있습니다. 동영상 행에서 "동영상 미리보기"를 클릭하면 재생되고, "프레임 추출"을 클릭하면 추출 대화상자가 열립니다. 행 위에 있는 "프레임 추출"을 클릭하면 모든 동영상에 이 작업을 수행합니다. 추출한 프레임은 저장할 때 업로드됩니다.

저장하면 Roboflow는 동영상(최대 3GB)과 추출한 프레임을 보관합니다. 업로드에 이미지도 포함된 경우 동영상은 "Videos: " 뒤에 배치 이름을 붙인 별도의 배치로 들어갑니다. 동영상이 더 크거나 사용자 역할에서 동영상 보관을 허용하지 않으면 Roboflow는 추출한 프레임만 보관합니다. 요금제나 Project 유형에서 동영상 주석을 지원하지 않으면 동영상을 추가할 때 추출 대화상자가 열립니다.

추출 대화상자에서는 초당 60프레임부터 60초당 1프레임까지 간격을 지정해 프레임을 샘플링합니다. 필름 스트립의 트림 핸들을 끌어 범위 밖의 프레임을 제외하세요. 프레임을 직접 선택하려면 "수동 선택"을 클릭한 다음 `M` 를 눌러 현재 프레임을 추가하세요, `,` 그리고 `.` 한 프레임씩 이동하려면, 그리고 `Shift+Left` 그리고 `Shift+Right` 를 눌러 선택한 프레임 사이를 이동합니다. 샘플링된 프레임과 선택한 프레임은 중복 없이 병합됩니다.

동영상을 여러 개 대기열에 추가하면 모두에 동일한 간격을 적용할 수 있습니다. 선택한 프레임은 동영상 하나에만 속하므로, 선택한 프레임이 있는 각 동영상마다 별도의 대화상자가 열립니다.

프로젝트에 이미 있는 동영상에서 프레임을 추출하려면 이미지 브라우저에서 동영상을 선택하고 "프레임 추출"을 클릭하거나, 동영상을 열고 미리보기에서 프레임을 추출하세요. Dataset 페이지에 동영상만 표시하려면 "유형"을 "동영상"으로 설정하세요. 새 동영상은 데이터셋에 추가될 때까지 Annotate 페이지에서 해당 배치와 함께 유지됩니다.

<details>

<summary>지원되는 동영상 파일 형식</summary>

Roboflow는 브라우저에서 동영상을 디코딩하므로 업로드할 수 있는 형식은 [브라우저의 동영상 지원](https://caniuse.com/?search=video%20format)에 따라 달라집니다. MOV와 MP4는 대부분의 브라우저에서 작동합니다.

브라우저에서 동영상을 디코딩할 수 없으면 Roboflow에 "지원되지 않는 동영상" 오류가 표시됩니다. 흔한 원인은 HEVC/H.265입니다(예: DJI 드론, GoPro, 최신 휴대전화로 촬영한 영상). HEVC/H.265는 Safari에서만 디코딩됩니다. 동영상을 MP4(H.264)로 변환한 다음 다시 업로드하세요.

동영상이 계속 로드되지 않으면 [포럼](https://discuss.roboflow.com/) 에 게시하거나 계정 담당자에게 문의하세요.

</details>

### 동영상 구간 주석 가져오기

동작 인식 프로젝트에서는 각 동작이 발생하는 시점을 지정한 레이블을 가져올 수 있습니다. 각 동영상 옆에 해당 동영상의 주석 파일인 `_annotations.coco.json` 이 하나씩 들어 있는 폴더를 끌어다 놓으세요.

```
my_videos/
├── train/
│   ├── serve-01.mp4
│   └── _annotations.coco.json
└── valid/
    ├── serve-02.mp4
    └── _annotations.coco.json
```

각 파일의 `info.format` 값은 `roboflow-video-coco` 이며, MP4 또는 MOV 동영상 하나에 대한 설명이 들어 있습니다. 공간 주석과 프레임별 주석은 건너뛰며, ZIP 아카이브는 허용되지 않습니다. 폴더 이름이 `train`, `valid`또는 `test` 이면 해당 폴더 안 동영상의 데이터 분할이 지정됩니다. 그렇지 않으면 업로드가 시작되기 전에 데이터 분할을 선택해야 합니다.

동영상을 다시 가져오면 해당 구간이 대체됩니다. 단, 이미 프레임 주석이 있는 동영상은 예외이며, 이 경우 Roboflow는 기존 프레임 주석을 유지합니다.

## HTTP API

### 이미지 업로드 심사 확인

업로드 응답에 심사 보류 중인 이미지 ID가 포함되어 있으면, 사용 가능하다고 안내하기 전에 해당 이미지의 판정 결과를 확인하세요. 심사 대기 중인 이미지는 여전히 보류 상태입니다. 승인되거나 비식별 처리된 이미지는 나중에 사용 가능해질 수 있으며, 거부되거나 심사에 실패한 이미지는 프로젝트에 추가되지 않습니다. 심사 결과만으로 이미지가 Dataset에서 사용 가능한 상태인지 확인할 수는 없습니다.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/{workspace}/images/{imageId}/screening" method="get" %}
[manage-images.yaml](https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-e79147570726f4d6b42c79beb72e2651a92dfd6d%2Fmanage-images.yaml?alt=media)
{% endopenapi %}

### 동영상 업로드

최대 3GB의 MP4 또는 MOV 동영상을 Workspace나 동작 인식 프로젝트와 같은 프로젝트에 업로드할 수 있습니다. 업로드는 세 단계로 진행됩니다.

1. 업로드를 준비합니다. 다음 항목을 받습니다. `videoId`, `signedUrl`, `requiredHeaders`.
2. 다음 주소로 `PUT` 요청을 보내 동영상 파일을 전송합니다. `signedUrl`, 각 헤더는 `requiredHeaders`에 지정되어 있습니다. URL은 60분 후 만료됩니다.
3. 다음 상태가 될 때까지 업로드 상태를 확인하세요. `status` 가 `uploaded` 또는 `failed`.

업로드 스크리닝을 사용하면, 초당 한 프레임을 검사하는 동안 동영상은 `pending` 상태로 유지됩니다. 프레임이 거부되거나 가려지면 상태는 `failed` 가 되고 동영상은 삭제됩니다. 오디오와 메타데이터는 검사하지 않습니다.

선택 항목인 `batch`, `tag`, `metadata`및 `split` 필드는 이미지 업로드와 같은 방식으로 작동합니다. 동일한 동영상이 이미 프로젝트에 있으면 Roboflow에서 해당 동영상을 재사용합니다. 동영상은 기존 배치를 유지하고 지정한 태그, 메타데이터, 분할 정보를 적용합니다.

{% openapi src="/files/9adc2fc9c253afaf0c2add39d011d1d8cbb826a2" path="/{workspace}/upload/video" method="post" %}
[video-upload.yaml](https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-e3c30ed3463097178da198e0cc20ac25f88d496c%2Fvideo-upload.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9adc2fc9c253afaf0c2add39d011d1d8cbb826a2" path="/{workspace}/upload/video/{videoId}" method="get" %}
[video-upload.yaml](https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-e3c30ed3463097178da198e0cc20ac25f88d496c%2Fvideo-upload.yaml?alt=media)
{% endopenapi %}

업로드한 동영상을 찾으려면 [데이터셋을 검색](https://docs.roboflow.com/datasets/ko/manage/manage-datasets/dataset-search.md#http-api) 하고 `mediaTypes` 을 다음으로 설정합니다. `["video"]`.

## CLI

Roboflow Python 명령줄 인터페이스를 사용하여 더 큰 데이터셋을 업로드할 수 있습니다.

명령줄 인터페이스로는 이미지만 업로드할 수 있습니다. 동영상이 있는 경우 [파일로 저장된 프레임으로 분할](https://superuser.com/questions/1044444/how-do-i-use-ffmpeg-to-split-a-video-into-images-and-then-reassemble-exactly-the)해야 합니다. 그런 다음 이러한 파일을 Roboflow에 업로드할 수 있습니다.

시작하려면 먼저 `roboflow-python`:

```
pip install roboflow
```

그다음 [Workspace ID를 확인](https://docs.roboflow.com/reference/authentication/authentication/workspace-and-project-ids).

합니다. 마지막으로 다음 형식으로 명령을 준비합니다.

```
roboflow import -w testupload -p project-1-8zgld /path/to/dataset/folder
```

지정해야 하는 인수는 다음과 같습니다.

* `-w testupload`: 워크스페이스 이름입니다.
* `-p <project-id>`: 프로젝트 ID입니다.

명령을 실행하면 업로드 프로세스가 시작되었음을 나타내는 메시지가 표시됩니다. 그런 다음 이미지가 업로드되는 동안 로그가 표시됩니다.

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-cb3c6b1fff1fa6883a6fb226f8a3704493263a70%2FCleanShot%202024-03-13%20at%2011.29.09%402x.png?alt=media" alt=""><figcaption><p>명령줄을 사용하여 데이터셋 업로드하기</p></figcaption></figure>

명령줄에서 데이터를 업로드하는 방법을 보여주는 동영상 가이드를 확인하세요.

{% embed url="<https://www.loom.com/share/19637984033a466b831af56f9404fa89>" %}

### ZIP 파일 업로드

대규모 데이터셋의 경우 개별 파일 대신 이미지와 주석을 하나의 `.zip` 아카이브로 업로드할 수 있습니다. 아카이브는 한 번 업로드된 후 Roboflow 서버에서 비동기식으로 처리되므로 파일을 하나씩 업로드하는 것보다 빠르고 안정적입니다.

다음 파일을 직접 업로드합니다:  `.zip`  파일을 직접 업로드합니다:

```bash
roboflow image upload dataset.zip --workspace <workspace> -p <project>
```

또는 업로드하기 전에 CLI가 폴더를 ZIP 파일로 압축하도록 할 수 있습니다:

```bash
roboflow image upload ./dataset/folder --zip-upload --workspace <workspace> -p <project>
```

기본적으로 명령은 처리가 완료될 때까지 기다린 후 요약을 출력합니다. 즉시 반환하려면  `--no-wait` 를 전달하세요. CLI가 업로드 상태를 확인하는 데 사용할 수 있는 작업 ID를 출력합니다.

## Python SDK

다음을 사용하여  `Workspace.upload_dataset()` 로  `.zip`  아카이브를 업로드하거나 업로드 전에 폴더를 ZIP 파일로 압축할 수 있습니다:

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()

# .zip 경로는 자동으로 감지되어 아카이브로 업로드됩니다
workspace.upload_dataset("dataset.zip", project_name="your-project")

# 폴더의 경우 use_zip_upload를 활성화하여 하나의 아카이브로 압축하고 업로드합니다
workspace.upload_dataset("./dataset/folder", project_name="your-project", use_zip_upload=True)
```

{% hint style="info" %}
ZIP 업로드는 최대 8GB 및 100,000개 파일의 아카이브를 지원합니다. 예측(`is_prediction=True`)은 ZIP 업로드에서 지원되지 않습니다. 예측을 업로드하려면 이미지별 업로드를 사용하세요.
{% endhint %}

## MCP 서버

AI 에이전트를  [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 에 연결해 이미지와 선택적 어노테이션 파일을 ZIP으로 추가하세요. 검토 대기 중인 이미지와 바로 사용할 수 있는 이미지를 구분해 보고하세요.

<table data-search="false"><thead><tr><th width="290">도구</th><th>설명</th></tr></thead><tbody><tr><td><code>image_upload</code></td><td>ZIP 파일을 통해 로컬 이미지 파일을 프로젝트에 업로드합니다.</td></tr><tr><td><code>image_upload_status</code></td><td>검토 대기 중인 이미지를 포함해 ZIP 업로드 진행 상태와 개수를 확인합니다.</td></tr><tr><td><code>images_screening_status</code></td><td>검토 대기 중인 이미지 ID 하나의 검토 결과를 확인합니다.</td></tr><tr><td><code>images_update_metadata</code></td><td>업로드된 이미지의 메타데이터와 태그를 업데이트합니다.</td></tr></tbody></table>

## 업로드한 데이터 보기

Roboflow에 업로드된 모든 데이터는 "배치" 단위로 업로드됩니다. 이 배치는 프로젝트의 Annotate 페이지에서 확인할 수 있습니다:

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-e02e3663f94fef52256a1528c2361066bcc4d89f%2FScreenshot%202025-05-20%20at%2008.04.10.png?alt=media" alt=""><figcaption></figcaption></figure>

## 이미지 크기 제한

이미지 크기는 최대 30MB, 각 변은 최대 16,384픽셀, 전체 픽셀 수는 최대 178,956,970픽셀(약 1억 7,900만 화소)까지 가능합니다. 웹 앱, API, ZIP 업로드, 데이터 소스 등 모든 업로드 방식에서 제한을 초과하는 이미지는 업로드할 수 없습니다. 이 제한이 적용되기 전에 업로드한 이미지는 프로젝트에 그대로 남아 있습니다.

## 중복 이미지

프로젝트에 이미 있는 이미지를 업로드하려고 하면 해당 이미지의 업로드는 건너뜁니다.

프로젝트에서 이미지를 제거해도 어노테이션은 유지됩니다. 해당 이미지를 다시 업로드하면 기존 어노테이션과 이전 어노테이션 상태를 그대로 유지한 채 프로젝트에 다시 추가되므로, 어노테이션이 완료된 이미지가 어노테이션되지 않은 상태로 돌아오지 않습니다.

{% hint style="info" %}
두 데이터 세트를  [병합하면](https://docs.roboflow.com/datasets/ko/manage/merge-datasets.md), 병합된 데이터 세트와 원본 데이터 세트 두 개가 모두 계정에 존재합니다. 따라서 이미지가 중복되므로 병합에는 요금이 부과되지 않습니다.
{% endhint %}

## 데이터 소유권

Roboflow에 업로드하는 모든 이미지와 동영상의 소유권은 계속 귀하에게 있습니다. 이는  [서비스 약관 제23B조](https://roboflow.com/terms):

> 에 명시되어 있습니다. 귀하는 게시, 제출, 공개, 표시 또는 전송하는 모든 콘텐츠, 정보 또는 자료에 대한 모든 소유권을 보유합니다.

## 데이터 개인정보 보호

비공개 프로젝트는 Roboflow Universe에 공개적으로 표시되지 않습니다. 프로젝트 개인정보 설정을  [직접 관리할 수 있습니다](https://docs.roboflow.com/datasets/ko/manage/make-a-project-public.md).
