> 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/deployment/ja/roboflow-cloud/batch-processing.md).

# バッチ処理

## 概要

Batch Processing は、画像バッチや保存済み動画に対して実行するコスト効率の高い方法です。 [Workflows](https://docs.roboflow.com/workflows) 画像バッチや保存済み動画に対して実行できます。大量のデータを非同期で処理するのに最適です。

Batch Processing は、大規模なバッチを実行するために必要なインフラを自動的にプロビジョニングします。

{% hint style="info" %}
Batch Processing は Growth および Enterprise プランで利用できます。ジョブは「Batch Processing」タブから開始するか、Asset Library 内の選択項目に対して Workflow を実行できます。 [Asset Library](https://docs.roboflow.com/platform/workspaces/asset-library).
{% endhint %}

Roboflow の Web インターフェース、または API（CLI 経由）から Batch Processing ジョブを設定できます。

ジョブを開始すると、データを処理するためのマシンがクラウド上にプロビジョニングされます。その後、データに対して実行した Workflow の出力が入った JSON ファイルを受け取ります。

次の動画では、Batch Processing を詳しく説明しています：

{% embed url="<https://www.youtube.com/watch?v=S7K2j2IeQrM>" %}

## Web アプリ

### Batch Processing ジョブを作成する

Batch Processing ジョブを作成するには、Roboflow ダッシュボードの左サイドバーで Deployments をクリックします。次に、「Batch Processing」タブをクリックします：

<figure><img src="/files/3b1d482191e8bd2388cf6095af04a1c95b467f7d" alt=""><figcaption></figcaption></figure>

「New Batch Job」をクリックして Batch Processing ジョブを作成します。

ジョブを設定するウィンドウが開きます：

<figure><img src="/files/fe2b2e0493c3a08c9a01dfbd278e14a404ca70da" alt=""><figcaption></figcaption></figure>

#### Workflow を選択

ジョブの設定を始めるには、まず Workflow を選択します。まだ Workflow がない場合は、Getting started のために Workflows のドキュメントを参照してください。

#### 画像または動画をアップロード

次に、Workflow を実行したい画像または動画をアップロードする必要があります。

#### ハードウェアを設定

Batch Processing ジョブは CPU または GPU で実行できます。GPU ジョブは高速ですが、より高価です。

料金情報については、Roboflow の料金ドキュメントを参照してください。

ジョブには CPU または GPU のいずれかを選択してください：

<figure><img src="/files/e6572d4d4ea2c99054cc434a35eb087c0aea4479" alt=""><figcaption></figcaption></figure>

「Advanced Options」タブには、いくつかの高度な設定オプションもあります。これらのオプションはデフォルトのままにしておくことを推奨します。

#### ジョブを開始

Batch Processing ジョブを開始するには、「Create Batch Job」をクリックします。

ジョブのインフラがプロビジョニングされ、処理が開始されます。

### ジョブの進行状況を監視

ジョブを開始すると、処理の設定中、バッチデータの処理中、そしてジョブ完了時に状態インジケーターが表示されます。

バッチのどこまでが処理済みかをリアルタイムで監視できます。

データの処理にかかる時間は、処理する画像や動画の数、Workflow の複雑さ、選択した CPU または GPU ハードウェアによって異なります。

ジョブを開くと、ジョブがどの画像で実行されたかを示す「Input Source」を含む詳細を確認できます： [Asset Library](https://docs.roboflow.com/platform/workspaces/asset-library) それらを選択するために使われた検索クエリ（その選択を再度開くためのリンク付き）、または手動で選択された画像数。

### アプリから Workflow を実行

に加えて、 [API](#http-api) および [CLI](#cli)、Roboflow アプリから直接 Batch Processing ジョブを開始して、 [ワークフロー](https://docs.roboflow.com/workflows) 保存済み画像の大規模セットに対して Workflow を実行できます。方法は 2 つあります：

* Asset Library からオンデマンドで。
* 各 [Datasource](https://docs.roboflow.com/datasets/create-and-upload/adding-data/datasources) がクラウドバケットから新しい画像をミラーリングするたびに自動で。

#### Asset Library から

次の [Asset Library](https://docs.roboflow.com/platform/workspaces/asset-library) では、選択した画像に対して、オンデマンドで Workflow を実行できます。

画像を手動で選択するか、現在の検索条件に一致するすべての画像を選択してから、「Run Workflow」をクリックします。結果を画像に書き戻す方法を含む全体のフローについては、 [Workflow の実行](https://docs.roboflow.com/platform/workspaces/asset-library#running-a-workflow).

#### Datasource がミラーリングすると自動的に

1つの [Datasource](https://docs.roboflow.com/datasets/create-and-upload/adding-data/datasources) クラウドバケットから Workspace に画像とメタデータをミラーリングします。各ミラーリングで取り込まれた新しい画像に対して、自動で Workflow を実行できます。これにより、タグ付け、品質スコアリング、事前ラベリングなどのエンリッチメントを、新しいデータが到着するたびに手動操作なしで最新の状態に保てます。

これらの自動化は、 [Datasources](https://app.roboflow.com/settings/datasources) ページの「Workflow runs」セクションで設定します。

{% hint style="info" %}
Workflow runs の管理には、バッチ自動化を管理する権限を持つ Workspace ロールが必要です。「Workflow runs」セクションが表示されない場合は、Workspace 管理者に依頼してください。
{% endhint %}

自動化を追加するには：

1. 「Workflow runs」セクションで、「Add workflow run」をクリックします。
2. 自動化の名前を入力します。
3. 「Run when」で「On Sync」を選び、 [Datasources](https://docs.roboflow.com/datasets/create-and-upload/adding-data/datasources) を選択してトリガーされるようにします。
4. 実行する Workflow を選択します。これはちょうど 1 つの `image` 入力を持っている必要があります。
5. マシンタイプ（CPU または GPU）を選択します。
6. 「Create」をクリックします。

選択した Datasource のいずれかがミラーリングされるたびに、そのミラーで取り込まれた画像に対して Workflow が Batch Processing ジョブとして実行されます。進行状況は Activity Center と Deployments の「Batch Processing」タブで、他の Batch Processing ジョブと同様に追跡できます。

Workflow の結果を画像に書き戻して Asset Library で検索できるようにする方法については、 [結果を書き戻す](https://docs.roboflow.com/platform/workspaces/asset-library#writing-results-back-to-the-asset-library).

### API または CLI からジョブを実行

プログラムで Batch Processing ジョブを作成して実行するには、以下の [HTTP API](#http-api) および [CLI](#cli) セクションを参照してください。よくある問題のデバッグについては、 [トラブルシューティング](/deployment/ja/roboflow-cloud/batch-processing/troubleshooting.md).

## HTTP API

**クイックリンク：**

* [データを取り込む](#ingest-data) (動画、単一画像、画像)
* [バッチのステータスを確認](#check-batch-status) (アイテム数、シャードの詳細)
* [ジョブを開始](#start-a-job)
* [ジョブの進行状況を監視](#monitor-job-progress) (ジョブの状態、ステージ、タスク)
* [結果をエクスポート](#export-results) (出力の一部、ダウンロード URL)
* [Webhook 通知](#webhook-notifications)

### データを取り込む

#### 動画をアップロード

## Upload a video

> Request a signed URL to upload a video file. After receiving the response, PUT the video to the \`uploadURL\` with the provided \`extensionHeaders\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Ingestion","description":"Upload images and videos to Data Staging before processing."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/video":{"post":{"operationId":"uploadVideo","tags":["Data Ingestion"],"summary":"Upload a video","description":"Request a signed URL to upload a video file. After receiving the response, PUT the video to the `uploadURL` with the provided `extensionHeaders`.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"name":"fileName","in":"query","required":true,"schema":{"type":"string"},"description":"Name of the video file (e.g. `my_video.mp4`)."}],"responses":{"200":{"description":"Signed URL details for uploading the video.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"signedURLDetails":{"type":"object","properties":{"uploadURL":{"type":"string","description":"PUT the video file to this URL."},"method":{"type":"string","description":"HTTP method to use for the upload."},"extensionHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Include these headers in the PUT request."},"maxFileSize":{"type":"integer","description":"Maximum file size in bytes."}}}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

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

## Upload a single image

> Upload a single image via multipart form data. Best for batches up to 5,000 images.\
> \
> \*\*Note:\*\* Single-image and bulk uploads cannot be combined for the same batch.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Ingestion","description":"Upload images and videos to Data Staging before processing."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/image":{"post":{"operationId":"uploadImage","tags":["Data Ingestion"],"summary":"Upload a single image","description":"Upload a single image via multipart form data. Best for batches up to 5,000 images.\n\n**Note:** Single-image and bulk uploads cannot be combined for the same batch.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"name":"fileName","in":"query","required":true,"schema":{"type":"string"},"description":"Name of the image file."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The image file to upload."}}}}}},"responses":{"200":{"description":"Image uploaded successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### 画像を一括アップロード

## Bulk upload images

> Request a signed URL for uploading a \`.tar\` archive of images. Recommended for batches exceeding 5,000 images. Bundle up to 500 images per archive.\
> \
> The response contains a signed URL and extension headers. Pack images into a \`.tar\` archive and PUT it to the signed URL.\
> \
> \*\*Note:\*\* Bulk and single-image uploads cannot be combined for the same batch.\
> \
> When performing bulk ingestion, data is indexed in the background. There may be a short delay before all data is available.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Ingestion","description":"Upload images and videos to Data Staging before processing."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/bulk-upload/image-files":{"post":{"operationId":"bulkUploadImages","tags":["Data Ingestion"],"summary":"Bulk upload images","description":"Request a signed URL for uploading a `.tar` archive of images. Recommended for batches exceeding 5,000 images. Bundle up to 500 images per archive.\n\nThe response contains a signed URL and extension headers. Pack images into a `.tar` archive and PUT it to the signed URL.\n\n**Note:** Bulk and single-image uploads cannot be combined for the same batch.\n\nWhen performing bulk ingestion, data is indexed in the background. There may be a short delay before all data is available.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"Signed URL details for uploading a tar archive.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"signedURLDetails":{"type":"object","properties":{"shardId":{"type":"string","format":"uuid","description":"Unique identifier for this shard upload."},"uploadURL":{"type":"string","description":"PUT the tar archive to this URL."},"method":{"type":"string","description":"HTTP method to use for the upload."},"extensionHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Include these headers in the PUT request."},"maxNumberOfImages":{"type":"integer","description":"Maximum number of images per tar archive."},"maxShardSize":{"type":"integer","description":"Maximum tar archive size in bytes."}}}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

### バッチのステータスを確認

## Get batch item count

> Returns the count of ingested items in a batch. Use this to verify all data has been ingested before starting a job.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Batch Status","description":"Inspect staged data and batch contents."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/count":{"get":{"operationId":"getBatchCount","tags":["Batch Status"],"summary":"Get batch item count","description":"Returns the count of ingested items in a batch. Use this to verify all data has been ingested before starting a job.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"Batch item count.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"count":{"type":"integer","description":"Number of items in the batch."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### シャードのアップロード詳細を確認

## List batch shards

> Returns shard details for a bulk-upload batch. Paginated — use \`nextPageToken\` from the response to fetch subsequent pages.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Batch Status","description":"Inspect staged data and batch contents."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/shards":{"get":{"operationId":"getBatchShards","tags":["Batch Status"],"summary":"List batch shards","description":"Returns shard details for a bulk-upload batch. Paginated — use `nextPageToken` from the response to fetch subsequent pages.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"$ref":"#/components/parameters/nextPageToken"}],"responses":{"200":{"description":"Paginated list of batch shards.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"shards":{"type":"array","items":{"type":"object"},"description":"List of shard objects."},"nextPageToken":{"type":"string","nullable":true,"description":"Token for fetching the next page of results. `null` if no more pages."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."},"nextPageToken":{"name":"nextPageToken","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination token from a previous response."}}}}
```

### ジョブを開始

## Start a batch processing job

> Start a batch processing job that runs a Workflow against staged data.\
> \
> \*\*Job ID constraints:\*\* Lowercase letters, digits, hyphens, and underscores only. Maximum 20 characters.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}":{"post":{"operationId":"startJob","tags":["Processing"],"summary":"Start a batch processing job","description":"Start a batch processing job that runs a Workflow against staged data.\n\n**Job ID constraints:** Lowercase letters, digits, hyphens, and underscores only. Maximum 20 characters.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"$ref":"#/components/parameters/api_key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStartRequest"}}}},"responses":{"200":{"description":"Job started successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}},"schemas":{"JobStartRequest":{"type":"object","required":["type","jobInput","computeConfiguration","processingSpecification"],"properties":{"type":{"type":"string","enum":["simple-image-processing-v1"],"description":"Job type."},"jobInput":{"type":"object","required":["type","batchId"],"properties":{"type":{"type":"string","enum":["staging-batch-input-v1"],"description":"Input type."},"batchId":{"type":"string","description":"The batch ID containing the data to process."}}},"computeConfiguration":{"type":"object","required":["type","machineType"],"properties":{"type":{"type":"string","enum":["compute-configuration-v2"],"description":"Configuration type."},"machineType":{"type":"string","enum":["cpu","gpu"],"description":"Machine type. Use `gpu` for Workflows with multiple or large models."},"workersPerMachine":{"type":"integer","default":4,"description":"Number of parallel workers per machine. Reduce for memory-intensive Workflows."}}},"processingTimeoutSeconds":{"type":"integer","default":3600,"description":"Maximum cumulative machine runtime in seconds across all parallel workers."},"processingSpecification":{"type":"object","required":["type","workspace","workflowId"],"properties":{"type":{"type":"string","enum":["workflows-processing-specification-v1"],"description":"Processing specification type."},"workspace":{"type":"string","description":"Workspace containing the Workflow."},"workflowId":{"type":"string","description":"The Workflow to run. Find this in the Workflow Editor under \"Deploy\"."},"aggregationFormat":{"type":"string","enum":["jsonl","csv"],"default":"jsonl","description":"Output format for aggregated results."}}},"notificationsURL":{"type":"string","format":"uri","description":"Webhook URL for job completion notifications. Custom webhook headers are not yet supported. The only header sent is `Authorization: Bearer rf_{workspace_id}`."}}}}}}
```

### ジョブの進行状況を監視

#### ジョブのステータスを取得

## Get job status

> Returns the current status of a batch processing job.

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}":{"get":{"operationId":"getJobStatus","tags":["Processing"],"summary":"Get job status","description":"Returns the current status of a batch processing job.","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"Job status details.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"jobStatus":{"type":"string","description":"Current job status (e.g. `pending`, `processing`, `completed`, `failed`)."},"progress":{"type":"number","description":"Processing progress as a fraction between 0 and 1."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### ジョブステージを一覧表示

## List job stages

> Returns the list of stages for a job. Each job typically has \`processing\` and \`export\` stages, each producing an output batch.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages":{"get":{"operationId":"getJobStages","tags":["Processing"],"summary":"List job stages","description":"Returns the list of stages for a job. Each job typically has `processing` and `export` stages, each producing an output batch.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"List of job stages.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"stages":{"type":"array","items":{"type":"object"},"description":"List of stage objects. Each stage has an ID and an output batch ID."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### ステージタスクを一覧表示

## List tasks for a stage

> Returns the list of tasks for a specific job stage. Paginated — use \`nextPageToken\` from the response to fetch subsequent pages.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages/{stage_id}/tasks":{"get":{"operationId":"getStageTasks","tags":["Processing"],"summary":"List tasks for a stage","description":"Returns the list of tasks for a specific job stage. Paginated — use `nextPageToken` from the response to fetch subsequent pages.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"name":"stage_id","in":"path","required":true,"schema":{"type":"string"},"description":"The stage identifier."},{"$ref":"#/components/parameters/api_key"},{"$ref":"#/components/parameters/nextPageToken"}],"responses":{"200":{"description":"Paginated list of tasks.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"tasks":{"type":"array","items":{"type":"object"},"description":"List of task objects."},"nextPageToken":{"type":"string","nullable":true,"description":"Token for fetching the next page of results. `null` if no more pages."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."},"nextPageToken":{"name":"nextPageToken","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination token from a previous response."}}}}
```

### 結果をエクスポート

#### 出力パートを一覧表示

## List output batch parts

> Lists the parts of an output batch. Use the \`export\` stage output batch for compressed results.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Export","description":"Download results after processing completes."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/parts":{"get":{"operationId":"listBatchParts","tags":["Data Export"],"summary":"List output batch parts","description":"Lists the parts of an output batch. Use the `export` stage output batch for compressed results.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"List of batch parts.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"parts":{"type":"array","items":{"type":"object","properties":{"partName":{"type":"string","description":"Name of the batch part."}}},"description":"List of batch part objects."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### ダウンロード URL を一覧表示

## List download URLs

> Returns paginated download URLs for files in a batch part.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Export","description":"Download results after processing completes."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/list":{"get":{"operationId":"listDownloadUrls","tags":["Data Export"],"summary":"List download URLs","description":"Returns paginated download URLs for files in a batch part.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"$ref":"#/components/parameters/nextPageToken"},{"name":"partName","in":"query","schema":{"type":"string"},"description":"Filter by part name (from the list parts response)."}],"responses":{"200":{"description":"Paginated list of download URLs.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"filesMetadata":{"type":"array","items":{"type":"object","properties":{"downloadURL":{"type":"string","description":"Signed URL to download the file."},"fileName":{"type":"string","description":"Original file name."},"partName":{"type":"string","nullable":true,"description":"Part name this file belongs to."},"shardId":{"type":"string","nullable":true,"description":"Shard ID (for bulk-upload batches)."},"contentType":{"type":"string","description":"Content type (e.g. `image`, `video`)."},"nestedContentType":{"type":"string","nullable":true,"description":"Nested content type, if applicable."}}},"description":"List of file metadata objects with download URLs."},"nextPageToken":{"type":"string","nullable":true,"description":"Token for fetching the next page of results. `null` if no more pages."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."},"nextPageToken":{"name":"nextPageToken","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination token from a previous response."}}}}
```

### Webhook 通知

ステータスをポーリングする代わりに、Webhook を使って取り込みまたは処理完了時に通知を受け取れます。 [CLI の使用方法](#webhook-automation) Webhook の設定とペイロード形式については、

## CLI

をインストールすると `inference-cli` にアクセスできるようになり、 `inference rf-cloud` コマンドを使用できます。これにより、Roboflow Batch Processing のコアコンポーネントである Batch Processing と Data Staging を操作できます。

### セットアップ

```bash
pip install inference-cli
export ROBOFLOW_API_KEY="YOUR-API-KEY-GOES-HERE"
```

クラウドストレージのサポートが必要な場合：

```bash
pip install 'inference-cli[cloud-storage]'
```

API キーの見つけ方については、 [認証ガイド](https://docs.roboflow.com/reference/authentication/authentication/find-your-roboflow-api-key).

### データを取り込む

#### 画像

```bash
inference rf-cloud data-staging create-batch-of-images \\
  --images-dir <your-images-dir-path> \\
  --batch-id <your-batch-id>
```

#### 動画

```bash
inference rf-cloud data-staging create-batch-of-videos \\
  --videos-dir <your-videos-dir-path> \\
  --batch-id <your-batch-id>
```

{% hint style="info" %}
**Batch ID の形式：** 小文字のみで、64 文字以下。使用できるのは英字、数字、ハイフン（`-`）、およびアンダースコア（`_`).
{% endhint %}

#### クラウドストレージ

データがすでにクラウドストレージ（S3、Google Cloud Storage、Azure）にある場合、ファイルをローカルにダウンロードせずに直接処理できます。

**画像の場合：**

```bash
inference rf-cloud data-staging create-batch-of-images \\
  --data-source cloud-storage \\
  --bucket-path <cloud-path> \\
  --batch-id <your-batch-id>
```

**動画の場合：**

```bash
inference rf-cloud data-staging create-batch-of-videos \\
  --data-source cloud-storage \\
  --bucket-path <cloud-path> \\
  --batch-id <your-batch-id>
```

次の `--bucket-path` パラメータは以下のプロバイダーをサポートしています。Glob パターンで取り込むファイルを絞り込みます：

| プロバイダー               | パス形式                        | Glob の例                                                       |
| -------------------- | --------------------------- | ------------------------------------------------------------- |
| S3                   | `s3://bucket-name/path/`    | `s3://my-bucket/training-data/**/*.jpg` - すべての JPG を再帰的に      |
| Google Cloud Storage | `gs://bucket-name/path/`    | `gs://my-bucket/videos/2024-*/*.mp4` - 以内の MP4 `2024-*` フォルダー |
| Azure Blob Storage   | `az://container-name/path/` | `az://container/images/*.png` - images フォルダー内の PNG            |

{% hint style="info" %}
クラウドストレージの認証情報は **ローカルでのみ** CLI によって署名付き URL を生成するために使用されます。これらは **アップロードされることは決してありません** Roboflow サーバーに。
{% endhint %}

{% hint style="warning" %}
生成された署名付き URL は 24 時間有効です。この時間内にバッチ処理ジョブが完了するようにしてください。
{% endhint %}

大規模データセットの場合、システムは自動的に画像を 20,000 ファイルごとのチャンクに分割します。動画は 1,000 未満のバッチで最も効果的です。

#### 署名付き URL による取り込み

高度な自動化では、ローカルファイルではなく署名付き URL 経由でデータを取り込めます：

| フラグ                             | 説明                                                   |
| ------------------------------- | ---------------------------------------------------- |
| `--data-source references-file` | 署名付き URL 経由で参照されたファイルを処理します。                         |
| `--references <path_or_url>`    | ファイル URL を含む JSONL ファイルへのパス、またはそのようなファイルを指す署名付き URL。 |

**参照ファイル形式（JSONL）：**

```
{"name": "<unique-file-name-1>", "url": "https://<signed-url>"}
{"name": "<unique-file-name-2>", "url": "https://<signed-url>"}
```

{% hint style="info" %}
署名付き URL による取り込みは、Growth Plan および Enterprise のお客様にご利用いただけます。
{% endhint %}

### ステージ済みデータを確認

```bash
inference rf-cloud data-staging show-batch-details --batch-id <your-batch-id>
```

### ジョブを開始

#### 画像を処理

```bash
inference rf-cloud batch-processing process-images-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --machine-type gpu
```

#### 動画を処理

```bash
inference rf-cloud batch-processing process-videos-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --machine-type gpu \\
  --max-video-fps <your-desired-fps>
```

{% hint style="info" %}
**Workflow ID の見つけ方：** Roboflow アプリで Workflow Editor を開き、「Deploy」をクリックし、コードスニペット内の識別子を見つけます。
{% endhint %}

{% hint style="info" %}
デフォルトでは、処理は CPU 上で実行されます。 `--machine-type gpu` を複数のモデルや大規模モデルを含む Workflow に使用します。
{% endhint %}

### ジョブの進行状況を監視

開始コマンドは **ジョブ ID**を出力します。ステータス確認に使用します：

```bash
inference rf-cloud batch-processing show-job-details --job-id <your-job-id>
```

### 結果をエクスポート

ジョブの詳細には **出力バッチ ID**が含まれます。結果のエクスポートに使用します：

```bash
inference rf-cloud data-staging export-batch \\
  --target-dir <dir-to-export-result> \\
  --batch-id <output-batch-of-a-job>
```

### Webhook 自動化

ステータスをポーリングする代わりに、Webhook を使って取り込みまたは処理完了時に通知を受け取れます。

#### データ取り込み Webhook

CLI コマンド `create-batch-of-images` および `create-batch-of-videos` は以下をサポートします：

| フラグ                                     | 説明                      |
| --------------------------------------- | ----------------------- |
| `--notifications-url <webhook_url>`     | 通知用の Webhook エンドポイント。   |
| `--notification-category ingest-status` | 取り込みプロセス全体のステータス。デフォルト。 |
| `--notification-category files-status`  | 各ファイルの処理ステータス。          |

通知は HTTP POST で送信され、 `Authorization` ヘッダーには Roboflow の Publishable Key が含まれます。

**取り込みステータス通知**

```json
{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8c20f970-fe10-41e1-9ef2-e057c63c07ff",
    "ingest_id": "8cd48813430f2be70b492db67e07cc86",
    "batch_id": "test-batch-117",
    "shard_id": null,
    "notification": {
        "type": "ingest-status-notification-v1",
        "success": false,
        "error_details": {
            "type": "unsafe-url-detected",
            "reason": "信頼できないドメインが見つかりました: https://example.com/image.png"
        }
    },
    "delivery_attempt": 1
}
```

**ファイルステータス通知**

```json
{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
    "ingest_id": "d5cb69aa-b2d1-4202-a1c1-0231f180bda9",
    "batch_id": "prod-batch-1",
    "shard_id": "0d40fa12-349e-439f-83f8-42b9b7987b33",
    "notification": {
        "type": "ingest-files-status-notification-v1",
        "success": true,
        "ingested_files": [
            "000000494869.jpg",
            "000000186042.jpg"
        ],
        "failed_files": [
            {
                "type": "file-size-limit-exceeded",
                "file_name": "big_image.png",
                "reason": "単一画像の最大サイズは 20971520B です。"
            }
        ],
        "content_truncated": false
    },
    "delivery_attempt": 1
}
```

#### ジョブ完了 Webhook

追加する `--notifications-url` をジョブ開始時に指定します：

```bash
inference rf-cloud batch-processing process-images-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --notifications-url <webhook_url>
```

**ジョブ完了通知**

```json
{
  "type": "roboflow-batch-job-notification-v1",
  "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
  "job_id": "<your-batch-job-id>",
  "job_state": "success | fail",
  "delivery_attempt": 1
}
```

### クラウドストレージ認証

#### AWS S3 と S3 互換ストレージ

認証情報は以下から自動的に検出されます：

1. **環境変数：**

```bash
export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token  # オプション
```

2. **AWS 認証情報ファイル** (`~/.aws/credentials`, `~/.aws/config`)
3. **IAM ロール** (EC2、ECS、Lambda)

**名前付きプロファイル：**

```bash
export AWS_PROFILE=production
```

**S3 互換サービス（Cloudflare R2、MinIO など）：**

```bash
export AWS_ENDPOINT_URL=https://account-id.r2.cloudflarestorage.com
export AWS_REGION=auto  # R2 では region='auto' が必要です
export AWS_ACCESS_KEY_ID=your-r2-access-key
export AWS_SECRET_ACCESS_KEY=your-r2-secret-key
```

#### Google Cloud Storage

認証情報は以下から検出されます：

1. **サービスアカウント キーファイル** （自動化に推奨）：

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
```

2. **ユーザー認証情報** gcloud CLI から（`gcloud auth login`)
3. **GCP メタデータサービス** （Google Cloud Platform 上で実行している場合）

#### Azure Blob Storage

**SAS トークン（推奨）：**

```bash
export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_SAS_TOKEN="sv=2021-06-08&ss=b&srt=sco&sp=rl&se=2024-12-31"
```

**アカウントキー：**

```bash
export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_ACCOUNT_KEY=your-account-key
```

Azure CLI で SAS トークンを生成します：

```bash
az storage container generate-sas \\
  --account-name mystorageaccount \\
  --name my-container \\
  --permissions rl \\
  --expiry 2024-12-31T23:59:59Z
```

#### カスタムスクリプト

高度なユースケースでは、署名付き URL ファイルを生成するためのスクリプトを参照してください：

* **AWS S3：** [generateS3SignedUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateS3SignedUrls.sh)
* **Google Cloud Storage：** [generateGCSSignedUrls.sh](https://github.com/roboflow/roboflow-python/blob/main/scripts/generateGCSSignedUrls.sh)
* **Azure Blob Storage：** [generateAzureSasUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateAzureSasUrls.sh)

### すべてのオプションを確認

```bash
inference rf-cloud --help
inference rf-cloud data-staging --help
inference rf-cloud batch-processing --help
```