Documentación de Oracle Cloud Infrastructure

Claves de API

Las claves de API de OCI Generative AI son tokens de credenciales seguras que se utilizan para autenticar a los emisores de llamadas y autorizar el acceso a grandes modelos de lenguaje alojados por el servicio OCI Generative AI.

Acerca de la clave de API

Una clave de API de OCI Generative AI es un token secreto (una cadena) específico del servicio OCI Generative AI. Puede generar una clave de API y utilizarla para acceder a los grandes modelos de lenguaje alojados por el servicio.

Esta clave de API es diferente de una clave de API de IAM de OCI, que utiliza un par de claves pública/privada para proporcionar un acceso de arrendamiento de OCI general.

Cómo funciona la clave de API

Cada clave de API de OCI Generative AI incluye dos secretos independientes, como key-one y key-two. Ambos secretos son cadenas únicas.

  • La clave de API se crea mediante el nombre y el servicio de IA generativa, y se establecen fechas de caducidad para sus dos secretos.
  • Cada secreto proporciona el mismo nivel de acceso y está vinculado a la misma clave de API. Puede utilizar cualquier secreto de forma intercambiable en las aplicaciones.
  • Cuando la aplicación llame a un punto final de modelo de OCI Generative AI, incluya cualquier secreto en la cabecera de autorización.
Importante

La clave de API debe estar en la misma región que el modelo con el que desea utilizarla.

Cómo utilizar la clave de API

Puede generar claves de API de OCI Generative AI y utilizarlas para acceder a puntos finales de modelos de lenguaje grandes alojados por el servicio de IA generativa mediante la API de REST o el SDK nativo de openai. A continuación, se muestran los pasos para utilizar las claves de API.

  1. En OCI Generative AI, cree una clave de API en una región soportada para el modelo que desea utilizar.
  2. En OCI IAM, agregue permisos de clave de API.
  3. Utilice esta clave cuando llame a un modelo soportado en una región soportada mediante las siguientes opciones:

Modelos soportados

Modelos para API de finalizaciones de chat
Modelos para API de respuestas
Importante

Llamadas externas a modelos de Grok xAI

Los modelos de xAI Grok se alojan en un centro de datos de OCI, en un arrendamiento aprovisionado para xAI. Los modelos de xAI Grok, a los que se puede acceder a través del servicio OCI Generative AI, están gestionados por xAI.

Uso de claves de API con API de REST

Puede utilizar las claves de API en las cabeceras de la API de REST y curl. Estos son los puntos finales que puede utilizar para la API de REST.

Puntos finales admitidos

Finalizaciones de chat
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/chat/completions
Respuestas
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/responses

Ejemplo con 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?"
    }
]
}'

Uso de claves de API con SDK de OpenAI

Puede utilizar las claves de API con el SDK OpenAI. Estos son los puntos finales que puede utilizar para el SDK de OpenAI.

Puntos finales admitidos

Especifique base_url como 
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1
Finalizaciones de chat
Utilice este método: client.chat.completions.create
Respuestas
Utilice este método: client.responses.create
Ejemplo
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)
Referencia
Repositorio GitHub de Oracle

Regiones soportadas

Regiones

Para los SDK de OpenAI, las regiones de OCI soportadas que se deben utilizar con claves de API están limitadas a:

  • Centro de Alemania (Fráncfort)
  • Sur de India (Hyderabad)
  • Centro de Japón (Osaka)
  • Este de EE. UU. (Ashburn)
  • Medio Oeste de EE. UU. (Chicago)
  • Oeste de EE. UU. (Phoenix)

Para confirmar las regiones utilizables de un modelo para el paquete OCI OpenAI, realice las siguientes tareas.

  1. Abra la tarjeta del modelo en la documentación de IA generativa:
  2. Observe las regiones que se muestran para ese modelo.
  3. Seleccione una región para el modelo que aparezca tanto en las regiones disponibles del modelo como en las seis regiones OCI OpenAI anteriores.
  4. Verifique si el modelo está disponible en el modo que necesita (bajo demanda o dedicado).

    Para acceder a modelos en modo dedicado, están soportados los puntos finales tanto públicos como privados.

Rotación o sustitución de una clave

Para rotar una clave de API de OCI Generative AI, puede cambiar su estado en la consola de OCI o mediante la operación SetApiKeyState con la API. Realice los siguientes pasos:

  1. Active el secreto en espera. Active el secreto no utilizado (por ejemplo, key-two) y actualice las aplicaciones para que lo utilicen.
  2. Verifique el failover. Confirme que las solicitudes se autentican con el secreto recién activado y que las cargas de trabajo continúan sin interrupción.
  3. Revocar o desactivar el primer secreto.
    • Si sospechas una fuga o es hora de retirar el primer secreto, revóvalo. Una vez que el cambio se propaga, las solicitudes que utilizan el secreto revocado se rechazan. Revocar un secreto lo desactiva permanentemente y la acción es irreversible.
    • Si planea reutilizar el primer secreto, desactívelo. Una vez que el cambio se propaga, las solicitudes que utilizan el secreto desactivado se rechazan hasta que se vuelve a activar.
    Consejo

    Desactivar un secreto para una suspensión o investigación a corto plazo. Revoca un secreto si se ha visto comprometido o si necesitas retirarlo permanentemente.

Para obtener más información sobre cómo realizar estas tareas, consulte Gestión de claves de API.

Importante

Copie los secretos nuevos o regenerados inmediatamente y almacénelos de forma segura. Sólo aparecen una vez.

Mejores prácticas

Almacene siempre los secretos clave de la API de OCI Generative AI en un gestor de secretos aprobado. Nunca los comprometa al control de origen ni los incruste en el código del lado del cliente.

  • Utilice la configuración de dos secretos para una rotación sin problemas y sin tiempo de inactividad, y defina los vencimientos para actualizar las claves con regularidad.
  • Limite el acceso a las claves mediante compartimentos y políticas de privilegios mínimos.
  • Supervise el uso, configure alertas y rote las claves inmediatamente si detecta actividad sospechosa.

Gestión de claves de API

Después de obtener el permiso de IAM para el recurso de claves de API de OCI Generative AI, puede gestionar claves de API mediante las siguientes operaciones:

Ejemplos en GitHub

Para obtener una experiencia práctica, consulte ejemplos en el repositorio de Oracle GitHub.