> 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/image-metadata.md).

# 이미지 메타데이터

이미지에 사용자 지정 키-값 메타데이터를 첨부해 데이터셋을 검색, 필터링, 정리할 수 있습니다.

메타데이터를 사용하면 Roboflow 워크스페이스의 이미지에 맞춤 키-값 쌍을 연결할 수 있습니다. 메타데이터에 이미지와 함께 저장할 구조화된 정보(예: 촬영 조건, 기기 식별자, 품질 점수 또는 도메인별 속성)를 기록한 다음, 해당 속성을 기준으로 데이터를 검색하고 필터링하고 정리할 수 있습니다.

## 개요

각 이미지에는 원하는 수만큼 메타데이터 항목을 저장할 수 있습니다. 항목은 **키** (예: `camera_id`)와 **값** (문자열, 숫자 또는 불리언)으로 구성됩니다.

| 값 유형 | 예시                                          |
| ---- | ------------------------------------------- |
| 문자열  | `location: "warehouse-3"`, `shift: "night"` |
| 숫자   | `temperature: 72.5`, `quality_score: 95`    |
| 불리언  | `reviewed: true`, `is_night: false`         |

### 사용 사례

* **촬영 맥락** - 카메라 ID, GPS 좌표, 날씨, 조명 조건 기록
* **품질 추적** - 신뢰도 점수, 검토 상태, 주석 작업자 ID 연결
* **데이터 분할** - 원하는 속성으로 데이터 세트를 필터링해 목적에 맞는 학습 세트 구성
* **외부 시스템 연결** - 이미지를 내부 도구와 연결하는 식별자 저장

## 메타데이터 추가

웹 UI, Python SDK, CLI, HTTP API를 통해 이미지에 메타데이터를 추가하거나, 다음을 통해 자동으로 추가할 수 있습니다. [S3 버킷 미러](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.md).

{% hint style="info" %}
이미지가 AWS S3와 같은 클라우드 스토리지에 있다면 [데이터 소스](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.md) 와 버킷 미러를 사용해 이미지 파일과 메타데이터 사이드카를 동기화된 상태로 유지하세요. 서명된 URL이나 수동 업로드는 동일한 지속적 메타데이터 동기화 기능을 제공하지 않습니다.
{% endhint %}

### 웹 애플리케이션

{% stepper %}
{% step %}

#### 이미지 열기

프로젝트에서 이미지를 하나 엽니다.
{% endstep %}

{% step %}

#### 키와 값 입력

메타데이터 섹션에서 첫 번째 입력란에 **키** 를, 두 번째 입력란에 **값** 을 입력합니다.
{% endstep %}

{% step %}

#### 추가

저장하려면 **Enter** 를 누르거나 추가를 클릭합니다.
{% endstep %}
{% endstepper %}

입력한 값은 유형에 따라 자동으로 파싱됩니다.

| 입력한 값            | 저장 형식                  |
| ---------------- | ---------------------- |
| `front`          | `"front"` (문자열)        |
| `95`             | `95` (숫자)              |
| `3.14`           | `3.14` (숫자)            |
| `true` / `false` | `true` / `false` (불리언) |

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-81508e07bb2a1aca8c5c8d7b66268c3ac88a35c6%2Fimage%20(439).png?alt=media" alt=""><figcaption><p>Annotation Tool의 메타데이터 편집기</p></figcaption></figure>

### Python SDK

이미지를 업로드할 때 `metadata` 딕셔너리를 전달합니다:

```python
import roboflow

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

project.upload(
    image_path="image.jpg",
    metadata={
        "camera_id": "cam001",
        "location": "warehouse-3",
        "temperature": 72.5,
        "is_night": False
    }
)
```

### CLI

기존 이미지의 메타데이터와 태그를 업데이트하려면 `roboflow image metadata` 명령어를 사용합니다:

