URL API Kimi Code: configurazione del Base URL per client OpenAI

L'URL e il significato di ogni parte

Se stai cercando l'URL dell'API Kimi Code, potresti cercare l'indirizzo del servizio di Kimi. Per quello, usa la documentazione del fornitore, poiché non posso garantirlo. Questo sito offre qualcos'altro: un'API ospitata compatibile con OpenAI davanti a un modello a pesi aperti, gestita da un provider indipendente. Il suo indirizzo è:

Copyhttps://api.kimicode.cc/v1

Quella stringa è il base URL. È la parte condivisa da ogni richiesta. L'SDK aggiunge il resto. Quando chiami chat.completions.create, la libreria OpenAI invia un POST a https://api.kimicode.cc/v1/chat/completions. L'elenco dei modelli si trova su https://api.kimicode.cc/v1/models e richiede un GET.

Questi sono gli unici metodi serviti da questa API: POST /v1/chat/completions e GET /v1/models. Se speravi in endpoint per immagini, audio o embedding, non esistono qui. È un'API testuale.

Tre impostazioni sono importanti, e nient'altro deve cambiare nel tuo codice OpenAI esistente: il Base URL, la chiave API e l'ID del modello uncensored.

Perché il Base URL è l'unico interruttore

I client in stile OpenAI sono costruiti attorno a un'idea: il formato della richiesta è fisso e l'host è un'impostazione. La libreria ha un host predefinito che punta al fornitore originale. Quando lo sostituisci con un altro Base URL, lo stesso corpo della richiesta va da un'altra parte. Non devi cambiare nulla nei tuoi prompt, negli array di messaggi o nell'analisi delle risposte.

Per questo, migrare da un provider compatibile OpenAI richiede tre modifiche: Base URL, chiave e nome del modello. I campi della risposta, come choices, message, finish_reason e usage, hanno gli stessi nomi, quindi il codice che li legge continua a funzionare.

Spiega anche gli errori strani che si verificano. Se uno strumento richiede un "URL del server" e incolli solo l'host, manca il percorso. Se richiede un "endpoint completo" e incolli la base, la richiesta va nel posto sbagliato. Quando una schermata di configurazione è poco chiara, prova prima l'URL di base e leggi il codice di stato restituito. La guida rapida nella documentazione illustra la stessa migrazione con un esempio in più.

Variabili d'ambiente per gli strumenti che non puoi modificare

Molti strumenti da riga di comando e framework creano un client OpenAI senza toccare il costruttore. Di solito leggono le variabili d'ambiente standard, quindi impostarle è sufficiente:

Copyexport OPENAI_BASE_URL="https://api.kimicode.cc/v1"
export OPENAI_API_KEY="YOUR_KEY"

Alcuni strumenti più vecchi cercano OPENAI_API_BASE, quindi se uno ignora il primo nome, prova il secondo. Dopo averli impostati, avvia lo strumento nella stessa sessione shell, poiché le variabili impostate in un'altra finestra del terminale non sono condivise.

Lo strumento avrà comunque bisogno di un nome del modello. Se hard-coda un modello ospitato, cerca un flag o una riga di configurazione che lo imposti e usa uncensored. Se non può essere modificato, lo strumento non è adatto e uno script piccolo come quelli sopra è una soluzione migliore.

Ottieni prima una chiave

Le richieste sono autenticate con un'intestazione Authorization: Bearer YOUR_KEY. Ogni SDK ufficiale crea questa intestazione per te dall'argomento api_key. Puoi creare la chiave dopo aver effettuato l'accesso con Google o con email e password.

I nuovi account possono richiedere $0,50 di credito di prova con un clic sulla pagina della chiave API. Non serve una carta e dura 7 giorni. È sufficiente per eseguire ogni esempio qui sotto molte volte. Le chiavi di prova permettono 2 richieste parallele e 60 richieste al minuto, quindi esegui gli esempi uno alla volta.

Memorizza la chiave in una variabile d'ambiente invece che nei file di origine. Una chiave committata in un repository pubblico verrà trovata e usata da qualcun altro entro poche ore, e il credito che contiene è tuo.

Prima richiesta in curl

Curl è il modo più veloce per dimostrare che l'URL funziona, perché rimuove ogni libreria dall'equazione. Se questa chiamata ha successo, qualsiasi problema che incontri in seguito è nella configurazione del tuo client.

Copyexport KIMICODE_KEY="YOUR_KEY"

curl https://api.kimicode.cc/v1/models   -H "Authorization: Bearer $KIMICODE_KEY"

curl https://api.kimicode.cc/v1/chat/completions   -H "Authorization: Bearer $KIMICODE_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "messages": [
      {"role": "user", "content": "Say hello in five words."}
    ]
  }'

La prima chiamata restituisce l'elenco dei modelli, che dovrebbe includere uncensored. La seconda restituisce un oggetto di completamento chat standard. Guarda le intestazioni di risposta con curl -i e vedrai X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency. Tieni l'ID richiesta se contatti supporto per una chiamata specifica.

Python con l'SDK OpenAI

Installa la libreria con pip install openai, quindi modifica due argomenti nel costruttore del client.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kimicode.cc/v1",
    api_key=os.environ["KIMICODE_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what a base URL is in two sentences."},
    ],
    temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage)

