> 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/roboflow/roboflow-jp/datasets/adding-data/image-metadata.md).

# Image Metadata

メタデータを使うと、Roboflow workspace の画像にカスタムのキーと値のペアを追加できます。メタデータを使って、撮影条件、デバイス識別子、品質スコア、その他ドメイン固有の属性などの構造化情報を画像と一緒に保存し、その属性を基準にデータを検索、フィルタリング、整理できます。

## 概要

各画像には、任意の数のメタデータエントリを含めることができます。エントリとは、 **キー** （たとえば次のような名前） `camera_id`）と、次の **値** （文字列、数値、またはブール値）です。

| 値の型  | 例                                           |
| ---- | ------------------------------------------- |
| 文字列  | `location: "warehouse-3"`, `shift: "night"` |
| 数値   | `temperature: 72.5`, `quality_score: 95`    |
| ブール値 | `reviewed: true`, `is_night: false`         |

### ユースケース

* **撮影コンテキストの記録** — camera ID、GPS座標、天候、照明条件を記録
* **品質追跡** — 信頼度スコア、レビュー状態、アノテータIDを付与
* **データの切り出し** — 任意の属性でデータセットをフィルタリングし、目的に合ったトレーニングセットを作成
* **外部システム連携** — 画像を社内ツールに紐付ける識別子を保存

## メタデータの追加

画像にメタデータを追加するには、web UI、Python SDK、REST API、または次を通じて自動的に行えます: [S3 Bucket Mirror](/roboflow/roboflow-jp/datasets/adding-data/datasources.md).

{% hint style="info" %}
画像が AWS S3 のようなクラウドストレージにある場合は、 [Datasources](/roboflow/roboflow-jp/datasets/adding-data/datasources.md) と Bucket Mirror を使用して、画像ファイルとメタデータのサイドカーを同期状態に保ってください。Signed URL や手動アップロードでは、同じような継続的なメタデータ同期は行われません。
{% endhint %}

### Web Application

{% stepper %}
{% step %}

#### 画像を開く

project 内の任意の画像を開きます。
{% endstep %}

{% step %}

#### キーと値を入力

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

{% step %}

#### Add

押して **Enter** で保存するか、Add をクリックします
{% endstep %}
{% endstepper %}

値は型に応じて自動的に解析されます:

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

<figure><img src="/files/9e32629a005dc64e4665ccb8fecc587ed638ae30" 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
    }
)
```

既にアップロード済みの画像のメタデータを更新するには、 `rfapi` アダプターを直接使用します。渡された値は `metadata` アップサートされます。新しいキーは追加され、既存のキーは上書きされます。

```python
from roboflow.adapters import rfapi

rfapi.update_image_metadata(
    api_key="YOUR_API_KEY",
    workspace_url="your-workspace",
    image_id="IMAGE_ID",
    metadata={"quality_score": 95, "reviewed": True},
    remove_metadata=["old_key"],
    add_tags=["reviewed"],
    remove_tags=["pending"]
)
```

1回の呼び出しで最大1,000枚の画像を更新するには、 `batch_update_image_metadata`。これにより `taskId` が返され、async tasks endpoint でポーリングできます:

```python
from roboflow.adapters import rfapi

result = rfapi.batch_update_image_metadata(
    api_key="YOUR_API_KEY",
    workspace_url="your-workspace",
    updates=[
        {"imageId": "img1", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]},
        {"imageId": "img2", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]}
    ]
)
print(result["taskId"])
```

### 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
```

1つの画像IDは同期的に更新されます。カンマ区切りの複数ID（最大1,000件）の場合は、batch async endpoint を使用します。次を追加: `--poll` バッチの完了を待つためのもので、これがない場合、コマンドは `taskId` を返します。後で次で確認できます: `roboflow asynctasks get <task-id>`.

| フラグ                    | 説明                          |
| ---------------------- | --------------------------- |
| `-m`, `--metadata`     | 設定するキーと値のペアの JSON 文字列       |
| `--remove-metadata`    | 削除するメタデータキーをカンマ区切りで指定       |
| `--tags`               | 追加するタグをカンマ区切りで指定            |
| `--remove-tags`        | 削除するタグをカンマ区切りで指定            |
| `--poll` / `--no-poll` | バッチ完了まで待機（batch mode のみ）    |
| `--timeout`            | ポーリングのタイムアウト秒数（デフォルト: 1800） |

