Ultralytics YOLO27:
Get Started

APIキー#

Ultralytics Platform のAPIキーを使用すると、リモートトレーニング、推論、自動化のための安全なプログラムアクセスが可能になります。用途ごとに名前を付けたキーを作成し、AES-256-GCM暗号化で保護できます。

Ultralytics Platformの設定画面にあるAPI Keysタブのキー一覧

オーナーのみ

ワークスペースオーナーだけが、ワークスペースの Ultralytics API keys を作成、表示、または取り消すことができます。これらのキーはワークスペースオーナーとして認証されるためです。他のメンバーはキー一覧を表示できません。外部プロバイダーの接続状況は確認できますが、プロバイダーキーの全体を表示したり、接続を変更したりすることはできません。APIキー自体を使って、他のAPIキーを作成または取り消すことはできません。例外は On Premise worker keys で、On Premise統合からホストを切断すると取り消されます。

APIキーを作成#

新しいAPIキーを作成します:

  1. Settings > API Keys に移動します
  2. Add Key をクリックし、プロバイダーとして Ultralytics を選択します
  3. キーの名前を入力します（例: "Training Server"）
  4. Create Key をクリックします

Ultralytics Platformの設定画面にあるAPI KeysタブのAPIキー作成ダイアログ

キー名#

キーの用途がわかる名前を付けます:

  • training-server - リモートトレーニングマシン用
  • ci-pipeline - CI/CD統合用
  • local-dev - ローカル開発用

キーの表示#

作成後、確認ダイアログにキーが表示されます:

Ultralytics Platformの設定画面にあるAPI KeysタブのAPIキー作成完了・コピー用ダイアログ

キーをコピー

作成後、キーをコピーしてすぐに参照できるようにしてください。キー一覧にあるコピー button はいつでも使用できます。一覧には各キーのプレフィックスのみが表示されます。

エージェントとアノテーション用のプロバイダーキー#

同じ Settings > API Keys タブには、Agents が使用する外部モデルプロバイダーのキーと、クラスプロンプトによるアノテーション の有料モデル用キーも保存されます。アノテーションでは、データセットのワークスペースに保存されているキーが使用されます。これらのキーを追加、置き換え、削除できるのはワークスペースオーナーだけです。チームメンバーは接続済みのプロバイダーを確認できます。必要なプロバイダーが接続されていない場合は、オーナーに接続を依頼してください。オーナーとしてプロバイダーを接続するには:

  1. Add Key をクリックします。
  2. ワークフローで使用する言語モデルまたは視覚言語モデル、あるいは実行するアノテーションモデルに対応するプロバイダーを選択します。
  3. そのプロバイダーのAPIキーを API Key に貼り付け、Save Key をクリックします。ダイアログの Get an API key リンクをクリックすると、プロバイダーのキー取得ページが開きます。

Ultralyticsキーでは、外部モデルプロバイダーの認証はできません。プロバイダーの利用料金は、保存したキーに関連付けられたプロバイダーアカウントに請求されます。プロバイダーキーを置き換えるには、キー行の編集コントロールを使用します。

Google Geminiをプロバイダーとして選択したUltralytics PlatformのAPIキー追加ダイアログ

キーの形式#

APIキーは次の形式です:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • プレフィックス: ul_ はUltralyticsキーを示します
  • 本体: 40文字のランダムな16進数
  • 合計: 43文字

キーのセキュリティ#

  • キーはAES-256-GCM暗号化で保存され、平文で保存されることはありません
  • 先頭の11文字（ul_ と8桁の16進数）は表示用プレフィックスとして使用されるため、キーを公開せずに識別できます

APIキーの使用#

環境変数#

キーを環境変数として設定します:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Python>=3.11でYOLO CLIを使用して、キーを検証して保存します:

yolo login YOUR_API_KEY

保存したキーを yolo logout で削除します。

HTTPヘッダー#

APIリクエストにキーを含めます:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

または、Python SDK（pip install "ultralytics-platform>=0.1.45"）に渡すこともできます。api_key が省略されている場合、Python SDKは ULTRALYTICS_API_KEY または yolo login で保存されたキーを読み込みます:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

利用可能なすべてのエンドポイントについては、REST APIリファレンス をご覧ください。

リモートトレーニング#

キーを使用してメトリクスストリーミングを有効にします。

開始する前に、Python>=3.11にUltralyticsパッケージをインストールするか、最新バージョンに更新してください:

pip install -U ultralytics
export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

リモートトレーニングの詳細なガイドについては、クラウドトレーニング をご覧ください。

キーの管理#

キーの表示#

すべてのキーは Settings > API Keys タブに一覧表示されます:

各キーの行には、キー名、キーのプレフィックス、作成日、キー全体をコピーするボタン、削除（ゴミ箱）ボタンが表示されます。