Parametri come temperature, top_p, stop, seed e le penalità di frequenza e presenza vengono passati al modello. Il valore max_tokens è opzionale. Senza di esso il completamento può usare tutto ciò che resta della finestra da 100.000 token, che è il prompt e il completamento combinati.

L'SDK legge anche due variabili d'ambiente se non passi argomenti: OPENAI_BASE_URL e OPENAI_API_KEY. È utile per gli strumenti che non puoi modificare. Imposta entrambi, avvia lo strumento e parlerà con questa API.

Node, streaming e modalità JSON

La configurazione Node è speculare a Python. Installa con npm install openai.

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kimicode.cc/v1",
  apiKey: process.env.KIMICODE_KEY,
});

// Streaming over SSE
const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Write a four-line poem about routers." }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

// JSON mode
const json = await client.chat.completions.create({
  model: "uncensored",
  response_format: { type: "json_object" },
  messages: [
    { role: "system", content: "Reply with a JSON object only." },
    { role: "user", content: "Give me keys name and port for a local dev server." },
  ],
});
console.log(JSON.parse(json.choices[0].message.content));

Lo streaming usa eventi inviati dal server e l'utilizzo viene segnalato alla fine dello stream. Una richiesta in streaming mantiene la sua slot di concorrenza fino al termine dello stream, quindi un client che apre uno stream e non lo legge bloccherà una slot. Con la modalità JSON, dì comunque al modello nel prompt di rispondere in JSON. Il flag vincola il formato di output, ma un'istruzione chiara ti dà nomi di campo migliori.

Chiamate di funzioni

I tool usano la forma OpenAI usuale: un elenco tools, un tool_choice opzionale e i risultati dei tool inviati indietro come messaggi con role: "tool". Durante lo streaming, i tool_calls arrivano a pezzi attraverso i blocchi.

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.kimicode.cc/v1", api_key=os.environ["KIMICODE_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "get_port",
        "description": "Look up the port of a named local service",
        "parameters": {
            "type": "object",
            "properties": {"service": {"type": "string"}},
            "required": ["service"],
        },
    },
}]

messages = [{"role": "user", "content": "Which port does the api service use?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]

messages.append(first.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": json.dumps({"service": "api", "port": 8080}),
})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)

Tratta gli argomenti dal modello come input non attendibile. Validali prima di eseguire qualsiasi cosa. Il modello può saltare una chiamata o chiamarla con un campo errato, come qualsiasi modello può fare, quindi mantieni un percorso di riserva nel tuo ciclo.

Quando l'URL fallisce

La maggior parte dei guasti rientra in un breve elenco.

• 404 Not Found. Il percorso è errato. Cause comuni: la base URL è impostata su https://api.kimicode.cc senza /v1, o su https://api.kimicode.cc/v1/chat/completions così il client aggiunge il percorso due volte. Usa esattamente la base URL sopra.
• 401 Unauthorized. La chiave manca, ha spazi o newline estranei, o l'intestazione non è un token Bearer. Stampa la lunghezza della variabile per verificare.
• 429 con codice rate_limited. Hai superato il limite per minuto: 300 richieste per una chiave completa, 60 per una chiave di prova.
• 429 con codice concurrency. Troppe richieste simultanee: 8 per una chiave completa, 2 per una chiave di prova.
• 429 con intestazione Retry-After: 5. Sovraccarico temporaneo. Attendi cinque secondi e riprova.
• Richiesta troppo grande. Il limite del corpo è 8 MB e il prompt più il completamento devono rientrare in 100.000 token.

Un ciclo di ritentativi che onora Retry-After e aumenta il backoff per gli altri due codici gestisce quasi tutto. Il costo per chiamata è piccolo; la pagina dei prezzi ha i prezzi per token, e la guida rapida della documentazione mostra i passaggi di migrazione da un altro provider in stile OpenAI.

Ritentativi e abitudini in produzione

Una volta che la prima chiamata funziona, aggiungi un wrapper di ritentativi prima di rilasciare. Onora l'intestazione Retry-After quando è presente e riduci il backoff con un breve ritardo casuale altrimenti.

Copyimport os, time, random
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.kimicode.cc/v1", api_key=os.environ["KIMICODE_KEY"])

def ask(messages, tries=5):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except RateLimitError as err:
            retry_after = 5
            if getattr(err, "response", None) is not None:
                retry_after = int(err.response.headers.get("retry-after", 5))
            time.sleep(retry_after + random.random())
    raise RuntimeError("still rate limited after retries")

Limita la tua concorrenza in base alla tua chiave: un pool di thread da 8 per una chiave completa, 2 per una chiave di prova. Questo evita l'errore concurrency prima che inizi, e ti mantiene entro il limite di 300 richieste al minuto anche quando ogni chiamata richiede più di qualche secondo.

Infine, ricorda che paghi per token. Registra l'oggetto usage per ogni chiamata e osserva l'intestazione X-Balance-USD. A $0,15 per 1M token di input e $0,50 per 1M token di output, un turno di chat tipico è una frazione di centesimo, ma i loop e le cronologie lunghe si accumulano, e il log ti dice dove.

Altre guide

• Prezzi API Kimi Code vs Token a consumo
• Kimicode in Cursor Alternative: Configurazione endpoint personalizzato
• API Groq: Miti vs Fatti per LLM senza censura