Oracle Cloud Infrastructureドキュメント

APIキー

OCI生成AI APIキーは、コール元を認証し、OCI生成AIサービスによってホストされる大規模言語モデルへのアクセスを認可するために使用されるセキュアな資格証明トークンです。

APIキーについて

OCI生成AI APIキーは、OCI生成AIサービスに固有のシークレット・トークン(文字列)です。APIキーを生成し、それを使用してサービスによってホストされる大規模言語モデルにアクセスできます。

このAPIキーは、公開キーと秘密キー・ペアを使用して一般的なOCIテナンシ・アクセスを提供するOCI IAM APIキーとは異なります。

APIキーの仕組み

各OCI生成AI APIキーには、key-oneやkey-twoなどの2つの異なるシークレットが含まれています。両方の秘密は一意の文字列です。

  • 生成AIサービスを使用してAPIキーを作成し、その2つのシークレットに有効期限を設定します。
  • 各シークレットは、同じレベルのアクセスを提供し、同じAPIキーに関連付けられます。アプリケーションでは、どちらかのシークレットを同じ意味で使用できます。
  • アプリケーションがOCI生成AIモデル・エンドポイントをコールする場合は、認可ヘッダーにいずれかのシークレットを含めます。
重要

APIキーは、それを使用するモデルと同じリージョンにある必要があります。

APIキーの使用方法

OCI生成AI APIキーを生成し、それらを使用して、REST APIまたはネイティブのopenai SDKを使用して生成AIサービスによってホストされる大規模言語モデル・エンドポイントにアクセスできます。APIキーを使用するステップは次のとおりです。

  1. OCI生成AIで、使用するモデルのサポートされているリージョンにAPIキーを作成します。
  2. OCI IAMで、APIキー権限の追加を行います。
  3. このキーは、次のオプションを使用して、サポートされているリージョンでサポートされているモデルをコールする場合に使用します。

サポートされるモデル

チャット完了APIのモデル
レスポンスAPIのモデル
重要

外部コール

xAI Grokモデルは、xAI用にプロビジョニングされたテナンシ内のOCIデータ・センターでホストされます。OCI Generative AIサービスを介してアクセスできるxAI Grokモデルは、xAIによって管理されます。

REST APIでのAPIキーの使用

APIキーは、REST APIおよびcurlのヘッダーで使用できます。REST APIに使用できるエンドポイントを次に示します。

サポートされているエンドポイント

チャット完了
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/chat/completions
レスポンス
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/responses

curlの使用例:

curl 
--location 'https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1/chat/completions' \
--header 'Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"model": "xai.grok-4",
"messages": [
    {
    "role": "user",
    "content": "What's the capital of France?"
    }
]
}'

OpenAI SDKでのAPIキーの使用

APIキーは、OpenAI SDKとともに使用できます。OpenAI SDKに使用できるエンドポイントを次に示します。

サポートされているエンドポイント

次のようにbase_urlを指定します。 
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1
チャット完了
このメソッドの使用: client.chat.completions.create
レスポンス
次の方法を使用します: client.responses.create
例
from openai import OpenAI
import os

API_KEY=os.getenv("OPENAI_API_KEY")

print(API_KEY)

client = OpenAI(
    api_key=API_KEY,
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1"
)

# Responses API
response = client.responses.create(
    model="openai.gpt-oss-120b",
    # model="xai.grok-3",
    # meta models are not supported with the Responses API
    input="Write a one-sentence bedtime story about a unicorn."
)
print(response)

# Completion API
response = client.chat.completions.create(
    # model="openai.gpt-oss-120b",
    # model="meta.llama-3.3-70b-instruct",
    model="xai.grok-3",
    messages=[{
        "role": "user", 
        "content": "Write a one-sentence bedtime story about a unicorn."
        }
    ]
)
print(response)
参照
Oracle GitHubリポジトリ

サポートされるリージョン

リージョン

OpenAI SDKの場合、APIキーで使用するサポートされているOCIリージョンは、次のものに制限されます:

  • ドイツ中央部(フランクフルト)
  • インド南部(ハイデラバード)
  • 日本中央部(大阪)
  • 米国東部(アッシュバーン)
  • 米国中西部(シカゴ)
  • 米国西部(フェニックス)

OCI OpenAIパッケージのモデルの使用可能なリージョンを確認するには、次のタスクを実行します。

  1. 生成AIドキュメントでモデルのカードを開きます。
  2. そのモデルにリストされているリージョンに注意してください。
  3. モデルの使用可能なリージョンと前述の6つのOCI OpenAIリージョンの両方に表示されるモデルのリージョンを選択します。
  4. モデルが必要なモード(オンデマンドまたは専用)で使用可能かどうかを確認します。

    専用モードでモデルにアクセスする場合、パブリック・エンドポイントとプライベート・エンドポイントの両方がサポートされます。

キーのローテーションまたは置換

OCI生成AI APIキーをローテーションするには、OCIコンソールで、またはAPIでSetApiKeyState操作を使用して、その状態を変更します。次にステップを示します。

  1. スタンバイ・シークレットをアクティブ化します。 未使用のシークレット(key-twoなど)をアクティブ化し、それを使用するようにアプリケーションを更新します。
  2. フェイルオーバーを確認します。 リクエストが新しくアクティブ化したシークレットで認証され、ワークロードが中断せずに続行されていることを確認します。
  3. 最初のシークレットを取り消すか非アクティブ化します。
    • リークが疑われる場合、または最初のシークレットをリタイアする時間になった場合は、それを取り消します。変更が伝播されると、取り消されたシークレットを使用するリクエストは拒否されます。シークレットを取り消すと、シークレットは永続的に無効化され、アクションは元に戻せません。
    • 最初のシークレットを再利用する場合は、非アクティブ化します。変更が伝播されると、非アクティブ化されたシークレットを使用するリクエストは、再アクティブ化するまで拒否されます。
    ヒント

    短期的な停止または調査のためにシークレットを非アクティブ化します。シークレットが漏洩した場合、またはシークレットを完全にリタイアする必要がある場合は、シークレットを取り消します。

これらのタスクを実行するステップは、APIキーの管理を参照してください。

重要

新規または再生成されたシークレットをすぐにコピーし、安全に格納します。一度だけ現れます。

ベスト・プラクティス

OCI生成AI APIキー・シークレットは、常に承認済シークレット・マネージャに格納してください。ソース・コントロールにコミットしたり、クライアント側のコードに埋め込んだりしないでください。

  • スムーズでゼロ・ダウンタイムのローテーションには2つのシークレット設定を使用し、キーを定期的にリフレッシュするように期限切れを設定します。
  • コンパートメントおよび最小権限ポリシーを使用して、キーへのアクセスを制限します。
  • 疑わしいアクティビティを検出すると、使用状況を監視し、アラートを設定し、キーをすぐにローテーションできます。

APIキーの管理

OCI生成AI APIキー・リソースのIAM権限を取得した後、次の操作を使用してAPIキーを管理できます:

GitHubの例

ハンズオン・エクスペリエンスについては、Oracle GitHubリポジトリの例を参照してください。