Autenticar com uma chave de API

O gateway CLEVI autentica as rotas compatíveis com OpenAI e as rotas compatíveis com Anthropic com uma única chave de API.
No cliente, é necessário configurar dois valores: o cabeçalho de autenticação que contém a chave e o base URL do SDK. O formato de cabeçalho permitido e o base URL diferem consoante a especificação.
Depois de concluir a configuração, pode confirmar imediatamente se a autenticação foi efetuada consultando a lista de modelos.
Se a autenticação falhar, é devolvido 401. Se a autenticação for bem-sucedida, mas as condições de autorização ou de limite não forem cumpridas, é devolvido 403.

Emita a chave de API no ecrã de chaves de API da consola. No mesmo ecrã, pode gerir a revogação da chave e o âmbito da sua utilização.

Cabeçalho de autenticação

Ambas as especificações colocam a chave de API num único cabeçalho do pedido. Utilize um dos cabeçalhos X-API-Key ou Authorization; o formato permitido depende da especificação.

Ao utilizar o cabeçalho Authorization numa rota compatível com OpenAI, é necessário o prefixo Bearer. Se enviar apenas a chave, sem o prefixo, o gateway rejeita o pedido.

Os nomes dos cabeçalhos não distinguem maiúsculas de minúsculas, pelo que o cabeçalho x-api-key enviado pelo SDK da Anthropic também funciona diretamente. Se especificar ambos os cabeçalhos, o valor de X-API-Key terá prioridade.

base URL

Os SDK que já utiliza continuam a funcionar se apenas alterar o base URL para o endereço abaixo. Os dois endereços diferem quanto à inclusão de /v1, por isso especifique diretamente o endereço correspondente à especificação.

Verificar a autenticação

Depois de configurar a chave e o URL base, pode verificar se a autenticação está a funcionar consultando a lista de modelos. Os exemplos abaixo executam a mesma consulta com curl, o OpenAI SDK e o Anthropic SDK. Substitua sk-... pela chave emitida no ecrã da chave da API.

Ao consultar com curl, especifique o caminho completo até /v1/models em ambos os formatos. O primeiro comando utiliza o cabeçalho X-API-Key no caminho compatível com OpenAI, e o segundo utiliza o cabeçalho Authorization no caminho compatível com Anthropic.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

No OpenAI SDK, especifique no base_url um endereço que inclua /v1.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

No Anthropic SDK, especifique no base_url um endereço que termine antes de /v1.
Para a autenticação, utilize diretamente o cabeçalho x-api-key enviado pelo SDK.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

Se a resposta de qualquer exemplo for 200, a autenticação foi bem-sucedida e data na resposta contém a lista de modelos que podem ser chamados com esta chave. Se for 401, verifique a causa pela ordem indicada na secção seguinte.

Falha de autenticação

Se enviar uma chave inexistente, expirada ou revogada, será devolvido 401. Se fizer uma chamada sem chave no caminho compatível com OpenAI, será devolvido o corpo abaixo; no caminho compatível com Anthropic, error.type será authentication_error.

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

Se receber 401, verifique pela ordem seguinte.

1. Verifique o estado da chave no ecrã da chave da API. Se a chave estiver expirada ou revogada, emita uma nova.
2. Verifique se o nome do cabeçalho é X-API-Key ou Authorization.
3. Se utilizar o cabeçalho Authorization no caminho compatível com OpenAI, verifique se inclui o prefixo Bearer.

Depois de corrigir, execute novamente a consulta da lista de modelos na secção de verificação da autenticação e confirme se recebe 200.

Cabeçalhos utilizados em conjunto

Todos os cabeçalhos seguintes são opcionais. Recomendamos especificar X-Request-Id para facilitar o rastreio de problemas.

Se os erros 5xx se repetirem, informe-nos através da ajuda e dos contactos, juntamente com o X-Request-Id. Se o valor tiver sido especificado diretamente, poderá compará-lo imediatamente com os registos do cliente.