API Reference

OpenClacky exposes a set of OpenAI-compatible HTTP APIs covering text chat. If you're already using the OpenAI or any major SDK, just swap base_url to ours and api_key to a key you've topped up at OpenClacky — no other code changes required.

This page is for developers. It covers four things: how to authenticate, what endpoints exist, what each request/response looks like, and how to read errors.

Basics

Authentication

Pass the bearer token on every request:

curl https://api.openclacky.com/chat/completions \
  -H "Authorization: Bearer sk-oc-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

x-api-key: sk-oc-xxxxxxxxxxxx is also accepted (some SDKs prefer this).

Endpoint catalog

The most-used endpoints are documented below.

1. Chat — POST /chat/completions

Request body (standard OpenAI Chat Completions):

{
  "model": "dsk-deepseek-v4-pro",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "temperature": 0.7,
  "stream": false
}

Response body (standard OpenAI shape + our cost_usd):

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "dsk-deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hi there!" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 4,
    "total_tokens": 16
  },
  "cost_usd": 0.000084
}

Model alias rules

The full model list lives at AI Key Supported Models. Newly launched models are added there.

Streaming

Set "stream": true and you'll get a standard OpenAI SSE stream (data: {...}\n\n … data: [DONE]\n\n). Works with the Python openai SDK, Vercel AI SDK, and similar clients out of the box.

6. List models — GET /models

Returns the models available to the API key making the request.

Request: GET /models, authenticated with a Bearer Token.

Response:

{
  "object": "list",
  "data": [
    { "id": "dsk-deepseek-v4-pro", "object": "model", "owned_by": "openclacky" }
  ]
}

• If the API key has allowed_models configured, only the intersection is returned.
• Without a whitelist, all available models are listed.

7. Balance & quota — GET /balance

Returns the account balance and key-level quota usage for the API key making the request.

Request: GET /balance, authenticated with a Bearer Token.

Response:

{
  "is_available": true,
  "balance_infos": [
    { "currency": "USD", "total_balance": "5.0" }
  ],
  "quota": {
    "enabled": true,
    "amount": 10.0,
    "used": 3.5,
    "remaining": 6.5,
    "reset_period": "monthly"
  }
}

Note: The quota field only appears when quota is enabled and quota_amount is set on the key. Keys without quota will not include this field.

Pricing at a glance

Prices already include our 5% service markup (subject to change — actual charges in cost_usd are authoritative).

Chat (per-token)

Token rates vary per model. Look up the exact price at AI Key Supported Models before you commit; the cost_usd field on every response is the authoritative charge.

Error codes

Every error returns this JSON envelope:

{
  "error": {
    "code": "invalid_api_key",
    "message": "invalid api key",
    "type": "auth_error"
  },
  "error_message": "invalid api key"
}

Retry guidance: 429 / 502 are safely retryable with exponential backoff (start at 1 s, max 3 attempts). Don't retry 400/401/402/403.

SDK examples

We're OpenAI-compatible — use the OpenAI SDK as-is, just swap base_url and api_key.

Python (openai SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.openclacky.com",
    api_key="sk-oc-xxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="dsk-deepseek-v4-pro",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Node.js (openai SDK)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.openclacky.com",
  apiKey: process.env.OPENCLACKY_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "dsk-deepseek-v4-pro",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

FAQ

Q: Do you support streaming?
A: Yes for /chat/completions (set stream: true).

Q: Are there rate limits?
A: Each key has a generous default RPM cap. Hitting it returns 429 quota_exceeded — back off and retry, or contact us for a higher quota.

Q: How do I reconcile costs?
A: Every response carries cost_usd — that's the authoritative charge for that call. Monthly invoices and per-call breakdown are in the dashboard.