```bash
# 단일 이미지의 메타데이터 설정
roboflow image metadata <image_id> -m '{"camera_id": "cam001", "location": "warehouse-3"}'

# 이미지에 태그 추가
roboflow image metadata <image_id> --tags "reviewed,v2"

# 메타데이터 키 삭제
roboflow image metadata <image_id> --remove-metadata "old_key,deprecated_field"

# 태그 삭제
roboflow image metadata <image_id> --remove-tags "draft"

# 한 번의 호출로 메타데이터 설정, 태그 추가 및 태그 삭제
roboflow image metadata <image_id> -m '{"quality_score": 95}' --tags "reviewed" --remove-tags "pending"

# 여러 이미지 일괄 업데이트(비동기)
roboflow image metadata img1,img2,img3 -m '{"batch": "june-2026"}' --tags "processed" --poll
```

이미지 ID 하나를 지정하면 동기적으로 업데이트됩니다. 쉼표로 구분된 여러 ID(최대 1,000개)를 지정하면 일괄 비동기 엔드포인트가 사용됩니다. 일괄 작업이 완료될 때까지 기다리려면 `--poll` 을 추가하세요. 이 옵션이 없으면 명령어는 나중에 확인할 수 있는 `taskId` 를 반환합니다. 다음 명령어로 확인할 수 있습니다: `roboflow asynctasks get <task-id>`.

| 플래그                    | 설명                      |
| ---------------------- | ----------------------- |
| `-m`, `--metadata`     | 설정할 키-값 쌍의 JSON 문자열     |
| `--remove-metadata`    | 삭제할 메타데이터 키를 쉼표로 구분한 목록 |
| `--tags`               | 추가할 태그를 쉼표로 구분한 목록      |
| `--remove-tags`        | 삭제할 태그를 쉼표로 구분한 목록      |
| `--poll` / `--no-poll` | 배치 완료까지 대기(배치 모드에서만 사용) |
| `--timeout`            | 폴링 제한 시간(초, 기본값: 1800)  |

### HTTP API

이미지를 업로드할 때 메타데이터를 추가하려면 멀티파트 폼에 JSON 객체 문자열이 포함된 `metadata` 필드를 보내거나 쿼리 매개변수로 전달합니다.

{% 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 %}

이미 워크스페이스에 있는 이미지의 메타데이터와 태그를 변경하려면 이미지 한 개를 바로 업데이트합니다.

{% 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):

{% 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 %}

### S3 버킷 미러링

