適切なツールの選び方

CLI、Python SDK、または REST API をいつ使うか。

Roboflow は 3 つの開発者ツールを通じて同じ基盤プラットフォームを提供しています。これらは相互排他的ではありません - ほとんどの本番ワークフローでは 3 つすべてを使います。このページは簡単な判断ガイドです。

ひと目でわかる

	CLI	Python SDK	REST API
最適な用途	アドホックなスクリプト、AI エージェント、シェル自動化	ノートブック、スケジュール済みジョブ、Python アプリケーション	Python 以外のサービス、webhook、エッジデバイス
認証	ROBOFLOW_API_KEY 環境変数または roboflow login	API キーを渡す Roboflow(...) または ROBOFLOW_API_KEY	Authorization: Bearer ヘッダー（クエリパラメータは旧方式）
出力	デフォルトでは整形済みテーブル、 --json スクリプト用に	Python の dict とオブジェクト	JSON
インストール	pip install roboflow	pip install roboflow	なし
対象範囲	SDK に追随; エージェント向け	REST API と同等、加えて便利なヘルパー	権威ある実装 - すべての機能はまずここに出ます
エラー	終了コード（0 / 1 / 2 / 3）+ stderr の JSON エラーボディ	Python 例外	HTTP ステータスコード + JSON エラーボディ

CLI を使うべき場面

CLI は、何かをしたいときに使います 一度だけ、またはシェルパイプラインの一工程として。出力形式と終了コードは、スクリプトや AI エージェント向けに設計されています。

具体的には:

• Python を書かずに素早く結果を見たいプロトタイピング中です。

• Roboflow の操作を他のツールにパイプしたいです（roboflow project list --json | jq …).

• Claude Code や Cursor のような AI コーディングエージェントを使っている場合、CLI の構造化された JSON 出力と安定した終了コードのほうが、Python REPL よりもエージェントにとって扱いやすいです。

• あなたは Makefile、GitHub Action、または画像をアップロードし、学習を開始し、あるいはデータセットをダウンロードするシェルスクリプトを書いています。

参照 CLI.

Python SDK を使うべき場面

すでに Python を使っていて、 型付きオブジェクト、慣用的なヘルパー、クロスコールの状態が欲しい場合は SDK を使います。SDK は REST API の薄いラッパーですが、次のものが追加されます:

• ワークスペース / プロジェクト / バージョン / モデル 発見しやすいメソッドを持つオブジェクト。

• 並列アップロード（upload_dataset(num_workers=10)).

• 予測可視化ヘルパー（完全な roboflow パッケージがインストールされている場合 - roboflow-slim).

• 推論とアップロードを組み合わせたアクティブラーニングループ。

• vision-events の取り込みに直接アクセス。

具体的には:

• データセットを反復しながら調整している Jupyter ノートブック内にいます。

• 必要に応じてアップロード、学習、推論を行う Python サービスを構築しています。

• 操作を連鎖させる必要があります（アップロード → 学習 → 準備完了まで待機 → 予測）。

• 既存の Python アプリに Roboflow を組み込んでいます。

参照 Python SDK.

REST API を使うべき場面

REST API を使うのは、 Python を使っていないとき、Python パッケージをインストールできない環境（ブラウザ、Cloudflare Worker、組み込みデバイス、容量の小さい zipfile の Lambda など）から呼び出す必要があるとき、または webhook から Roboflow を利用したいときです。

具体的には:

• JavaScript / TypeScript / Go / Rust のクライアントを構築しています。

• 独自ファームウェアで動作する webcam やセンサーからイベントを送信しています。

• Zapier / n8n / ノーコード自動化ツールと連携する必要があります。

• 特定の機能が SDK に搭載される前に REST API で提供されます。

参照 REST API.

ツールの併用

実際には、チームは 3 つすべてを使っています:

• CI/CD は CLI を使ってデータセットをアップロードし、学習を開始します。

• Python のデータパイプライン は SDK を使って学習結果に反応し、モデルバージョンを調整します。

• 本番アプリ は REST API を使って推論を実行し、イベントを送信します。

同じワークスペースと API キーで 3 つすべてに認証できるので、認証情報が増殖しません。

推論は特別です

学習済みモデルを画像や動画で実行する場合、これら 3 つ以外にも追加の選択肢があります。ホスト型推論は Roboflow Serverless Hosted API の serverless.roboflow.comで実行されます。より高いスループットやオンプレミス用途については、 Roboflow Inference （セルフホスト）と 専用デプロイ （管理された GPU マシン）を参照してください。

CLI の infer コマンド、SDK の model.predict()、そして推論 URL への直接 REST 呼び出しは、いずれも同じ基盤推論エンジンへの経路です。

推論リクエストの認証は、プラットフォームの REST API とも異なります。推論 URL を直接呼び出す場合は、API キーを Authorization: Bearer ヘッダーとして送信してください。ヘッダーにすることで、キーが URL やサーバーログに残りません。キーを api_key クエリパラメータまたはボディフィールドとして渡すのは旧方式です。すべてのサーバーバージョンで動作しますが、新しいコードでは推奨されません。 inference-sdkを使う場合は、ヘッダーを自分で組み立てる代わりにクライアントで一度トランスポートを設定します。参照: API キーの転送.