Skip to content

OpenAI-compatible endpoint

Use a Kojen deployment with the OpenAI SDK (Python and TypeScript)

Every Kojen deployment is an OpenAI-compatible chat completions endpoint. Change the base URL and key in the official OpenAI SDK for Python or TypeScript: streaming, tools and structured output.

Before you start

  • Deploy a model in Kojen (Deployments → New deployment). Its id goes in the base URL: https://kojen.ai/api/v1/endpoints/<deployment-id>.
  • Create a deployment key (kojen_dk_…) under Deployments → Learning, revisions & keys. It can only call that one deployment, so it's the right key to ship in an app. An account key (kojen_…, Settings → API Keys & MCP) of the deployment's owner with the read or write scope also works.
  • Keep the key server-side, e.g. in KOJEN_DEPLOYMENT_KEY. Anyone holding it can call the deployment and spend its owner's token allowance.

Python

Python (openai)
pip install openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://kojen.ai/api/v1/endpoints/<deployment-id>",
    api_key=os.environ["KOJEN_DEPLOYMENT_KEY"],   # kojen_dk_… for this deployment (or an owner key)
)

reply = client.chat.completions.create(
    model="ignored",   # the deployment decides the model and system prompt
    messages=[{"role": "user", "content": "I was charged twice"}],
    temperature=0.2,
    max_tokens=256,
)
print(reply.choices[0].message.content)
prediction_id = reply.model_extra["kojen"]["prediction_id"]

Tool calling and JSON-schema output use the same parameters as against OpenAI:

Python
tools = [{
    "type": "function",
    "function": {
        "name": "get_order",
        "description": "Look up an order by number",
        "parameters": {
            "type": "object",
            "properties": {"order_number": {"type": "string"}},
            "required": ["order_number"],
        },
    },
}]

reply = client.chat.completions.create(
    model="ignored",
    messages=[{"role": "user", "content": "Is order 1042 refundable?"}],
    tools=tools,
)
print(reply.choices[0].message.tool_calls)

# Structured output
reply = client.chat.completions.create(
    model="ignored",
    messages=[{"role": "user", "content": "I was charged twice"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "ticket",
            "schema": {
                "type": "object",
                "properties": {"category": {"type": "string", "enum": ["billing", "bug", "how-to"]}},
                "required": ["category"],
            },
        },
    },
)
print(reply.choices[0].message.content)

TypeScript / Node

TypeScript (openai)
npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://kojen.ai/api/v1/endpoints/<deployment-id>",
  apiKey: process.env.KOJEN_DEPLOYMENT_KEY, // kojen_dk_…
});

const reply = await client.chat.completions.create({
  model: "ignored", // the deployment decides the model and system prompt
  messages: [{ role: "user", content: "I was charged twice" }],
});
console.log(reply.choices[0].message.content);
TypeScript, streaming
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://kojen.ai/api/v1/endpoints/<deployment-id>",
  apiKey: process.env.KOJEN_DEPLOYMENT_KEY, // kojen_dk_…
});

// Tokens arrive as the model writes them.
const stream = await client.chat.completions.create({
  model: "ignored",
  messages: [{ role: "user", content: "App crashes on login" }],
  stream: true,
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");

Send feedback on predictions

Each completion includes a kojen object next to choices. The SDKs keep unknown fields: in Python read reply.model_extra["kojen"], in TypeScript cast the reply. Posting feedback lets Kojen track quality and, if you turned it on, retrain from corrections.

TypeScript
// Rate a prediction so Kojen can learn from it (continuous learning).
const predictionId = (reply as unknown as { kojen: { prediction_id: string } }).kojen.prediction_id;

await fetch("https://kojen.ai/api/v1/endpoints/<deployment-id>/feedback", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOJEN_DEPLOYMENT_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prediction_id: predictionId, feedback: "negative", correction: "billing" }),
});

What the endpoint supports

  • model is ignored: the deployment decides the model and system prompt. Any string works; SDKs that require one just need something.
  • stream: true streams real SSE chunks ending in [DONE]; stream_options: { include_usage: true } adds a final usage chunk.
  • tools, tool_choice, parallel_tool_calls and response_format (text, json_object, json_schema) are forwarded to the model, and its tool_calls come back unchanged, so tool calling and structured output work through the SDK as usual.
  • Also forwarded: temperature, top_p, n (up to 4), stop, seed, the penalties and max_tokens / max_completion_tokens (up to 4,096).
  • Only POST /chat/completions and POST /feedback exist under the base URL. There is no /models, /embeddings or Responses API, so use the SDK's chat-completions client.
  • Each reply carries kojen.prediction_id (also the X-Kojen-Prediction-Id header). Post it to /feedback to rate a prediction and feed continuous learning.
  • Errors use OpenAI's { error: { message, type, param, code } } shape; 429s send Retry-After.

Get an API key

Kojen is free to start, no card needed. Train and evaluate an agent, deploy it behind an OpenAI-compatible endpoint, and connect your tools over MCP.

Create a free account

Also see: Vercel AI SDK · LangChain · LlamaIndex · Claude Code · Cursor · Claude Desktop