### REST API

#### アップロード時にメタデータを追加

次を含めます: `metadata` 画像をアップロードする際、multipart form data に field（JSON 文字列化済み）を含めます:

```bash
curl -X POST "https://api.roboflow.com/dataset/your-dataset/upload?api_key=YOUR_API_KEY" \\
  -F "name=image.jpg" \\
  -F "split=train" \\
  -F "file=@image.jpg" \\
  -F 'metadata={"camera_id":"cam001","temperature":72.5}'
```

#### 既存画像のメタデータを更新

単一画像用 endpoint を使って、すでに workspace にある画像のメタデータの設定・上書き、メタデータキーの削除、タグの追加/削除を行えます。渡された値は `metadata` アップサートされます（新しいキーは追加され、既存のキーは上書きされます）。次に列挙したキーは `removeMetadata` 削除されます。

```bash
curl -X POST "https://api.roboflow.com/your-workspace/images/IMAGE_ID/metadata?api_key=YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "metadata": {"quality_score": 95, "reviewed": true},
    "removeMetadata": ["old_key"],
    "addTags": ["reviewed"],
    "removeTags": ["pending"]
  }'
```

| フィールド            | 型         | 説明                                                              |
| ---------------- | --------- | --------------------------------------------------------------- |
| `metadata`       | object    | 設定するキーと値のペア。新しいキーを追加し、既存のものは上書きします。                             |
| `removeMetadata` | string\[] | 削除するメタデータキー。1つのキーを両方に含めることはできません `metadata` と `removeMetadata`. |
| `addTags`        | string\[] | 追加するタグ。                                                         |
| `removeTags`     | string\[] | 削除するタグ。1つのタグを両方に含めることはできません `addTags` と `removeTags`.           |

すべてのフィールドは任意ですが、少なくとも1つは指定する必要があります。返り値: `200 { "success": true }`.

#### メタデータの一括更新（非同期）

1回の呼び出しで最大1,000枚の画像を更新するには、 `POST` workspace レベルの endpoint に updates の配列を送信します:

```bash
curl -X POST "https://api.roboflow.com/your-workspace/images/metadata?api_key=YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "updates": [
      {"imageId": "img1", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]},
      {"imageId": "img2", "metadata": {"batch": "june-2026"}, "addTags": ["processed"]}
    ]
  }'
```

返り値 `202 { "taskId": "...", "url": "..." }`。返された URL を同じ `api_key` でポーリングし、ステータスと各項目の結果を取得します:

```bash
curl "https://api.roboflow.com/your-workspace/asynctasks/TASK_ID?api_key=YOUR_API_KEY"
```

### S3 Bucket Mirror

使用する場合、 [Datasources](/roboflow/roboflow-jp/datasets/adding-data/datasources.md) S3 bucket から画像を同期すると、メタデータは各画像の横に配置された JSON サイドカーファイルを通じて取り込まれます。詳細は [Datasources](/roboflow/roboflow-jp/datasets/adding-data/datasources.md) サイドカーファイルの形式、制約、更新戦略をご覧ください。

## メタデータで検索

メタデータはインデックス化され、次の中で検索可能です: [Asset Library](/roboflow/roboflow-jp/workspaces/asset-library.md)。検索バーを使って、メタデータ値で画像を絞り込めます:

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

メタデータフィルターは、他の検索フィルターと組み合わせられます:

```
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` （で始まる） `.`), `空白を含む` （空白を含む）

## メタデータとタグの違い

メタデータも [タグも](/roboflow/roboflow-jp/datasets/manage-datasets/add-tags-to-images.md) 画像の整理に役立ちますが、役割は異なります:

|             | タグ                                   | メタデータ                                      |
| ----------- | ------------------------------------ | ------------------------------------------ |
| **構造**      | シンプルなラベル                             | キーと値のペア                                    |
| **値**       | 値はなく、名前のみ                            | 文字列、数値、またはブール値                             |
| **向いている用途** | 分類、workflow status                   | 構造化属性、測定値                                  |
| **例**       | `reviewed`, `v2`, `needs-annotation` | `temperature: 72.5`, `camera_id: "cam001"` |

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