> 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/ja/toappurdo/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を追加する
* **データの切り出し** - 任意の属性でデータセットをフィルタリングし、目的に応じたトレーニングセットを作成する
* **外部システムとの連携** - 画像を社内ツールに関連付ける識別子を保存する

## メタデータの追加

Web UI、Python SDK、CLI、HTTP API、または [S3 Bucket Mirror](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasources.md).

{% hint style="info" %}
を使って、自動的に画像にメタデータを追加できます。画像が AWS S3 などのクラウドストレージにある場合は、 [Datasources](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasources.md) と Bucket Mirror を使用すると、画像ファイルとメタデータサイドカーを同期した状態に保てます。署名付き URL や手動アップロードでは、同様の継続的なメタデータ同期は行われません。
{% endhint %}

### Web アプリケーション

{% stepper %}
{% step %}

#### 画像を開く

プロジェクト内の任意の画像を開きます。
{% endstep %}

{% step %}

#### キーと値を入力する

メタデータセクションで、1つ目の入力欄に **キー** を、2つ目の入力欄に **値** を入力します。
{% endstep %}

{% step %}

#### 追加

保存するには **Enter** キーを押すか、［追加］をクリックします
{% endstep %}
{% endstepper %}

入力した値は、型に応じて自動的に解析されます。

| 入力値              | 保存形式                    |
| ---------------- | ----------------------- |
| `front`          | `"front"` （文字列）         |
| `95`             | `95` （数値）               |
| `3.14`           | `3.14` （数値）             |
| `true` / `false` | `true` / `false` （ブール値） |

<figure><img src="https://2416768182-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
# 1 枚の画像にメタデータを設定
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"

# メタデータの設定、タグの追加、タグの削除を 1 回の呼び出しで実行
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 が 1 つの場合は同期的に更新されます。カンマ区切りで複数の 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

画像のアップロード時にメタデータを追加するには、 `metadata` フィールドにJSONオブジェクト文字列を指定してマルチパートフォームで送信するか、クエリパラメーターとして送信します。

{% openapi src="/files/871d94afdd69722fa0b20585f008a8cecc6c224f" path="/dataset/{project}/upload" method="post" %}
[manage-images.yaml](https://2416768182-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枚の画像をすぐに更新します。

{% openapi src="/files/871d94afdd69722fa0b20585f008a8cecc6c224f" path="/{workspace}/images/{imageId}/metadata" method="post" %}
[manage-images.yaml](https://2416768182-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を使って [Async Tasks API](https://docs.roboflow.com/reference/platform/rest-api/async-tasks):

{% openapi src="/files/871d94afdd69722fa0b20585f008a8cecc6c224f" path="/{workspace}/images/metadata" method="post" %}
[manage-images.yaml](https://2416768182-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バケットミラー

画像の同期に [Datasources](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/datasources.md) を使用してS3バケットから画像を同期する場合、各画像と同じ場所に配置されたJSONサイドカーファイルからメタデータがインポートされます。 [Datasources](https://docs.roboflow.com/datasets/ja/toappurdo/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>1枚の画像のメタデータとタグを更新します。</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>

## 撮影日時

Roboflow [Asset Library](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://2416768182-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 はアップロードに使用したブラウザーのタイムゾーンで時刻を読み取ります。

すでにワークスペース内にある画像をアップロードしても、既存の撮影時刻は保持されます。 `captured_at` を自分で設定した場合、Roboflow はその値を保持します。

プロジェクト（チャットまたはプロジェクトのアップロードページ）からアップロードした画像、API 経由でアップロードした画像、または [データソース](https://docs.roboflow.com/datasets/ja/toappurdo/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://2416768182-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 では、ワークスペース内に存在するメタデータキーと値に基づくオートコンプリートも利用できます。

## キーの命名規則

メタデータキーは、次の規則に従う必要があります。

| 規則       | 詳細                                                |
| -------- | ------------------------------------------------- |
| 使用できる文字  | 英字（`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/ja/guan-li/manage-datasets/add-tags-to-images.md) はどちらも画像の整理に役立ちますが、それぞれ用途が異なります。

|           | タグ                                   | メタデータ                                      |
| --------- | ------------------------------------ | ------------------------------------------ |
| **構造**    | シンプルなラベル                             | キーと値のペア                                    |
| **値**     | 値はなく、名前のみ                            | 文字列、数値、またはブール値                             |
| **最適な用途** | 分類、ワークフローのステータス                      | 構造化された属性、測定値                               |
| **例**     | `reviewed`, `v2`, `needs-annotation` | `temperature: 72.5`, `camera_id: "cam001"` |

同じ画像にタグとメタデータの両方を設定できます。たとえば、画像に `reviewed` というタグを付け、さらに `reviewer: "alice"` および `confidence: 0.95` をメタデータとして保存できます。