이미지를 S3 버킷에서 동기화할 때 [데이터 소스](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.md) 를 사용하는 경우, 각 이미지와 함께 배치한 JSON 사이드카 파일을 통해 메타데이터를 가져옵니다. 사이드카 파일 형식, 제약 조건 및 업데이트 전략은 [데이터 소스](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.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_update_metadata</code></td><td>이미지 한 개의 메타데이터와 태그를 업데이트합니다.</td></tr><tr><td><code>images_batch_update_metadata</code></td><td>여러 이미지의 메타데이터와 태그를 일괄 업데이트합니다.</td></tr><tr><td><code>images_search</code></td><td>태그, 클래스 또는 메타데이터를 기준으로 업데이트할 이미지를 찾습니다.</td></tr></tbody></table>

## 촬영 시각

다음에 이미지를 업로드할 때 [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library) 를 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent#add-media)와 함께 사용하면 Roboflow가 각 이미지의 촬영 시각을 메타데이터로 저장합니다. 촬영 시각은 사진의 EXIF 데이터(JPEG 및 HEIC)에서 가져옵니다. 이미지에 EXIF 시각 정보가 없으면 파일의 마지막 수정 날짜를 사용합니다.

<table data-search="false"><thead><tr><th width="220">키</th><th>값</th></tr></thead><tbody><tr><td><code>captured_at</code></td><td>UTC 기준 ISO 8601 날짜 및 시간 형식의 촬영 시각(예: <code>2026-11-12T13:15:42.000Z</code>).</td></tr><tr><td><code>captured_at_unix</code></td><td>같은 시각을 Unix 초 단위로 나타낸 값(예: <code>1794489342</code>). 날짜 범위로 검색하는 데 사용하세요.</td></tr><tr><td><code>captured_at_source</code></td><td><code>exif</code> 시간이 사진에서 가져온 경우 또는 <code>file_modified</code> 파일의 마지막 수정 날짜에서 가져온 경우입니다.</td></tr></tbody></table>

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-f4ec85a769378294042f6043404259039e45c167%2Fimage-metadata-capture-time.webp?alt=media" alt="Image details in the Asset Library showing captured_at, captured_at_unix, and captured_at_source metadata"><figcaption><p>Asset Library 이미지의 촬영 시간 메타데이터</p></figcaption></figure>

사진의 EXIF 시간에 시간대 정보가 없으면 Roboflow는 사진을 업로드한 브라우저의 시간대로 시간을 해석합니다.

이미 Workspace에 있는 이미지를 업로드하면 기존 촬영 시간이 유지됩니다. 직접 `captured_at` 을 설정하면 Roboflow는 설정한 값을 유지합니다.

Project(채팅 또는 Project의 업로드 페이지)나 API를 통해, 또는 [Datasource](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.md) 에서 업로드한 이미지에는 촬영 시간이 설정되지 않습니다. 채팅에 끌어다 놓은 zip 파일의 이미지는 EXIF 데이터가 있는 경우에만 촬영 시간이 설정됩니다.

## 메타데이터로 검색하기

메타데이터는 색인화되며 [Asset Library](https://docs.roboflow.com/platform/workspaces/asset-library)에서 검색할 수 있습니다. 검색창을 사용해 메타데이터 값으로 이미지를 필터링하세요:

```
metadata:camera_id="cam001"
metadata:quality_score>80
metadata:reviewed=true
```

날짜 범위에 촬영된 이미지를 찾으려면 `captured_at_unix` 를 기준으로 필터링하고 범위의 시작과 끝을 Unix 초 단위로 지정하세요. 다음은 2026년 11월 12일(UTC)에 촬영된 이미지를 찾습니다:

```
metadata:captured_at_unix>=1794441600 AND metadata:captured_at_unix<1794528000
```

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-f9cd2adde8b5c395ccd6d6f02f939a8333c858f9%2Fimage-metadata-capture-time-search.webp?alt=media" alt="Asset Library search filtered to images captured on one day"><figcaption><p>촬영 시간으로 Asset Library 검색하기</p></figcaption></figure>

메타데이터 필터를 다른 검색 필터와 함께 사용할 수 있습니다:

```
metadata:location="warehouse-3" AND class:forklift
```

Asset Library에서는 Workspace에 존재하는 메타데이터 키와 값을 바탕으로 자동 완성도 제공됩니다.

## 키 이름 지정 규칙

메타데이터 키는 다음 규칙을 따라야 합니다:

| 규칙      | 세부 정보                                          |
| ------- | ---------------------------------------------- |
| 허용되는 문자 | 문자(`a-z`, `A-Z`), 숫자(`0-9`), 밑줄(`_`), 마침표(`.`) |
| 첫 번째 문자 | 문자, 숫자 또는 밑줄이어야 합니다                            |
| 금지된 문자  | 슬래시(`/`)는 사용할 수 없습니다                           |

유효한 키: `camera_id`, `capture.temperature`, `_internal_ref`, `v2_score`

잘못된 키: `camera/id` (포함: `/`), `.starts_with_dot` (로 시작: `.`), `has spaces` (공백 포함)

## 메타데이터와 태그 비교

메타데이터와 [태그는](https://docs.roboflow.com/datasets/ko/manage/manage-datasets/add-tags-to-images.md) 모두 이미지를 정리하는 데 도움이 되지만, 각각의 용도는 다릅니다:

|            | 태그                                   | 메타데이터                                      |
| ---------- | ------------------------------------ | ------------------------------------------ |
| **구조**     | 간단한 레이블                              | 키-값 쌍                                      |
| **값**      | 값 없이 이름만 있음                          | 문자열, 숫자 또는 불리언                             |
| **적합한 용도** | 분류, 워크플로 상태                          | 구조화된 속성, 측정값                               |
| **예시**     | `reviewed`, `v2`, `needs-annotation` | `temperature: 72.5`, `camera_id: "cam001"` |

같은 이미지에 태그와 메타데이터를 모두 사용할 수 있습니다. 예를 들어 이미지에 `reviewed` 태그를 지정하고, 다음 값을 저장할 수도 있습니다: `reviewer: "alice"` 및 `confidence: 0.95` 를 메타데이터로 저장합니다.
