API Character AI: Cambia client in tre righe

Prerequisiti

Prima di scrivere codice, hai bisogno di un account attivo su characteraiapi.com. Visita la pagina Ottieni chiave API e registrati con solo email e password. Non è richiesta una carta di credito per iniziare e i nuovi account ricevono $0,50 di credito di prova valido per 7 giorni. Una volta registrato, la tua chiave API viene visualizzata immediatamente. Conserva questa chiave in modo sicuro, poiché autentica tutte le richieste all'endpoint. Avrai anche bisogno di un SDK per il linguaggio supportato installato nel tuo ambiente di sviluppo. L'endpoint character ai api accetta parametri standard OpenAI, quindi qualsiasi client compatibile con OpenAI può funzionare con modifiche minime.

Installa l'SDK

Per i progetti Python, installa il pacchetto ufficiale OpenAI usando pip. Questa libreria gestisce automaticamente la serializzazione JSON e le richieste HTTP. Per le applicazioni Node.js, usa npm per aggiungere il pacchetto openai. Entrambe le librerie supportano le funzionalità di streaming e chiamata di strumenti descritte più avanti in questa guida. Assicurati che la versione dell'SDK sia recente abbastanza da supportare gli eventi inviati dal server (SSE) per lo streaming dei token in tempo reale. Se usi un client HTTP personalizzato invece di un SDK, devi gestire manualmente il payload JSON e l'analisi dello stream SSE secondo la specifica dell'API OpenAI.

Autenticazione

Ogni richiesta all'API deve includere la tua chiave API nell'intestazione Authorization. Usa il formato Bearer YOUR_API_KEY. L'URL di base per tutte le richieste è https://api.characteraiapi.com/v1. Quando usi un SDK, imposta la configurazione base_url su questo valore e fornisci la tua chiave tramite il parametro api_key. Se perdi la chiave o sospetti una perdita, puoi rigenerarla dal dashboard; la vecchia chiave verrà revocata immediatamente. È consentita solo una chiave attiva per account. Assicurati di utilizzare l'URL di base corretto, poiché le richieste all'endpoint standard OpenAI falliranno con un errore 404 o 401.

Completamento chat di base

La funzionalità principale è servita tramite l'endpoint /v1/chat/completions. Invia una richiesta POST con il nome del modello uncensored e la cronologia dei messaggi. Il modello risponde con un output testuale senza applicare i filtri standard sui contenuti per i contenuti adulti leciti. Di seguito è riportato un esempio curl che dimostra una semplice richiesta di completamento del testo.

Copycurl https://api.characteraiapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'

Questa richiesta restituisce un oggetto di completamento contenente il testo generato. Puoi regolare parametri come temperature per controllare la casualità o max_tokens per limitare la lunghezza dell'output. Il modello supporta una finestra di contesto di 100.000 token, consentendo di elaborare una cronologia di conversazioni sostanziale o documenti lunghi in una singola richiesta.

Risposte in streaming

Per una migliore esperienza utente, abilita lo streaming impostando stream: true nella tua richiesta. L'API restituisce eventi inviati dal server (SSE) contenenti chunk di token parziali man mano che vengono generati. Questo riduce la latenza percepita per le applicazioni chatbot. Usa il parametro stream_options se vuoi ricevere le statistiche di utilizzo finali nell'ultimo evento. Lo streaming è particolarmente utile per il roleplay di personaggi in tempo reale, dove la visualizzazione del testo parola per parola migliora l'immersione. Assicurati che il codice del client gestisca correttamente il formato SSE per analizzare ogni chunk in sequenza.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Limiti di richiesta ed errori

L'API impone un limite di 300 richieste al minuto per chiave. Se superi questo limite, riceverai un errore 429 Too Many Requests. I corpi delle richieste sono limitati a 8 MB. Gli errori comuni includono 401 per una chiave non valida o mancante, e 402 se il tuo credito prepagato è esaurito. Puoi ricaricare a partire da $10 utilizzando criptovalute (USDT o USDC), con crediti bonus disponibili per depositi più grandi. A differenza di alcuni provider, non ci sono commissioni nascoste o blocchi di abbonamento; paghi solo per i token che consumi. I prezzi sono trasparenti: $0,25 per 1M di token di input e $1,00 per 1M di token di output. Assicurati che la logica di gestione degli errori riprovi in caso di 429 con un backoff esponenziale.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.characteraiapi.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Node.js

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.characteraiapi.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);