Wat betekent OpenAI-compatible voor een API?

Het korte antwoord

Wanneer een provider zegt dat zijn API openai-compatible is, betekent dit dat hij dezelfde HTTP-verzoeken accepteert die de OpenAI-clientbibliotheken sturen en antwoorden retourneert in dezelfde vorm. Je houdt je code, wijzigt de basis-URL en de sleutel, en de aanroep gaat naar een andere server.

Dat is de hele belofte. Het is een uitspraak over de interface, alsof je zegt dat twee opladers dezelfde stekker gebruiken. Het vertelt je niet wat er aan het andere eind van de kabel zit. Het model, de veiligheidsregels, de prijs en de limieten worden allemaal door de provider bepaald, en die verschillen sterk.

Wat het label eigenlijk dekt

In de praktijk is OpenAI-compatible een korte lijst van concrete dingen. Als een provider ze allemaal ondersteunt, loopt de meeste client code ongewijzigd.

• Paden. Chat-verzoeken gaan naar POST /v1/chat/completions en de modellenlijst komt van GET /v1/models.
• Authenticatie. De sleutel reist in een Authorization: Bearer header.
• Verzoekbody. Een model string, een messages array van objecten met role en content, en optionele velden zoals temperature, top_p, stop en seed.
• Responslichaam. Een choices-array met het bericht van de assistent, een finish_reason en een usage-object met tokenaantallen.
• Streaming. Met stream: true stuurt de server Server-Sent Events, elk met een kleine JSON-delta, eindigend met een eindmarker.
• Optionele functies. Toolaanroep, JSON-modus en vergelijkbare velden, waar de provider kiest om ze te ondersteunen.

Omdat er zoveel tools voor dit formaat zijn geschreven, werd het een gemeenschappelijk doelwit. Editors, agentframeworks, roleplay-interfaces en gewone scripts laten je allemaal een aangepaste basis-URL invoeren, en dat is alles wat ze nodig hebben.

Waarom één formaat het gemeenschappelijke doel werd

Het chatvoltooiingen-formaat verspreidde zich omdat het eenvoudig was en vroeg beschikbaar kwam. Een toolauteur die het eenmaal ondersteunt, kan veel backends bereiken, en een backendauteur die het eenmaal ondersteunt, kan veel tools bereiken. Dat is een goede deal voor beide partijen, dus het formaat bleef hangen, zelfs bij diensten die niets te maken hebben met het bedrijf dat het ontwierp.

Voor jou als ontwikkelaar heeft dit een praktische betekenis. Je code hoeft niet voor elke provider een andere integratie. Je kunt een prototype in een middag tussen eindpunten verplaatsen, twee modellen op dezelfde prompts vergelijken, of een tweede provider als uitvaloptie houden als de eerste langzaam is. De kosten om van gedachten te veranderen zijn laag, en dat maakt het makkelijker om een nieuwe service te proberen zonder je eraan te binden.

De keerzijde is dat het gedeelde oppervlak echte verschillen verbergt. Omdat wisselen zo makkelijk is, is het verleidelijk aan te nemen dat alles achter de URL equivalent is. Dat is het niet, en de secties hieronder tonen waar de kloven meestal verschijnen.

Wat het je niet vertelt

Hier komen mensen verrast. Het label laat alles weg dat bepaalt of de API nuttig is voor je werk.

Het model erachter

Een compatibele endpoint kan elk model bedienen. Sommigen bedienen open-weight modellen, anderen routeren naar meerdere leveranciers, anderen verpakken een propriëtaire model. Compatibiliteit betekent niet dat de service wordt gerund door OpenAI, en het betekent niet dat het model zich gedraagt als een van hun modellen. De modelnaam die je doorgeeft in model is gewoon een string die de provider definieert.

Weigergedrag

Contentregels behoren tot het model en de provider, niet tot het protocol. Twee compatibele APIs kunnen op exact tegenovergestelde manieren reageren op dezelfde prompt. Als jouw toepassing fictie, roleplay of ander wettelijk volwassen materiaal is, controleer dan wat de provider zegt over weigeringen voordat je iets gaat integreren.

Functie diepgang

Sommige providers implementeren alleen chat. Anderen voegen tools, JSON-modus, logaritmische kansen of extra endpoints toe. Een client die een veld stuurt dat de server negeert, faalt niet altijd luidruchtig, dus een stille mismatch is mogelijk.

Limieten, prijzen en fouten

Rate limits, contextlengte, maximale lichaamsgrootte en prijs per token zijn allemaal keuzes van de provider. Foutlichamen verschillen ook in details, zelfs als de HTTP-statuscodes overeenkomen, dus je retry-logica moet zich baseren op statuscodes en headers in plaats van op berichttekst.

