Developers
Kalchevo AI API
How the sites we build talk to the AI. You only need this if you are working on one of them.
Every site on Kalchevo gets a site key (starts with kal_). Send it as the X-Site-Key header. Credits are deducted from the site owner's balance. There is no AI key to manage on the site itself.
Endpoints
| Method and path | Body | Credits |
|---|---|---|
GET /api/v1/balance | free | |
POST /api/v1/ai/blog | { topic, site?, area?, owner?, links?: [{title,url}], tone?, words? } | 60 |
POST /api/v1/ai/image | { prompt, style?, size? } returns base64 PNG | 40 |
POST /api/v1/ai/improve | { text, instruction? } | 10 |
POST /api/v1/ai/topics | { about?, count? } | 5 |
POST /api/v1/ai/chat | { messages: [{role, content}] } | 3 per 1k tokens |
POST /api/v1/checkout/session | free, returns a URL to open in a popup so the customer can buy credits | |
GET /api/v1/usage | free, last 50 uses |
Engines
Every AI call accepts an optional engine (for example fast, better, best, img-low, img-high). GET /api/v1/engines lists what is available with the credit price of each action per engine. Omit it for the default engine.
Responses
{ "ok": true, "credits_used": 60, "balance": 940, "result": { ... } }
Out of credits returns HTTP 402 with { "code": "insufficient_credits", "needed": 60, "balance": 12 }. Show the customer a "Buy credits" button that opens the checkout session URL.
Node.js example
const kal = require('./kalchevo-client')({ siteKey: process.env.KALCHEVO_SITE_KEY });
const post = await kal.blog({ topic: 'How many fire marshals do I need?' });
console.log(post.result.title, post.balance);
The drop in client (kalchevo-client.js) and the admin widget (kalchevo-widget.js) come with every Kalchevo site build.