Autenticazione

Creare una chiave

Le chiavi API vengono emesse da uno spazio di lavoro su console.artfical.com, nella pagina delle chiavi API. Crearne una lì è l'unico modo per ottenerne una; non esiste un modo per generare o ruotare una chiave tramite l'API stessa, ed è voluto: la creazione di una chiave è un'azione sensibile e poco frequente, e collocarla dietro la sessione autenticata della console la tiene fuori dalla portata di qualsiasi cosa abbia solo accesso a livello API.

Una chiave ha questo aspetto, sempre con lo stesso prefisso:

tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

Il valore completo della chiave viene mostrato esattamente una volta, nel momento in cui la crea. Successivamente, la console mostra solo una forma troncata a scopo identificativo (i primi caratteri e gli ultimi, con la parte centrale mascherata). Se perde il valore completo, non c'è modo di recuperarlo; l'unica opzione è revocare quella chiave e crearne una nuova. Tratti una chiave come tratterebbe la password di un database: la conservi in una variabile d'ambiente o in un gestore di secret, non nel codice sorgente, e mai in un'applicazione lato client dove il browser di un utente finale potrebbe leggerla.

Inviare la chiave in una richiesta

Ogni richiesta a /v1/chat/completions e /v1/models deve includere la chiave in un normale header Authorization, usando lo schema Bearer:

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

Questa è esattamente la stessa forma di header usata dall'API di OpenAI, ed è per questo che puntare un client già basato sull'SDK openai verso tAI è di solito una modifica di una sola riga: imposti base_url su https://api.artfical.com/v1 e api_key sulla propria chiave tAI, e il codice di richiesta dell'SDK stesso non deve cambiare.

# Python, usando il pacchetto ufficiale 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)

Una richiesta che omette del tutto l'header, o che lo invia nella forma sbagliata (senza il prefisso Bearer , con un valore vuoto, una chiave che non viene analizzata correttamente), viene rifiutata allo stesso modo di una chiave del tutto non valida: un 401 con un tipo authentication_error. Consulti Errori per la forma esatta della risposta.

Spazi di lavoro e ambito

Una chiave appartiene esattamente a uno spazio di lavoro e può essere usata solo per effettuare richieste per conto di quello spazio di lavoro. Non esiste il concetto di una chiave che copra più spazi di lavoro, né un modo per concedere a una singola chiave un accesso parziale solo ad alcuni modelli o a un certo livello di limite di frequenza; ogni chiave in uno spazio di lavoro ha lo stesso accesso a tutti i modelli elencati nella pagina Modelli. Se deve separare l'utilizzo o la fatturazione tra due progetti diversi, la risposta è avere due spazi di lavoro con le proprie chiavi, non una chiave condivisa tra loro.

L'utilizzo effettuato con una determinata chiave, il numero di richieste, il numero di token e il costo stimato, viene attribuito a quella chiave ed è visibile nella pagina Utilizzo della console, nell'ambito dello spazio di lavoro a cui la chiave appartiene. Questo serve puramente per la sua visibilità; non influisce sul modo in cui una richiesta viene elaborata.

Scadenza

Una chiave può facoltativamente essere creata con una data di scadenza (a 7, 30 o 90 giorni, oppure mai, scelta al momento della creazione della chiave). Una volta superata la data di scadenza, ogni richiesta effettuata con quella chiave viene rifiutata con lo stesso 401 authentication_error di una chiave non valida, indistinguibile dall'esterno. Se richieste che usano una chiave finora funzionante iniziano improvvisamente a fallire con 401, una chiave scaduta è la prima cosa da controllare, nella pagina delle chiavi API, prima di supporre che si sia rotto qualcos'altro.

Non esiste un rinnovo automatico. Una chiave in prossimità della scadenza deve essere sostituita con una appena creata; la console non estende sul posto la durata di una chiave esistente.

Revocare una chiave

Una chiave può essere revocata in qualsiasi momento dalla pagina delle chiavi API, immediatamente e in modo irreversibile. Una chiave revocata si comporta esattamente come una scaduta dal punto di vista dell'API: ogni richiesta successiva con essa riceve 401. La revoca è la risposta corretta a una chiave trapelata; non esiste un modo per ruotare sul posto il valore segreto di una chiave, solo per revocare quella vecchia e crearne una nuova che la sostituisca.

Cosa una chiave non concede da sola

Possedere una chiave API valida è sufficiente per effettuare richieste di completamento chat ed elencare i modelli. Non concede accesso a nulla nell'interfaccia della console stessa, alle impostazioni dello spazio di lavoro, alle informazioni di fatturazione o all'attività degli altri membri; quelle sono protette dal login basato su sessione della console stessa, del tutto separato dalle chiavi API. Una chiave API trapelata è un problema reale, poiché consente a qualcuno di effettuare richieste (e generare il relativo utilizzo) per conto del suo spazio di lavoro, ma non espone di per sé il suo account console né consente a qualcuno di accedere al suo posto.