Ultralytics YOLO27:

APIキー#

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

Ultralytics Platform Settings API Keys Tab Key List

所有者のみ

ワークスペースのオーナーのみがワークスペースのUltralytics API keysを作成、表示、または無効化できます。これは、これらのキーがワークスペースのオーナーとして認証を行うためです。他のメンバーはそのキーリストを表示できません。外部プロバイダーの接続ステータスは確認できますが、プロバイダーの完全なキーを表示したり、それらの接続を変更したりすることはできません。APIキー自体で他のAPIキーを作成または無効化することはできません。唯一の例外はOn Premise worker keysであり、これらはホストをオンプレミス統合から切断することで無効化されます。

APIキーの作成#

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

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

Ultralytics Platform Settings API Keys Tab Create API Key Dialog

キー名#

キーを識別しやすい名前にします。

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

キーの表示#

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

Ultralytics Platform Settings API Keys Tab API Key Created Copy Dialog

キーをコピー

作成後、簡単に参照できるようにキーをコピーしてください。キーリスト内のコピーボタンをいつでも使用することもできます。リストには各キーのプレフィックスのみが表示されます。

エージェント用プロバイダーキー#

同じSettings > API Keysタブには、Agentsで使用される外部モデルプロバイダーのキーも保存されます。ワークスペースのオーナーのみがこれらのキーの追加、置換、または削除を行うことができ、チームメンバーはどのプロバイダーが接続されているかを確認できます。不足しているプロバイダーを接続するには、オーナーに依頼してください。オーナーとしてプロバイダーを接続するには:

  1. Add Keyをクリックします。
  2. ワークフローの言語モデルまたはビジョン言語モデルに一致するプロバイダーを選択します。
  3. そのプロバイダーのAPIキーをAPI Keyに貼り付け、Save Keyをクリックします。ダイアログのGet an API keyリンクから、プロバイダーのキーページが開きます。

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

Ultralytics Platform Add API Key dialog with Google Gemini selected as the provider

キーの形式#

APIキーは次の形式です。

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • Prefix: ul_はUltralyticsのキーを識別します
  • Body: 40個のランダムな16進文字
  • Total: 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 が省略された場合に ULTRALYTICS_API_KEY または yolo login によって保存されたキーが読み取られます。

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

利用可能なすべてのエンドポイントについては、REST API Referenceを参照してください。

リモートトレーニング#

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

開始する前に、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

完全なリモートトレーニングガイドについては、Cloud Trainingを参照してください。

キーの管理#

キーの表示#

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

各キーカードには、キー名、コピー可能なキー値、相対的な作成時刻、失効ボタンが表示されます。

キーの失効#

侵害されたキー、または不要になったキーを失効させます。

  1. API Keysセクションでキーを見つけます
  2. Revoke（ごみ箱）ボタンをクリックします
  3. 失効を確認します
即時反映

失効は即時かつ永続的です。キーのレコードは無効化されるのではなく削除されます。そのキーを使用しているアプリケーションは動作しなくなります。

キーの再生成#

キーが侵害された場合:

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

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

APIキーは現在アクティブなワークスペースにスコープされます。

  • Personal workspace: キーは個人アカウントとして認証されます
  • Team workspace: キーはチームワークスペースの所有者として認証され、そのワークスペースで完全な所有者権限を持ちます

サイドバーでワークスペースを切り替えると、API Keysセクションにはそのワークスペースのキーが表示されます。ワークスペースキーには所有者権限が付与されるため、作成、表示、失効ができるのはワークスペース所有者だけです。ロールの詳細についてはTeamsを参照してください。

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. リクエスト頻度を下げます。カテゴリごとの制限についてはrate limit tableを参照してください
  2. Retry-Afterヘッダーを使用して指数バックオフを実装します
  3. 分離された推論キャパシティが必要な場合は、専用エンドポイントを使用してください

FAQ#

  • APIキーに厳格な上限はありません。異なるアプリケーションや環境に必要な数だけ作成してください。

  • キーは自動的には期限切れになりません。取り消すまで有効です。セキュリティ対策として、ローテーションの実装を検討してください。

  • はい、キーの完全な値は Settings > API Keys のキー一覧に表示されます。Platformはキーを復号して表示するため、いつでもコピーできます。

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

  • いいえ — チームworkspaceのキーはworkspace所有者として認証されるため、作成または表示できるのは所有者のみであり、共有すると所有者権限を引き渡すことになります。各メンバーには、それぞれの個人workspaceでキーを作成してもらってください。また、CIなどの共有オートメーション用に、所有者に専用のworkspaceキーを発行してもらってください。

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

貢献者
GLglenn-jocher17RAraimbekovm2SEsergiuwaxmann2LAlaodouya1MYmykolaxboiko1LALaughing-q1

コメント