キーの取り消し#

侵害されたキーや不要になったキーを取り消します:

  1. API Keysセクションでキーを見つけます
  2. 削除（ゴミ箱）ボタンをクリックします
  3. Remove Key をクリックして確定します
即時に反映

取り消しは即時に反映され、元に戻せません。キーは無効化されるのではなく、レコード自体が削除されます。そのキーを使用しているアプリケーションは動作しなくなります。

キーの再生成#

キーが侵害された場合:

  1. 同じ名前で新しいキーを作成します
  2. アプリケーションを更新します
  3. 古いキーを取り消します

ワークスペースのAPIキー#

APIキーは、現在アクティブなワークスペースに紐付けられます:

  • 個人ワークスペース: キーは個人アカウントとして認証されます
  • チームワークスペース: キーはチームワークスペースオーナーとして認証され、そのワークスペース内でオーナーのすべての権限を持ちます

サイドバーでワークスペースを切り替えると、API Keysセクションにはそのワークスペースのキーが表示されます。ワークスペースキーにはオーナー権限があるため、作成、表示、取り消しができるのはワークスペースオーナーだけです。ロールの詳細については、チーム をご覧ください。

On Premiseワーカーキー#

On Premise ホストを接続すると、専用のワーカーキーが発行されます。ワーカーキーはこのタブではなくOn Premise統合から管理され、APIキーと一緒に一覧表示されることはありません。ホストを切断するとキーが取り消され、そのホストでキューに登録済みまたは実行中のジョブもキャンセルされます。

セキュリティのベストプラクティス#

推奨事項#

  • キーを環境変数に保存します
  • 環境ごとに別のキーを使用します
  • 使用していないキーは速やかに取り消します
  • キーを定期的にローテーションします
  • キーの用途を識別できるわかりやすい名前を付けます

禁止事項#

  • キーをバージョン管理にコミットする
  • アプリケーション間でキーを共有する
  • アプリケーションの出力にキーを記録する
  • クライアント側のコードにキーを埋め込む

キーのローテーション#

セキュリティのため、キーを定期的にローテーションしてください。

  1. 同じ名前で新しいキーを作成します
  2. 新しいキーを使用するようにアプリケーションを更新します
  3. アプリケーションが正しく動作することを確認します
  4. 古いキーを失効させます
ローテーションのスケジュール

機密性の高いアプリケーションでは、90日ごとにキーをローテーションすることを検討してください。

トラブルシューティング#

無効なキーエラー#

Error: Invalid API key

解決策：

  1. キーが正しくコピーされていることを確認します（ul_ プレフィックスも含む）
  2. キーが失効していないことを確認します
  3. 環境変数が設定されていることを確認します
  4. Python>=3.11とultralytics>=8.4.120を使用していることを確認します

アクセス拒否#

Error: Permission denied for this operation

解決策：

  1. リソースの所有者であるか、適切なワークスペースアクセス権があることを確認します
  2. キーが正しいワークスペースに属していることを確認します
  3. チームワークスペースでキーを管理している場合は、自分がワークスペースの所有者であることを確認してください。ほかのロールにはWorkspace owner access requiredが付与されます
  4. 必要に応じて新しいキーを作成します

レート制限#

Error: Rate limit exceeded

解決策：

  1. リクエスト頻度を下げてください。カテゴリごとの制限については、レート制限の表を参照してください
  2. Retry-Afterヘッダーを使用して、指数バックオフを実装します
  3. 推論容量を分離する必要がある場合は、専用エンドポイントを使用してください

よくある質問#

  • APIキーに厳格な上限はありません。アプリケーションや環境ごとに必要な数だけ作成できます。

  • キーは自動的に期限切れになりません。失効させるまで有効です。セキュリティのため、ローテーションの実施を検討してください。

  • はい。Settings > API Keysのキー一覧には各キーのプレフィックスが表示され、コピーボタンを使うといつでもキーの完全な値をコピーできます。

  • キーはリージョンをまたいで使用できますが、アクセスできるデータはアカウントのリージョン内に限られます。

  • いいえ。チームワークスペースのキーはワークスペースの所有者として認証されるため、キーを作成または表示できるのは所有者のみであり、共有すると所有者の権限を渡すことになります。各メンバーは自身の個人ワークスペースでキーを作成し、CIなどの共有自動化には、所有者に専用のワークスペースキーを発行してもらってください。

  • いいえ。キーは作成されたワークスペースに属し、そのワークスペースのリソースにのみアクセスできます。自動化するワークスペースごとに別のキーを作成してください。

コントリビューター
GLglenn-jocher18RAraimbekovm4SEsergiuwaxmann2LAlaodouya1MYmykolaxboiko1LALaughing-q1

コメント