Inference API

Call Clanker Cloud inference with an API key

The Clanker Cloud inference endpoint gives paid account holders an API-key authenticated chat-completions surface for hosted model calls.

The first backend is Gemini. The request keeps provider and model as plain strings so newer Gemini model IDs and future providers do not require a schema redesign.

Start with Gemini-backed chat completions now; keep the model contract open for the next providers later.

Request

Minimal chat-completions call

curl

Use a paid Clanker Cloud account token as the API key. The response follows the familiar choices[0].message.content shape.

curl -sS "https://clanker-auth-gw-zc0ce3o.uk.gateway.dev/v1/inference/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CLANKER_CLOUD_API_KEY" \
  -d '{
    "provider": "gemini",
    "model": "gemini-3.5-flash",
    "messages": [
      { "role": "user", "content": "Explain this alert in one sentence." }
    ],
    "metadata": { "source": "external-client" }
  }'

Request shape

provider is optional. model is intentionally open text so new model IDs do not require a schema update.

{
  "provider": "gemini",
  "model": "gemini-3.5-flash",
  "messages": [
    { "role": "system", "content": "Keep replies concise." },
    { "role": "user", "content": "Summarize this incident." }
  ],
  "metadata": { "source": "external-client" }
}

Response shape

The endpoint returns an OpenAI-style non-streaming chat completion for easy client adoption.

{
  "id": "llm_...",
  "object": "chat.completion",
  "created": 1782100000,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ]
}

Endpoint

POST /v1/inference/chat/completions on the Clanker Cloud auth gateway.

Access

Requires a paid Clanker Cloud account token sent as X-API-Key or Authorization: Bearer <token>.

Model field

model is a free-form string, not an enum. Use a Gemini ID such as gemini-3.5-flash today.

Provider field

provider may be omitted or set to gemini/google now; more providers can be added later.

Supported providers

Works across the environments teams already run

The current product positioning covers cloud providers, Kubernetes, GitHub, and bring-your-own AI keys from one local operating surface.

Supports ->GeminiBYOK

Contract

API contract for the first provider release

Field	Current behavior	Expansion path
provider	Optional. gemini, google, and google-gemini route to the Gemini backend.	Additional provider strings can route to new backends later.
model	Required free-form string. Use Gemini model IDs or Gemini resource names today.	No enum change is needed when new provider model names are introduced.
messages	OpenAI-style system, user, and assistant messages. Empty messages are ignored.	The same shape can feed other chat-style providers.
metadata	Optional object stored with the interaction for diagnostics and feedback.	Can carry client, workspace, or feature identifiers without changing the core request.

Scope

What is intentionally not in the first cut

Streaming is not part of the first public endpoint.
Free and beta-only accounts receive 402 paid account required before model routing.
Non-Gemini providers are not routed yet even though the provider field is already a string.
The endpoint is for hosted model inference, not for cloud provider credentials or infrastructure actions.
The old desktop-app LLM path remains separate for backward compatibility.

FAQ

Common questions

Is the model field limited to a fixed list?

No. The API schema treats model as a free-form string. The first runtime backend is Gemini, so practical model IDs should be Gemini IDs until more providers are wired.

Can I use Authorization Bearer instead of X-API-Key?

Yes. Both X-API-Key and Authorization: Bearer <token> are accepted, but the token must belong to a paid Clanker Cloud account.

What happens for a free account token?

The endpoint returns 402 paid account required before it routes to Gemini or any future hosted model provider.

Does this endpoint receive cloud credentials?

No. It receives chat messages and optional metadata for hosted inference. Cloud provider credentials remain in the local app workflow.

Next step

Need local infrastructure context instead?

Use the MCP setup page when an agent needs the running desktop app, local provider credentials, and reviewed infrastructure actions.

Read MCP setup Read agent workflow