kimiapikey.comGuida
Integrazione della chiave API Kimi con SDK OpenAI e LangChain
Integrare questa API in un'app significa modificare due valori nel codice che probabilmente hai già: la base URL e la chiave. Questa guida mostra la modifica per gli SDK OpenAI, LangChain e LiteLLM, poi copre i retry e i limiti per l'uso in produzione.
Aggiornato

Punti chiave
- Ogni client ha bisogno degli stessi tre valori: base URL https://api.kimiapikey.com/v1, la tua chiave e il modello
uncensored. - Memorizzali nelle variabili d'ambiente così puoi cambiare provider senza modificare il codice.
- Gestisci le risposte 429 separatamente: rate_limited, concurrency e un sovraccarico temporaneo con Retry-After: 5.
- Una chiave completa permette 8 richieste concorrenti e 300 al minuto; una chiave di prova ne permette 2 e 60.
Cosa cambia effettivamente nel tuo codice
Una integrazione della chiave API Kimi sembra un progetto, ma per questo endpoint è una modifica di configurazione. Il servizio implementa il formato delle chat completions di OpenAI, quindi qualsiasi libreria client che ti permetta di impostare una base URL e una chiave funzionerà. Non c'è un SDK personalizzato da installare e nessuna nuova forma di richiesta da imparare.
| Impostazione | Valore |
|---|---|
| Base URL | https://api.kimiapikey.com/v1 |
| Autenticazione | La chiave dal tuo dashboard, inviata come Authorization: Bearer |
| Modello | uncensored |
| Endpoint | POST /v1/chat/completions, GET /v1/models |
Due punti fanno risparmiare tempo. Primo, questo è un modello testuale dietro un endpoint: nessun percorso embedding, nessuna generazione di immagini, nessun audio. Se la tua app chiama questi servizi, mantieni un altro provider per loro e instrada solo la chat qui. Secondo, questa non è l'API ufficiale di Kimi o di qualsiasi altro fornitore; è un provider indipendente che esegue un modello a pesi aperti, quindi i nomi dei modelli di altre piattaforme non verranno risolti. La guida alla chiave API Kimi spiega questa differenza più approfonditamente.
Ottieni la tua chiave nella pagina delle chiavi API. I nuovi account possono richiedere $0,50 di credito di prova lì, che è più che sufficiente per tutto quanto segue.
Configurazione e migrazione di un'app esistente
Le librerie ufficiali OpenAI Python e Node leggono OPENAI_API_KEY e OPENAI_BASE_URL dall'ambiente quando non le passi esplicitamente. Questo rende l'integrazione a minor sforzo un cambiamento shell:
export OPENAI_BASE_URL="https://api.kimiapikey.com/v1"
export OPENAI_API_KEY="YOUR_KEY"
Il codice esistente che crea un client OpenAI() ora parla a questo endpoint. Devi comunque modificare l'argomento model in uncensored. Inserisci anche il nome del modello in una variabile, ad esempio LLM_MODEL, così un ambiente di test e uno di produzione possono differire senza modificare il codice.
L'abitudine vale il minuto che richiede. Quando la base URL, la chiave e il modello sono nella configurazione, provare un altro provider compatibile con OpenAI è una modifica di deployment, e il rollback è la stessa modifica al contrario.
La maggior parte dei team non parte da un file vuoto. Hanno un'app che chiama già un'API in stile OpenAI e vogliono che chiami questa. La migrazione è principalmente una ricerca di tre stringhe.
- Trova dove viene creato il client e modifica la base URL.
- Trova ogni argomento
model=e sostituisci il vecchio nome conuncensored. - Cerca le funzionalità che il tuo codice usa ma che questa API non fornisce, come embedding, generazione di immagini o audio. Quelle chiamate devono rimanere con un altro provider o essere rimosse.
Poi confronta il comportamento, non solo la sintassi. Un modello diverso ha una voce diversa, una lunghezza predefinita diversa e abitudini diverse con la formattazione. Esegui i tuoi prompt di test esistenti, leggi le risposte fianco a fianco e regola il prompt di sistema dove il tono è cambiato. Il testo del prompt che funzionava con le stranezze di un altro modello a volte non fa nulla qui, e a volte peggiora le cose, quindi rimuovi i workaround vecchi uno alla volta e osserva cosa cambia.
Controlla anche i parametri che passi. Temperature, top_p, stop, seed e le penalità vengono passati attraverso, quindi si comportano come ti aspetti. I campi che appartengono ad altri vendor o a funzionalità che questa API non ha non faranno nulla di utile. Mantieni il corpo della richiesta piccolo e standard. Il limite del corpo è 8 MB, il che conta solo se incorpori documenti grandi direttamente.
Python: sincrono, streaming e asincrono
La forma esplicita, che non dipende dalle variabili d'ambiente:
from openai import OpenAI
client = OpenAI(
base_url="https://api.kimiapikey.com/v1",
api_key="YOUR_KEY",
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You answer in plain English."},
{"role": "user", "content": "Explain idempotency in two sentences."},
],
temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)
Per lo streaming, imposta stream=True e leggi i chunk mentre arrivano. Lo streaming viene consegnato tramite server-sent events, e l'utilizzo viene riportato alla fine.
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a limerick about retries."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Per un servizio che gestisce molti utenti, usa il client asincrono e limita la tua concorrenza così da non superare mai il limite di concorrenza della chiave. Un semaphore è il modo più semplice:
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="https://api.kimiapikey.com/v1",
api_key="YOUR_KEY",
)
gate = asyncio.Semaphore(8)
async def ask(prompt: str) -> str:
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
)
return r.choices[0].message.content
async def main():
prompts = [f"Give one fact about the number {n}." for n in range(20)]
answers = await asyncio.gather(*(ask(p) for p in prompts))
print(len(answers), "answers")
asyncio.run(main())
Imposta il semaphore a 2 mentre sei sulla chiave di prova, e a 8 su una chiave finanziata.
Node e TypeScript
La libreria Node prende le stesse due opzioni con nomi leggermente diversi:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.kimiapikey.com/v1",
apiKey: process.env.API_KEY,
});
const completion = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three HTTP status codes." }],
});
console.log(completion.choices[0].message.content);
Lo streaming con lo stesso client usa stream: true e un iteratore asincrono sul risultato. Se usi un framework front-end che avvolge la libreria OpenAI, come un toolkit UI chat, cerca la sua opzione base URL e impostala allo stesso modo. Tieni la chiave sul server. Una chiave inserita nel codice del browser può essere copiata da chiunque apra gli strumenti di sviluppo, e il credito dietro di essa è denaro reale.
LangChain e LiteLLM
I framework che avvolgono il client OpenAI di solito espongono gli stessi due parametri. In LangChain per Python, la classe del modello di chat OpenAI li accetta direttamente:
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.kimiapikey.com/v1",
api_key="YOUR_KEY",
temperature=0.5,
)
reply = llm.invoke("Summarize what a message queue does in one sentence.")
print(reply.content)
Da lì, catene, template di prompt e parser di output funzionano come fanno con qualsiasi modello di chat. Se associ strumenti, l'API supporta la chiamata di funzioni con tools e tool_choice, e i risultati degli strumenti tornano al modello come messaggi role: "tool", che è ciò che il framework produce.
LiteLLM è utile quando vuoi una convenzione di chiamata unica su più provider. Antepponi al modello openai/ e passa la base URL come api_base:
import litellm
resp = litellm.completion(
model="openai/uncensored",
api_base="https://api.kimiapikey.com/v1",
api_key="YOUR_KEY",
messages=[{"role": "user", "content": "Say hello in French."}],
)
print(resp.choices[0].message.content)
Per dati strutturati, passa response_format={"type": "json_object"} e dì nel prompt che vuoi JSON. Analizza sempre il risultato in modo difensivo, perché la modalità JSON richiede JSON valido ma il tuo schema è ancora solo una richiesta nel prompt.
Limiti, retry e gestione degli errori
Una chiave finanziata permette 8 richieste concorrenti e 300 richieste al minuto. Una chiave di prova ne permette 2 e 60. Il corpo può essere fino a 8 MB, e la finestra è di 100.000 token per prompt e completamento insieme. Quando superi un limite, l'API risponde con HTTP 429 e uno di questi:
rate_limited: troppe richieste al minuto. Riduci la frequenza per alcuni secondi.concurrency: troppe richieste in esecuzione contemporaneamente. Attendi che una finisca. Una richiesta in streaming mantiene il suo slot fino alla fine dello streaming, quindi un consumatore lento conta contro di te.- Un 429 con
Retry-After: 5: sovraccarico temporaneo. Attendi cinque secondi e riprova.
Un piccolo wrapper di retry che onora l'intestazione gestisce tutti e tre:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.kimiapikey.com/v1", api_key="YOUR_KEY", max_retries=0)
def chat(messages, tries=4):
for attempt in range(tries):
try:
return client.chat.completions.create(model="uncensored", messages=messages)
except RateLimitError as e:
wait = int(e.response.headers.get("retry-after", 2 ** attempt))
time.sleep(wait)
raise RuntimeError("still rate limited after retries")
Le richieste fallite o rifiutate non vengono addebitate, quindi i retry non comportano penalità di fatturazione. Registra l'intestazione di risposta X-Request-Id con ogni chiamata; è il modo più veloce per puntare a una richiesta se qualcosa sembra sbagliato. X-Balance-USD ti dice quanto credito rimane, che puoi alimentare a un alert. La documentazione elenca tutte le intestazioni di risposta.
Chiamata di funzioni attraverso un framework
I framework agent dipendono dalla chiamata di funzioni, quindi vale la pena fare un breve test prima di costruire su di essa. Questa API accetta tools e tool_choice, restituisce tool_calls quando il modello vuole eseguire una funzione, e si aspetta il risultato come messaggio role: "tool" che fa riferimento all'ID della chiamata. Lo streaming funziona con gli strumenti, con la chiamata che arriva in frammenti che l'SDK assembla per te.
Un buon primo test è un agente con un solo strumento, con una funzione il cui risultato puoi verificare a occhio, come una calcolatrice o una ricerca in un piccolo dizionario. Esegui il test dieci volte. Se il modello seleziona lo strumento e compila correttamente i suoi argomenti ogni volta, puoi aggiungere un secondo strumento. Se a volte risponde attingendo dalla memoria invece di chiamare la funzione, rendi la descrizione dello strumento più specifica, oppure imposta tool_choice per forzare la chiamata per quel passaggio. I modelli differiscono nell'affidabilità con cui gestiscono lunghe catene di chiamate, quindi mantieni le catene brevi e aggiungi un limite di passaggi a qualsiasi ciclo di esecuzione in modo che un'esecuzione confusa non vada in loop all'infinito e consumi credito.
Una breve checklist pre-lancio
- Esegui una richiesta tramite curl o l'SDK e conferma che il blocco di utilizzo sia presente.
- Testa lo streaming con il client che verrà usato in produzione, incluso cosa succede quando l'utente chiude la pagina a metà streaming.
- Limita la tua concorrenza al di sotto del limite della chiave.
- Imposta
max_tokensdove ci si aspettano risposte brevi, e taglia la cronologia della chat prima che cresca oltre ciò che vuoi pagare. - Tieni la chiave nella configurazione lato server e ruotala se appare in un log.
- Verifica i costi sul traffico reale. A $0,15 per 1M di input e $0,50 per 1M di output, una richiesta con 3.000 token in input e 700 in output costa $0,0008, quindi 10.000 di esse costano circa $8. I dettagli sono nella pagina prezzi.
I prompt inviati all'API non vengono usati per l'addestramento. L'unica regola sui contenuti che non cambia mai è il limite rigido sui contenuti sessuali che coinvolgono i minorenni; il modello è altrimenti sintonizzato per rispondere senza rifiuti per l'uso adulto legale, quindi le app che servono il pubblico dovrebbero comunque aggiungere la propria moderazione e controlli dell'età dove la legge o i tuoi utenti se li aspettano.
Altre guide
- Usa una chiave API stile Kimi in Cursor: Guida alla configurazione
- Prezzi delle chiavi API Kimi: quanto costa questa alternativa
- Chiave API Kimi: come funziona e quali sono le alternative
Domande frequenti
Il modello è lo stesso del Kimi ufficiale di Moonshot?
No, ospitiamo un modello a pesi aperti ottimizzato per essere senza censura. Non è GPT, Claude, Gemini, Grok, DeepSeek o il modello di nessun altro fornitore. È un modello distinto eseguito sui nostri server.
Addestrate i modelli sui miei dati?
No. I tuoi prompt e le tue risposte non vengono utilizzati per l'addestramento. Valutiamo la privacy e la trasparenza, quindi i tuoi dati restano tuoi.
Quali sono i limiti di richieste?
Hai un limite di 300 richieste al minuto per chiave. La dimensione massima del corpo della richiesta è di 8 MB. Questi limiti sono progettati per garantire prestazioni stabili per tutti gli utenti.
Qual è la policy sui contenuti?
Il modello è senza censura per argomenti per adulti, controversi e creativi. Tuttavia, blocciamo i contenuti sessuali che coinvolgono minori. Questo è un limite rigido che si applica sempre, indipendentemente dal tuo livello di abbonamento.
Domande e risposte
Ho bisogno di un SDK speciale?
No. Le librerie standard OpenAI per Python e Node funzionano dopo aver impostato la base URL su https://api.kimiapikey.com/v1 e aver usato la tua chiave. LangChain e LiteLLM funzionano allo stesso modo.
Quale nome di modello dovrebbe usare il mio codice?
Usa uncensored. È l’unico model ID servito dall’API e GET /v1/models lo elenca.
Come evito gli errori 429?
Limita le tue richieste parallele a 8 su una chiave finanziata o a 2 su una chiave di prova, e riprova dopo il ritardo indicato dall'intestazione Retry-After quando l'API lo richiede.
Supporta la chiamata di funzioni e la modalità JSON?
Sì. Usa tools e tool_choice per le chiamate di funzioni, e response_format con type json_object per l’output JSON. Funziona anche lo streaming.
Posso usare embedding o generazione di immagini con la stessa chiave?
No. L’API è solo per chat testuale, senza endpoint per embedding, immagini, audio o video.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica la base URL. È tutta la configurazione.