# Clanker Cloud Inference API

Use this page when you need the public paid-account Clanker Cloud hosted inference contract.

## Endpoint

```text
POST https://clanker-auth-gw-zc0ce3o.uk.gateway.dev/v1/inference/chat/completions
```

## Authentication

Send a paid Clanker Cloud account token as either:

```text
X-API-Key: <token>
Authorization: Bearer <token>
```

Free and beta-only account tokens receive `402 paid account required` before the request reaches the hosted model backend.

## Current provider scope

- The first runtime backend is Gemini.
- `provider` is optional. `gemini`, `google`, and `google-gemini` route to the Gemini backend.
- `model` is a free-form string, not an enum. Use Gemini model IDs such as `gemini-3.5-flash` or Gemini resource names such as `models/gemini-3.5-flash`.
- Additional provider strings can be routed later without changing the request schema.

## Curl example

```bash
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

```json
{
  "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

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

## First-cut limits

- Streaming is not part of the first public endpoint.
- Free and beta-only accounts receive `402 paid account required`.
- Non-Gemini providers are not routed yet.
- The endpoint receives chat messages and optional metadata for hosted inference. It does not receive cloud provider credentials.
- The old desktop-app LLM path remains separate for backward compatibility.