Documentação do Oracle Cloud Infrastructure

Chaves de API

As chaves de API do OCI Generative AI são tokens de credenciais seguras usados para autenticar chamadores e autorizar o acesso a grandes modelos de linguagem hospedados pelo serviço OCI Generative AI.

Sobre a Chave de API

Uma chave de API do OCI Generative AI é um token secreto (uma string) específico do serviço OCI Generative AI. Você pode gerar uma chave de API e usá-la para acessar os grandes modelos de linguagem hospedados pelo serviço.

Essa chave de API é diferente de uma chave de API do IAM do OCI, que usa um par de chaves pública/privada para fornecer acesso geral à tenancy do OCI.

Como Funciona a Chave de API

Cada chave da API do OCI Generative AI inclui dois segredos separados, como key-one e key-two. Ambos os segredos são strings únicas.

  • Você cria a chave de API por meio do serviço Generative AI e define datas de expiração para seus dois segredos.
  • Cada segredo fornece o mesmo nível de acesso e está vinculado à mesma chave de API. Você pode usar qualquer segredo de forma intercambiável em aplicativos.
  • Quando seu aplicativo chamar um ponto final do modelo do OCI Generative AI, inclua um segredo no cabeçalho Autorização.
Importante

A chave de API deve estar na mesma região do modelo com o qual você deseja usá-la.

Como Usar a Chave de API

Você pode gerar chaves de API do OCI Generative AI e usá-las para acessar pontos finais de grandes modelos de linguagem hospedados pelo serviço Generative AI usando a API REST ou o SDK openai nativo. Estas são as etapas para utilizar as chaves de API.

  1. Na OCI Generative AI, Crie uma chave de API em uma região suportada para o modelo que você deseja usar.
  2. No OCI IAM, Adicionar Permissões de Chave de API.
  3. Use esta chave ao chamar um modelo suportado em uma região suportada por meio das seguintes opções:

Modelos Suportados

Modelos para API de Conclusões de Chat
Modelos para API de Respostas
Importante

Chamadas Externas para Modelos Grok xAI

Os modelos xAI Grok são hospedados em um data center da OCI, em uma tenancy provisionada para xAI. Os modelos xAI Grok, que podem ser acessados por meio do serviço OCI Generative AI, são gerenciados pelo xAI.

Usando Chaves de API com API REST

Você pode usar as chaves de API em cabeçalhos de API REST e curl. Estes são os pontos finais que você pode usar para a API REST.

Pontos Finais Suportados

Conclusões de Bate-papo
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/chat/completions
Respostas
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/responses

Exemplo usando 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?"
    }
]
}'

Usando Chaves de API com SDKs OpenAI

Você pode usar as chaves de API com o SDK OpenAI. Estes são os pontos finais que você pode usar para o SDK OpenAI.

Pontos Finais Suportados

Especifique o base_url como 
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1
Conclusões de Bate-papo
Utilizar este método: client.chat.completions.create
Respostas
Utilizar este método: client.responses.create
Exemplo
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)
Referência
Repositório GitHub da Oracle

Regiões Suportadas

Regiões

Para SDKs OpenAI, as regiões do OCI suportadas a serem usadas com chaves de API são limitadas a:

  • Centro da Alemanha (Frankfurt)
  • Sul da Índia (Hyderabad)
  • Centro do Japão (Osaka)
  • Leste dos EUA (Ashburn)
  • Centro-Oeste dos EUA (Chicago)
  • Oeste dos EUA (Phoenix)

Para confirmar as regiões utilizáveis de um modelo para o pacote OCI OpenAI, execute as tarefas a seguir.

  1. Abra o cartão do modelo na documentação do serviço Generative AI:
  2. Observe as regiões listadas para esse modelo.
  3. Selecione uma região para o modelo que aparece nas regiões disponíveis do modelo E nas seis regiões anteriores do OCI OpenAI.
  4. Verifique se o modelo está disponível no modo necessário (sob demanda ou dedicado).

    Para acesso a modelos no modo dedicado, há suporte para pontos finais públicos e privados.

Rotacionando ou Substituindo uma Chave

Para rotacionar uma chave de API do OCI Generative AI, você pode alterar seu estado na Console do OCI ou usando a operação SetApiKeyState com a API. São estas as etapas:

  1. Ative o segredo stand-by. Ative o segredo não utilizado (por exemplo, key-two) e atualize seus aplicativos para usá-lo.
  2. Verifique o failover. Confirme se as solicitações são autenticadas com o segredo recém-ativado e se as cargas de trabalho continuam sem interrupção.
  3. Revogue ou desative o primeiro segredo.
    • Se você suspeitar de um vazamento ou é hora de retirar o primeiro segredo, revogue-o. Após a propagação da alteração, as solicitações que usam o segredo revogado são rejeitadas. Revogar um segredo o desativa permanentemente, e a ação é irreversível.
    • Se você planeja reutilizar o primeiro segredo, desative-o. Após a propagação da alteração, as solicitações que usam o segredo desativado são rejeitadas até você reativá-lo.
    Dica

    Desativar um segredo para suspensão ou investigação de curto prazo. Revogue um segredo se ele tiver sido comprometido ou se você precisar aposentá-lo permanentemente.

Para obter etapas sobre como executar essas tarefas, consulte Gerenciando Chaves de API.

Importante

Copie segredos novos ou gerados novamente imediatamente e armazene-os com segurança. Eles aparecem apenas uma vez.

Práticas Recomendadas

Sempre armazene segredos-chave da API do OCI Generative AI em um gerente de segredos aprovado. Nunca os comprometa com o controle de origem ou os incorpore em código do lado do cliente.

  • Use a configuração de dois segundos para uma rotação suave e sem tempo de inatividade e defina expirações para atualizar regularmente as chaves.
  • Limite o acesso a chaves usando compartimentos e políticas de menor privilégio.
  • Monitore o uso, configure alertas e gire as chaves imediatamente se detectar atividades suspeitas.

Gerenciando Chaves de API

Após obter a permissão do IAM para o recurso de chave de API do OCI Generative AI, você pode gerenciar chaves de API usando as seguintes operações:

Exemplos de GitHub

Para obter uma experiência prática, consulte exemplos no repositório do Oracle GitHub.