> 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/manage/manage-images.md).

# 이미지 관리

REST API와 Python SDK를 통해 개별 이미지를 업로드, 주석 달기, 검사, 태그 지정, 삭제합니다.

## 소개

Roboflow에서는 REST API와 Python SDK를 통해 프로젝트의 개별 이미지를 업로드, 어노테이션, 검사, 태그 지정 및 삭제할 수 있습니다. 스트림에서 이미지를 한 번에 하나씩 업로드하거나, 나중에 어노테이션을 첨부하거나, 이미지 메타데이터와 태그를 업데이트하는 등 데이터셋 일괄 업로드보다 세밀한 제어가 필요할 때 이 작업들을 사용하세요. 레이블이 지정된 전체 데이터셋을 한 번에 일괄 가져오려면 다음을 참조하세요:  [데이터셋 업로드](https://docs.roboflow.com/datasets/ko/create-and-upload/upload-a-dataset.md).

## HTTP API

### 이미지 업로드

다음 세 가지 방법 중 하나로 이미지를 전송합니다.

* 멀티파트 파일 업로드. 로컬 파일에 가장 효율적인 방법입니다.
* 요청 본문 전체를 base64 문자열로 전송. 클라이언트에서 멀티파트 요청을 만들 수 없을 때 사용합니다.
* 공개 URL을 지정하는  `image`  쿼리 매개변수. Roboflow가 자체 서버에서 이미지를 가져오므로 본문에는 아무것도 전송되지 않습니다.

업로드할 때마다 이미지 ID가 반환됩니다. 이 ID를 사용하여 이미지의 어노테이션을 업로드하세요. 업로드한 이미지는 프로젝트의 어노테이션 페이지에서 지정한 배치 또는 "API를 통해 업로드됨" 배치의 미할당 열에 표시됩니다.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/dataset/{project}/upload" method="post" %}
[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 %}

### 어노테이션 업로드

이미 업로드한 이미지에 어노테이션 파일을 첨부합니다.  [지원되는 어노테이션 형식](https://roboflow.com/formats)  중 파일에서 이미지의 파일 이름을 참조하는 형식이면 모두 사용할 수 있습니다. 앱의 업로드 페이지에서 어노테이션 파일을 이미지와 함께 드래그하여 추가할 수도 있습니다.

기본적으로 어노테이션을 추가하면 이미지가 데이터셋에 추가됩니다. 어노테이션 작업에 속하지 않은 이미지는 기존 배치에서  `jobName`으로 지정한 작업 또는 "API를 통해 어노테이션됨" 작업으로 이동합니다. 이미지를 데이터셋에 추가하지 않고 어노테이션을 저장하려면  `addToDataset=false` 를 전송하세요.

액션 인식 프로젝트의 경우 비디오의 세그먼트가 포함된  [`roboflow-video-coco`  문서](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data.md#import-video-segment-annotations)  하나를 전송하고, 이미지 ID 대신 비디오 ID를 사용하세요.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/dataset/{project}/annotate/{imageId}" method="post" %}
[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 %}

### 이미지 세부 정보 가져오기

이미지의 파일 이름, 분할, 태그, 메타데이터, 어노테이션 및 이미지 URL을 읽습니다. 비디오의 경우 응답에 포스터 이미지, 유효 기간이 짧은 다운로드 링크 및  [액션 세그먼트가 포함됩니다.](https://docs.roboflow.com/datasets/ko/annotate/annotate/annotate-video-segments.md).

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/{workspace}/{project}/images/{imageId}" 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 %}

### 버전 확인을 통해 어노테이션 저장

다른 사용자의 편집 내용을 덮어쓰지 않고 이미지의 어노테이션을 JSON 도형으로 바꿉니다. 먼저  `include=annotation`을 사용하여 이미지를 가져옵니다. 그런 다음 이미지에 저장된 어노테이션이 없더라도 해당 이미지의  `annotationGroupVersion` 을  `expectedGroupVersion`으로 전송합니다. 어노테이션을 읽은 후 변경된 경우 저장이 실패하고 상태 코드 409가 반환됩니다. 저장할 때마다 다음에 사용할 새 버전이 반환됩니다.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/{workspace}/{project}/images/{imageId}/annotation" method="put" %}
[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 %}

### 데이터셋에서 이미지 삭제

ID를 사용하여 프로젝트에서 이미지를 제거합니다. 다른 프로젝트에서 사용하지 않는 이미지는 영구적으로 삭제됩니다.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/{workspace}/{project}/images" method="delete" %}
[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 %}

### 이미지 태그 추가 및 제거

프로젝트의 이미지 한 장에 태그를 추가하거나, 제거하거나, 교체합니다. 파일 이름이 아닌 이미지 ID가 필요합니다. ID를 찾으려면  [프로젝트를 검색](https://docs.roboflow.com/datasets/ko/manage/manage-datasets/dataset-search.md#search-images-in-a-project) 하세요.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/{workspace}/{project}/images/{imageId}/tags" method="post" %}
[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 %}

### 이미지 메타데이터 및 태그 업데이트

워크스페이스의 어디에 있는 이미지에든  [사용자 지정 메타데이터](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/image-metadata.md) 와 태그를 기록합니다. 이미지 한 장을 변경하려면 단일 이미지 엔드포인트를 사용하세요. 이 엔드포인트는 변경 사항을 적용한 후 응답합니다.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/{workspace}/images/{imageId}/metadata" method="post" %}
[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 %}

한 번의 요청으로 최대 1,000개의 이미지를 변경하려면 배치 엔드포인트를 사용하세요. 이 엔드포인트는 백그라운드에서 실행되며 작업 URL을 반환합니다. 작업이 완료될 때까지  [비동기 작업 API](https://docs.roboflow.com/reference/platform/rest-api/async-tasks) 로 해당 URL을 폴링하세요. 결과에는 성공한 이미지의 수와 실패한 이미지 목록이 포함됩니다.

{% openapi src="/files/9a8b087e4c93abba80da9ac1de9a86c3d95c58a8" path="/{workspace}/images/metadata" method="post" %}
[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 %}

## Python SDK

`Project` 대량 [`upload_dataset`](https://docs.roboflow.com/datasets/ko/create-and-upload/upload-a-dataset.md#python-sdk) 흐름을 보완하는 이미지별 작업을 제공합니다. 단일 이미지 업로드를 세밀하게 제어하거나, 나중에 어노테이션을 첨부하거나, 스트림에서 이미지를 한 번에 하나씩 가져올 때 사용하세요.

### 이미지 업로드(선택적 어노테이션 포함)

`Project.upload()` 는 상황에 맞게 처리해 주는 고수준 도우미입니다. 이미지 하나와 이에 대응하는 어노테이션 파일(선택 사항)을 받아 한 번의 호출로 둘 다 프로젝트에 전송합니다.

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("my-detector")

result = project.upload(
    image_path="./photo.jpg",
    annotation_path="./photo.xml",   # optional; matched VOC / COCO / etc. annotation
    split="train",                    # train | valid | test
    batch_name="ingest-2026-05",     # optional; groups uploads in the web UI
    tag_names=["camera-A", "indoor"], # optional; apply tags
    is_prediction=False,              # set True for model-generated annotations awaiting review
    num_retry_uploads=2,              # retries on transient upload failures
)
print(result)
```

`single_upload()` 는 같은 인수를 받는 저수준 변형으로, 이미지와 (제공된 경우) 어노테이션의 원시 API 응답을 반환합니다.

### 이미지만 업로드

```python
project.upload_image(
    image_path="./photo.jpg",
    split="train",
    batch_name="ingest-2026-05",
    tag_names=["camera-A"],
)
```

어노테이션이 아직 없고 이미지가 바로 라벨 작업자에게 전달되는 경우에 유용합니다.

### 업로드 전에 이미지 유효성 검사

`check_valid_image()` 는 API를 호출하지 않고 Roboflow의 로컬 크기 및 형식 검사를 수행합니다:

```python
if project.check_valid_image("./photo.jpg"):
    project.upload_image("./photo.jpg")
```

### 기존 이미지에 어노테이션 첨부

`save_annotation()` 는 이미 프로젝트에 있는 이미지에 어노테이션을 등록합니다. 다른 곳에서 만든 라벨을 추가하거나 모델 예측을 정답 데이터로 승격할 때 유용합니다.

```python
project.save_annotation(
    image_id="<image-id>",
    annotation_path="./photo.xml",
    is_prediction=False,
    annotation_overwrite=True,    # replace any existing annotation
)
```

어노테이션 형식에 클래스 인덱스를 클래스 이름으로 매핑해야 하는 경우 `annotation_labelmap="./labelmap.yaml"` 를 전달하세요.

다음과 같이 저장하면 `is_prediction=True` 이미지를 검토 작업으로 보낼 수 있습니다. 예측이 저장되는 위치는 [예측이 저장되는 위치](https://docs.roboflow.com/datasets/ko/create-and-upload/upload-a-dataset.md#where-predictions-land).

### 에서 확인하세요.

```python
info = project.image("<image-id>")
print(info["name"], info["split"], info["annotations"])
```

이미지 메타데이터, 현재 분할 및 주석 상태를 반환합니다.

### 이미지 삭제

프로젝트 수준(이 프로젝트에 속한 이미지만 삭제):

```python
project.delete_images(["<image-id-1>", "<image-id-2>"])
```

워크스페이스 수준(어떤 프로젝트에서 참조하는지와 관계없이 이미지 삭제 — 주의해서 사용):

```python
workspace.delete_images(["<image-id-1>", "<image-id-2>"])
```

### v1.3.6 이상 버전에서의 업로드 관련 참고 사항

부터 `roboflow` 1.3.6부터 SDK는 Pillow를 통해 다시 인코딩하는 대신 원본 이미지 바이트를 업로드합니다. 이 변경으로 웹 업로더와 동일한 동작을 제공하며, Roboflow 서버가 SHA-256을 기준으로 업로드를 중복 제거할 수 있습니다. 같은 이미지를 두 번 업로드하는 자동화(예: 여러 배치에 추가하는 경우)를 사용한다면, 두 번째 업로드도 성공하지만 추가 저장용량 크레딧은 차감되지 않습니다.

## CLI

CLI를 사용해 이미지 하나와 선택적 주석, 태그 또는 메타데이터를 업로드합니다.

```bash
roboflow image upload photo.jpg -p PROJECT_ID
```

### 옵션

<table data-search="false"><thead><tr><th>플래그</th><th>설명</th></tr></thead><tbody><tr><td><code>-p</code>, <code>--project</code></td><td>프로젝트 ID(필수)</td></tr><tr><td><code>-a</code>, <code>--annotation</code></td><td>주석 파일 경로</td></tr><tr><td><code>-m</code>, <code>--labelmap</code></td><td>레이블 맵 파일 경로</td></tr><tr><td><code>-s</code>, <code>--split</code></td><td>데이터셋 분할: <code>train</code>, <code>valid</code>또는 <code>test</code>. 기본값은 <code>train</code>.</td></tr><tr><td><code>-t</code>, <code>--tag</code></td><td>쉼표로 구분된 태그 이름</td></tr><tr><td><code>-M</code>, <code>--metadata</code></td><td>JSON 문자열 형식의 메타데이터</td></tr><tr><td><code>--is-prediction</code></td><td>업로드를 예측 결과로 표시</td></tr><tr><td><code>-b</code>, <code>--batch</code></td><td>배치 이름</td></tr></tbody></table>

### 예시

주석이 포함된 이미지 업로드:

```bash
roboflow image upload photo.jpg -p my-project -a annotation.xml -s valid
```

태그와 메타데이터가 포함된 이미지 업로드:

```bash
roboflow image upload photo.jpg -p my-project -t "outdoor,daytime" -M '{"camera_id":"cam001"}'
```

디렉터리 또는 `.zip` 아카이브, 참조 [데이터 세트 업로드](https://docs.roboflow.com/datasets/ko/create-and-upload/upload-a-dataset.md).

## MCP 서버

AI 에이전트를 다음에 연결하면 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 다음 도구를 사용해 이미지를 찾고 업데이트할 수 있습니다:

<table data-search="false"><thead><tr><th width="290">도구</th><th>설명</th></tr></thead><tbody><tr><td><code>images_search</code></td><td>프로젝트 내 이미지를 검색합니다.</td></tr><tr><td><code>images_update_metadata</code></td><td>이미지 하나의 메타데이터와 태그를 업데이트합니다.</td></tr><tr><td><code>images_batch_update_metadata</code></td><td>여러 이미지의 메타데이터와 태그를 일괄 업데이트합니다.</td></tr><tr><td><code>annotations_save</code></td><td>기존 이미지에 주석을 저장합니다.</td></tr></tbody></table>
