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

# 画像を管理する

REST API と Python SDK を通じて、個々の画像をアップロード、注釈、確認、タグ付け、削除します。

## 概要

Roboflowでは、REST APIとPython SDKを使って、プロジェクト内の個々の画像をアップロード、アノテーション、確認、タグ付け、削除できます。これらの操作は、一括データセットアップロードよりも細かく制御したい場合（例：ストリームから画像を1枚ずつアップロードする、後からアノテーションを追加する、画像のメタデータやタグを更新する場合）に使用します。ラベル付きデータセット全体を一度に一括インポートするには、 [データセットをアップロードする](https://docs.roboflow.com/datasets/ja/toappurdo/upload-a-dataset.md).

## HTTP API

### 画像をアップロードする

次の3つの方法のいずれかで画像を送信します。

* マルチパート形式でファイルをアップロードします。ローカルファイルには、これが最も効率的な方法です。
* リクエスト本文全体をbase64文字列にします。クライアントでマルチパートリクエストを作成できない場合に使用します。
* 公開URLを指定する `image` クエリパラメーター。Roboflowは自社のサーバーから画像を取得するため、本文にデータを送信する必要はありません。

アップロードごとに画像IDが返されます。このIDを使って画像のアノテーションをアップロードします。アップロードした画像は、プロジェクトの［Annotate］ページにある［Unassigned］列に、指定したバッチまたは「Uploaded via API」バッチとして表示されます。

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

### アノテーションをアップロードする

すでにアップロードした画像にアノテーションファイルを添付します。これは、あらゆる [対応するアノテーション形式](https://roboflow.com/formats) で利用でき、ファイル内で画像のファイル名が参照されている必要があります。アプリの［Upload］ページで、画像と一緒にアノテーションファイルをドラッグして追加することもできます。

デフォルトでは、アノテーションを追加すると画像もデータセットに追加されます。どのアノテーションジョブにも属していない画像は、バッチから、 `jobName`で指定したジョブ、または「Annotated via API」ジョブに移動します。アノテーションを保存しつつ画像をデータセットに追加しない場合は、 `addToDataset=false` を送信します。

アクション認識プロジェクトでは、動画のセグメントを含む [`roboflow-video-coco` ドキュメントを1つ送信し、画像IDの代わりに動画IDを使用します。](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data.md#import-video-segment-annotations) 。

{% openapi src="/files/871d94afdd69722fa0b20585f008a8cecc6c224f" path="/dataset/{project}/annotate/{imageId}" 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 %}

### 画像の詳細を取得する

画像のファイル名、分割、タグ、メタデータ、アノテーション、画像URLを読み取ります。動画の場合、レスポンスにはポスター画像、一時的なダウンロードリンク、および動画の [アクションセグメント](https://docs.roboflow.com/datasets/ja/zhu-shi/zhu-shi/annotate-video-segments.md).

{% openapi src="/files/871d94afdd69722fa0b20585f008a8cecc6c224f" path="/{workspace}/{project}/images/{imageId}" method="get" %}
[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 %}

### バージョンを確認してアノテーションを保存する

他のユーザーの編集を上書きせずに、画像のアノテーションをJSONシェイプで置き換えます。まず、 `include=annotation`を指定して画像を取得します。次に、その `annotationGroupVersion` を `expectedGroupVersion`として送信します。画像に保存済みのアノテーションがない場合も同様です。読み取り後にアノテーションが変更されていると、保存は409ステータスで失敗します。保存するたびに次回使用する新しいバージョンが返されます。

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

### データセットから画像を削除する

IDを指定してプロジェクトから画像を削除します。他のプロジェクトで使用されていない画像は完全に削除されます。

{% openapi src="/files/871d94afdd69722fa0b20585f008a8cecc6c224f" path="/{workspace}/{project}/images" method="delete" %}
[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つの画像にタグを追加、削除、または置き換えます。必要なのはファイル名ではなく画像IDです。 [プロジェクトを検索して](https://docs.roboflow.com/datasets/ja/guan-li/manage-datasets/dataset-search.md#search-images-in-a-project) 画像IDを確認します。

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

### 画像のメタデータとタグを更新する

ワークスペース内の任意の場所にある画像に、 [カスタムメタデータ](https://docs.roboflow.com/datasets/ja/toappurdo/adding-data/image-metadata.md) とタグを書き込みます。画像が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つのリクエストで最大1,000枚の画像を変更するには、バッチエンドポイントを使用します。処理はバックグラウンドで実行され、タスクURLが返されます。タスクが完了するまで、 [非同期タスク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 %}

## Python SDK

`Project` 一括の [`upload_dataset`](https://docs.roboflow.com/datasets/ja/toappurdo/upload-a-dataset.md#python-sdk) フローを補完する、画像単位の操作を提供します。単一画像のアップロードを細かく制御したい場合、後からアノテーションを追加したい場合、またはストリームから画像を1枚ずつ取り込む場合に使用してください。

### 画像をアップロードする（アノテーションは任意）

`Project.upload()` は、適切な処理を自動で行う高レベルのヘルパーです。単一の画像と、任意の対応するアノテーションファイルを受け取り、1回の呼び出しで両方をプロジェクトに送信します。

```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/ja/toappurdo/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で再エンコードするのではなく、元の画像バイトをアップロードします。これにより、Webアップローダーとの動作の一貫性が回復し、RoboflowサーバーがSHA-256でアップロードを重複排除できるようになります。同じ画像を2回アップロードする自動化（たとえば、複数のバッチに追加する場合）を実行している場合、2回目のアップロードは追加のストレージクレジットを消費せずに成功します。

## CLI

CLIを使用して、画像1枚と、任意のアノテーション、タグ、またはメタデータをアップロードします。

```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/ja/toappurdo/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>1枚の画像のメタデータとタグを更新します。</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>
