Autenticação

Criar uma chave

As chaves de API são emitidas a partir de um workspace em console.artfical.com, na página de chaves de API. Criar uma chave ali é a única forma de a obter; não há forma de gerar ou rodar uma chave através da própria API, e isso é deliberado: a criação de chaves é uma ação sensível e pouco frequente, e colocá-la atrás da sessão autenticada da própria consola mantém-na fora do alcance de qualquer coisa que só tenha acesso ao nível da API.

Uma chave tem este aspeto, sempre com o mesmo prefixo:

tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

O valor completo da chave é mostrado exatamente uma vez, no momento em que a cria. Depois disso, a consola só mostra uma forma truncada para identificação (os primeiros caracteres e os últimos, com o meio ocultado). Se perder o valor completo, não há forma de o recuperar; a única opção é revogar essa chave e criar uma nova. Trate uma chave da mesma forma que trataria uma palavra-passe de base de dados: guarde-a numa variável de ambiente ou num gestor de segredos, nunca no código-fonte, e nunca numa aplicação do lado do cliente onde o browser de um utilizador final a possa ler.

Enviar a chave num pedido

Todos os pedidos a /v1/chat/completions e /v1/models devem incluir a chave num cabeçalho Authorization padrão, usando o esquema Bearer:

Authorization: Bearer tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

Este é exatamente o mesmo formato de cabeçalho que a própria API da OpenAI usa, razão pela qual apontar um cliente já baseado no SDK openai para a tAI costuma ser uma alteração de uma linha: defina base_url como https://api.artfical.com/v1 e api_key como a sua chave tAI, e o próprio código de pedidos do SDK não precisa de mudar.

# Python, usando o pacote oficial openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.artfical.com/v1",
    api_key="tai-sk-...",
)

response = client.chat.completions.create(
    model="tai-4.1",
    messages=[{"role": "user", "content": "Merhaba"}],
)
print(response.choices[0].message.content)

Um pedido em que falte totalmente o cabeçalho, ou que o envie no formato errado (sem o prefixo Bearer , um valor vazio, uma chave que não é possível interpretar), é rejeitado da mesma forma que uma chave diretamente inválida: um 401 com um tipo authentication_error. Consulte Erros para ver o formato exato da resposta.

Workspaces e âmbito

Uma chave pertence exatamente a um workspace e só pode ser usada para fazer pedidos em nome desse workspace. Não existe o conceito de uma chave que abranja vários workspaces, nem forma de conceder a uma única chave acesso parcial a apenas alguns modelos ou a um determinado nível de limite de taxa; todas as chaves de um workspace têm o mesmo acesso a todos os modelos listados na página Modelos. Se precisar de separar a utilização ou a faturação entre dois projetos diferentes, a resposta é dois workspaces com as suas próprias chaves, não uma chave partilhada entre eles.

A utilização feita com uma determinada chave, número de pedidos, número de tokens e custo estimado, é atribuída a essa chave e é visível na página de Utilização da consola, delimitada ao workspace a que a chave pertence. Isto serve apenas para visibilidade do seu lado; não afeta a forma como um pedido é processado.

Expiração

Uma chave pode, opcionalmente, ser criada com uma data de expiração (daqui a 7, 30 ou 90 dias, ou nunca, escolhido no momento da criação da chave). Assim que uma chave ultrapassa a sua data de expiração, todos os pedidos feitos com ela são rejeitados com o mesmo 401 authentication_error de uma chave inválida, indistinguível a partir do exterior. Se pedidos que usam uma chave que antes funcionava começarem subitamente a falhar com 401, uma chave expirada é a primeira coisa a verificar, na página de chaves de API, antes de assumir que outra coisa avariou.

Não existe renovação automática. Uma chave perto da sua data de expiração tem de ser substituída por uma recém-criada; a consola não prolonga a vida de uma chave existente no próprio lugar.

Revogar uma chave

Uma chave pode ser revogada a qualquer momento a partir da página de chaves de API, de forma imediata e irreversível. Uma chave revogada comporta-se exatamente como uma expirada do ponto de vista da API: todos os pedidos seguintes feitos com ela recebem 401. A revogação é a resposta certa para uma chave que tenha sido exposta; não há forma de rodar o valor secreto de uma chave no próprio lugar, apenas revogar a antiga e criar uma nova para a substituir.

O que uma chave não concede por si só

Ter uma chave de API válida é suficiente para fazer pedidos de conclusão de chat e listar modelos. Não concede acesso a nada na própria interface da consola, definições do workspace, informação de faturação, ou atividade de outros membros; isso é protegido pelo próprio início de sessão baseado em sessão da consola, inteiramente separado das chaves de API. Uma chave de API exposta é um problema real, uma vez que permite que alguém faça pedidos (e incorra na utilização associada) em nome do seu workspace, mas não expõe por si só a sua conta da consola nem permite que alguém inicie sessão como se fosse você.