Documentation Oracle Cloud Infrastructure

Clés d'API

Les clés d'API OCI Generative AI sont des jetons d'informations d'identification sécurisés utilisés pour authentifier les appelants et autoriser l'accès aux grands modèles de langage hébergés par le service OCI Generative AI.

A propos de la clé d'API

Une clé d'API OCI Generative AI est un jeton secret (chaîne) propre au service OCI Generative AI. Vous pouvez générer une clé d'API et l'utiliser pour accéder aux grands modèles de langage hébergés par le service.

Cette clé d'API est différente d'une clé d'API IAM OCI, qui utilise une paire de clés publique/privée pour fournir un accès à la location OCI général.

Fonctionnement de la clé d'API

Chaque clé d'API OCI Generative AI inclut deux clés secrètes distinctes, telles que key-one et key-two. Les deux clés secrètes sont des chaînes uniques.

  • Vous créez la clé d'API via le service d'IA générative, nommez et définissez des dates d'expiration pour ses deux clés secrètes.
  • Chaque clé secrète fournit le même niveau d'accès et est liée à la même clé d'API. Vous pouvez utiliser les deux clés secrètes de manière interchangeable dans les applications.
  • Lorsque votre application appelle une adresse de modèle OCI Generative AI, incluez l'une ou l'autre clé secrète dans l'en-tête d'autorisation.
Important

La clé d'API doit se trouver dans la même région que le modèle avec lequel vous voulez l'utiliser.

Utilisation de la clé d'API

Vous pouvez générer des clés d'API OCI Generative AI et les utiliser pour accéder à des adresses de modèle de langage volumineuses hébergées par le service d'IA générative à l'aide de l'API REST ou du kit SDK openai natif. Voici les étapes à suivre pour utiliser les clés d'API.

  1. Dans OCI Generative AI, créez une clé d'API dans une région prise en charge pour le modèle à utiliser.
  2. Dans OCI IAM, ajoutez des droits d'accès de clé d'API.
  3. Utilisez cette clé lorsque vous appelez un modèle pris en charge dans une région prise en charge via l'une des options suivantes :

Modèles pris en charge

Modèles pour l'API d'achèvement des discussions
Modèles pour l'API Réponses
Important

Appels externes aux modèles Grok xAI

Les modèles xAI Grok sont hébergés dans un centre de données OCI, dans une location provisionnée pour xAI. Les modèles xAI Grok, accessibles via le service OCI Generative AI, sont gérés par xAI.

Utilisation de clés d'API avec l'API REST

Vous pouvez utiliser les clés d'API dans les en-têtes de l'API REST et de curl. Voici les adresses que vous pouvez utiliser pour l'API REST.

Adresses prises en charge

Déclarations de fin de discussion
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/chat/completions
réponses
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/responses

Exemple d'utilisation de 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?"
    }
]
}'

Utilisation de clés d'API avec les kits SDK OpenAI

Vous pouvez utiliser les clés d'API avec le kit SDK OpenAI. Voici les adresses pouvant être utilisées pour le kit SDK OpenAI.

Adresses prises en charge

Indiquez base_url en tant que 
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1
Déclarations de fin de discussion
Utilisez la méthode suivante : client.chat.completions.create
réponses
Utilisez la méthode suivante : client.responses.create
Exemple
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)
Référence
Référentiel Oracle GitHub

Régions prises en charge

Régions

Pour les kits SDK OpenAI, les régions OCI prises en charge à utiliser avec les clés d'API sont limitées à :

  • Allemagne centrale (Francfort)
  • Sud de l'Inde (Hyderabad)
  • Centre du Japon (Osaka)
  • Est des Etats-Unis (Ashburn)
  • Midwest des Etats-Unis (Chicago)
  • Ouest des Etats-Unis (Phoenix)

Pour confirmer les régions utilisables d'un modèle pour le package OCI OpenAI, effectuez les tâches suivantes.

  1. Ouvrez la carte du modèle dans la documentation sur l'IA générative :
  2. Notez les régions répertoriées pour ce modèle.
  3. Sélectionnez une région pour le modèle qui apparaît dans les régions disponibles du modèle ET dans les six régions OCI OpenAI précédentes.
  4. Vérifiez si le modèle est disponible dans le mode dont vous avez besoin (à la demande ou dédié).

    Pour accéder aux modèles en mode dédié, les adresses publiques et privées sont prises en charge.

Rotation ou remplacement d'une clé

Pour effectuer la rotation d'une clé d'API OCI Generative AI, vous pouvez modifier son état dans la console OCI ou à l'aide de l'opération SetApiKeyState avec l'API. Voici les étapes à suivre :

  1. Activez la clé secrète de secours. Activez la clé secrète inutilisée (par exemple, key-two) et mettez à jour vos applications pour l'utiliser.
  2. Vérifiez le basculement. Vérifiez que les demandes s'authentifient avec la clé secrète nouvellement activée et que les charges globales se poursuivent sans interruption.
  3. Révoquer ou désactiver la première clé secrète.
    • Si vous soupçonnez une fuite ou qu'il est temps de retirer le premier secret, révoquez-le. Une fois la modification propagée, les demandes utilisant la clé secrète révoquée sont rejetées. La révocation d'un secret le désactive définitivement et l'action est irréversible.
    • Si vous prévoyez de réutiliser la première clé secrète, désactivez-la. Une fois la modification propagée, les demandes utilisant la clé secrète désactivée sont rejetées jusqu'à ce que vous la réactiviez.
    Conseil

    Désactiver un secret pour une suspension ou une enquête à court terme. Révoquez une clé secrète si elle a été compromise ou si vous devez la retirer définitivement.

Pour connaître les étapes à suivre pour effectuer ces tâches, reportez-vous à Gestion des clés d'API.

Important

Copiez immédiatement les clés secrètes nouvelles ou régénérées et stockez-les en toute sécurité. Ils n'apparaissent qu'une fois.

Meilleures pratiques

Stockez toujours les clés secrètes d'API OCI Generative AI dans un gestionnaire de clés secrètes approuvé. Ne les validez jamais dans le contrôle source ou ne les intégrez jamais dans le code côté client.

  • Utilisez la configuration à deux clés secrètes pour une rotation fluide et sans temps d'arrêt, et définissez des expirations pour actualiser régulièrement les clés.
  • Limitez l'accès aux clés à l'aide de compartiments et de stratégies de moindre privilège.
  • Surveillez l'utilisation, configurez des alertes et effectuez une rotation immédiate des clés si vous détectez des activités suspectes.

Gestion des clés d'API

Après avoir obtenu le droit d'accès IAM pour la ressource de clé d'API OCI Generative AI, vous pouvez gérer les clés d'API à l'aide des opérations suivantes :

Exemples sur GitHub

Pour une expérience pratique, reportez-vous à des exemples dans le référentiel Oracle GitHub.