Een snelle compatibiliteitstest

Je kunt een provider in een paar minuten verifiëren met drie verzoeken. Vervang de sleutel door je eigen. Dit voorbeeld gebruikt de basis-URL van deze site.

Copycurl https://api.kimicode.top/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

De eerste aanroep bevestigt de sleutel en lijst model-IDs. De tweede controleert de chatstructuur. Test dan de delen waar je applicatie op leunt: voeg "stream": true toe en kijk naar incrementele chunks, geef een tools array door als je function calling gebruikt, en stel response_format in op {"type":"json_object"} als je parseerbare output nodig hebt.

Activeer ook een fout opzettelijk, zoals een ongeldige sleutel. Je wilt een standaard HTTP-statuscode en een JSON-foutbody zien die je client kan afhandelen.

Dezelfde aanroep in Node

De JavaScript SDK neemt dezelfde twee waarden. Hier is een streamingaanroep, wat de structuur is die de meeste chatinterfaces gebruiken.

Copyimport OpenAI from "openai";

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

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Name three uses of SSE." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

Als dit tekst woord voor woord afdrukt, werkt het streaming pad end to end. Dezelfde lus werkt tegen elke compatibele provider, wat het hele punt van het formaat is.

Hoe wisselen eruitziet in code

Met de officiële Python SDK is de verandering twee constructorargumenten. De rest van je programma blijft zoals het was.

Copyfrom openai import OpenAI

client = OpenAI(
    base_url="https://api.kimicode.top/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarize SSE in one sentence."}],
)
print(resp.choices[0].message.content)

De Node SDK is hetzelfde idee met baseURL en apiKey opties. Veel tools lezen OPENAI_BASE_URL en OPENAI_API_KEY uit de omgeving, dus je kunt soms wisselen zonder aan code te raken.

Verander ook de model string. Een verzoek dat een model noemt dat de nieuwe server niet host, faalt, en dat is de meest voorkomende eerste fout.

Waar de API van deze site past

Deze service is een gehoste, tekst-only API die het OpenAI formaat volgt. Het draait één open-weight model, gerund door een onafhankelijke provider en afgestemd om te antwoorden zonder inhoudsweigeringen voor wettelijk volwassen gebruik. Het is niet de officiële API van een model leverancier en het roteert niet tussen leveranciers. De model ID is uncensored.

Het ondersteunt streaming over SSE met usage gerapporteerd aan het einde, tool calling, JSON-modus, en doorgeven van temperature, top_p, stop, seed en de penalties. Het contextvenster is 100.000 tokens voor prompt en completion samen. Het genereert geen afbeeldingen of audio, en het biedt geen embeddings of fine-tuning. Een regel is vast: geen seksuele inhoud met minderjarigen.

Facturatie is prepaid en gemeten: $0,15 per 1M input tokens en $0,50 per 1M output tokens, zonder abonnement. Je kunt de cijfers zien op de prijzen pagina, en de docs lopen een eerste verzoek door. Als je het wilt proberen zonder te betalen, kunnen nieuwe accounts een $0,50 trial credit claimen met één klik op de API key pagina.

Veelvoorkomende compatibiliteitsvalkuilen

1. Verkeerde base URL. De URL moet eindigen op /v1. Clients voegen zelf /chat/completions toe; als je dit ook aan de base URL toevoegt, krijg je een 404.
2. Niet-ondersteunde parameters. Als een bibliotheek een veld verzendt dat de server niet kent, controleer dan of het wordt afgewezen of stil wordt genegeerd, en verwijder het vervolgens.
3. Streaming en gelijktijdige verzoeken. Een gestreamd verzoek houdt een concurrency-slot vast tot de stream eindigt. Als je app veel streams opent, kun je een 429-fout krijgen met code concurrency, zelfs als je het aantal per minuut laag is.
4. Opnieuw proberen bij 429. Behandel 429 als een signaal om te wachten. Als er een Retry-After-header aanwezig is, houd er dan rekening mee.
5. Token-telling. Ga er niet van uit dat de tokenizer van een andere provider hetzelfde is. Lees het usage-object in het antwoord voor de aantallen waarover je wordt gefactureerd.

Niets van dit is moeilijk op te lossen zodra je weet waar je naar moet kijken, en het komt meestal neer op het zorgvuldig lezen van de eerste foutmelding.

Meer handleidingen

• OpenCode met een OpenAI-compatible API: Instellen
• Kimicode-alternatief: Ongecensureerde gehoste LLM API
• Ongecensureerde LLM API: OpenAI-compatible integratie en prijzen