Guida di riferimento API di tAI

L'endpoint

Tutto ciò che riguarda questa API passa attraverso un unico URL:

# URL di base
https://api.artfical.com/v1

Esiste un unico endpoint di completamento, POST /v1/chat/completions, e un unico endpoint di sola lettura per l'elenco, GET /v1/models. Questa è tutta la superficie disponibile. Non esiste un endpoint separato per ogni modello, né uno separato per lo streaming rispetto alla risposta non in streaming (lo stesso URL gestisce entrambi i casi, selezionati da un campo nel corpo della richiesta), né un endpoint separato per i turni di chiamata di strumenti. Se ha già sviluppato integrazioni con la Chat Completions API di OpenAI, con gli endpoint di inferenza di GitHub o con uno dei tanti provider che offrono una forma compatibile con OpenAI, questo le risulterà già familiare. Questa somiglianza è voluta: puntare un client compatibile con OpenAI già esistente (il pacchetto ufficiale openai per Python o Node, LangChain, LlamaIndex, un agente di coding come OpenCode, o un proprio wrapper leggero) verso https://api.artfical.com/v1 con una chiave API di tAI dovrebbe funzionare con poche o nessuna modifica al codice.

La via più rapida verso la prima richiesta

Servono tre cose: uno spazio di lavoro su console.artfical.com, una chiave API creata dalla pagina delle chiavi API di quello spazio di lavoro, e un qualsiasi client HTTP. Ecco la versione più breve, usando curl:

# Sostituisca tai-sk-... con la propria chiave
curl https://api.artfical.com/v1/chat/completions \
  -H "Authorization: Bearer tai-sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tai-4.1",
    "messages": [{"role": "user", "content": "Merhaba, kendini tanıt."}]
  }'

Quell'unica richiesta è un'integrazione completa e funzionante. Tutto il resto di questa sezione, streaming, chiamata di strumenti, input di immagini, controlli di campionamento, è un livello opzionale sopra questa stessa struttura, non un'API diversa da imparare. La pagina Chat completions illustra in dettaglio l'intera richiesta e risposta; la pagina Autenticazione spiega come la chiave stessa viene rilasciata, delimitata nei permessi e ruotata.

Come è organizzata questa sezione

Le pagine qui presenti sono raggruppate secondo l'ordine in cui la maggior parte delle persone ne ha effettivamente bisogno, non secondo l'ordine in cui l'implementazione sottostante si trova organizzata. Il primo gruppo, per iniziare, è la parte di cui chiunque ha bisogno indipendentemente da cosa sta costruendo: come autenticarsi, la struttura di una richiesta e di una risposta, in cosa lo streaming differisce da un'unica risposta bloccante, e come scoprire quali modelli esistono, quanto costano e cosa supportano. Il secondo gruppo, opzioni della richiesta, copre tutto ciò che è facoltativo rispetto a una richiesta di base: le leve di campionamento che modellano il modo in cui viene generata una risposta, come fornire al modello strumenti che può chiedere di chiamare, e come inviare un'immagine insieme al testo. Il terzo gruppo, riferimento, è pensato per essere consultato piuttosto che letto dall'inizio alla fine: la struttura esatta di una risposta di errore e cosa significa ciascun tipo, come funziona la limitazione di frequenza e quali header la riflettono, la tabella dei prezzi per modello, e una pagina pensata specificamente per chi sta migrando un'integrazione esistente basata sull'SDK OpenAI, con il dettaglio di cosa è supportato così com'è e cosa no.

A chi si rivolge

Questa sezione è scritta per chi scrive codice direttamente contro l'API, che si tratti di un servizio backend, di uno script o di un framework per agenti come OpenCode che tratta tAI come uno dei tanti provider intercambiabili compatibili con OpenAI. Presuppone familiarità con l'invio di richieste HTTP e la lettura di JSON, ma non una conoscenza pregressa specifica di tAI. Se invece sta cercando come usare tAI attraverso il prodotto di chat stesso, questo è trattato nella documentazione principale di tAI, non in questa sezione. Se sta cercando come viene valutata la sicurezza di tAI e quali misure di protezione sono integrate nel prodotto, quella è la sezione Sicurezza. Questa sezione è dedicata specificamente all'API HTTP rivolta agli sviluppatori: cosa invia, cosa ottiene indietro, e cosa significa ogni campo e header.

Una nota sulla stabilità

Le strutture di richiesta e risposta documentate in questa sezione sono quelle che intendiamo mantenere stabili. L'aggiunta di un campo è qualcosa da aspettarsi nel tempo man mano che l'API cresce; un campo documentato che cambia significato o scompare senza un sostituto non è qualcosa che facciamo con leggerezza. Dove qualcosa è genuinamente provvisorio o probabile che cambi, la pagina interessata lo dichiara esplicitamente invece di lasciarglielo scoprire nel modo peggiore. Se un campo o un comportamento non è menzionato da nessuna parte in questa sezione, lo consideri non parte del contratto supportato, anche se dovesse osservarlo in una risposta, perché potrebbe cambiare o scomparire senza preavviso.