# Bkper AI Provider

Bkper AI is an OpenAI-compatible inference provider. Any compatible client or agent harness can call it with a valid Bkper access token and available AI allowance. The Bkper CLI Agent is one preconfigured client, not the boundary of the inference service.

Bkper AI returns model responses. It does not give a model access to Books, files, tools, or local commands. The consuming client controls those capabilities and their permissions.

## Requirements

You need:

- a Bkper account with an eligible subscription or trial allowance;
- a valid Bkper OAuth access token;
- a client that supports OpenAI-compatible Chat Completions with a custom base URL.

Requests are attributed to the authenticated Bkper user. Business and Professional subscriptions may use a shared domain allowance. See [Models and Usage](https://bkper.com/docs/ai/models.md) for allowance scope, current rates, and effective model settings.

## Provider configuration

| Setting | Value |
| --- | --- |
| Provider type | OpenAI-compatible Chat Completions |
| Base URL | `https://ai.bkper.app/v1` |
| Authentication | `Authorization: Bearer ` |
| Model discovery | `GET /v1/models` |
| Inference | `POST /v1/chat/completions` |

When a client asks for an API key, provide the Bkper access token. The client should send it as a bearer token. Do not use an OpenAI, Anthropic, or xAI API key with the Bkper AI base URL.

## Get a token for local testing

Any supported Bkper OAuth flow can supply the access token. The Bkper CLI is a convenient way to obtain a short-lived token for local testing:

```bash
bkper auth login
export BKPER_TOKEN="$(bkper auth token)"
```

Treat the token as a secret. Do not commit it, print it in shared logs, or put it in a client-side application bundle.

## Send a request

This request uses one current model ID as an example. Use `GET /v1/models` or [Models and Usage](https://bkper.com/docs/ai/models.md) for the current portfolio.

```bash
curl --fail-with-body https://ai.bkper.app/v1/chat/completions \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "bkper-agent-id: my-harness" \
  --data '{
    "model": "openai/gpt-5.6-luna",
    "messages": [
      {"role": "user", "content": "Reply with exactly: connected"}
    ]
  }'
```

The `bkper-agent-id` header is optional. Set it to a stable lowercase identifier such as `my-harness` when you want the usage dashboard to attribute requests to that client or application. Requests without a valid identifier appear with an unknown source.

## Configure another client or harness

Use these values in any client that supports a custom OpenAI-compatible provider:

1. Select **OpenAI-compatible** or **custom OpenAI provider**.
2. Set the base URL to `https://ai.bkper.app/v1`.
3. Use the Bkper access token as the API key or bearer token.
4. Enter an exact model ID from `GET /v1/models`.
5. If the client supports custom headers, set `bkper-agent-id` for source attribution.

Some clients support only the OpenAI Responses API. Bkper AI currently exposes the Chat Completions interface, so confirm that the client can call `/v1/chat/completions`.

## Request behavior

- `model` is required and must match a current Bkper AI model ID.
- `messages` uses the OpenAI-compatible chat message structure.
- Set `stream` to `true` when the client supports streamed Chat Completions.
- Use `reasoning_effort` only at a level supported by the selected model.
- Requested context, output, and reasoning remain subject to Bkper's effective server-side settings.

Supported thinking levels, defaults, context caps, and output caps belong to the model configuration. See [Models and Usage](https://bkper.com/docs/ai/models.md) rather than relying on an upstream provider's generic defaults.

## Errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request, unavailable model, or unsupported model setting |
| `401` | Missing or invalid Bkper bearer token |
| `402` | The authenticated subscription payment is overdue |
| `429` | The monthly Bkper AI allowance is exhausted |
| `502` | The selected upstream model provider failed |

There are no automatic paid Bkper AI overages. Review the authenticated [Bkper AI usage dashboard](https://ai.bkper.app) for the current allowance and request attribution.

## Next steps

- [Compare models, effective limits, rates, and allowance rules](https://bkper.com/docs/ai/models.md).
- [Use the preconfigured Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md).
- [Review Bkper CLI Agent security](https://bkper.com/docs/ai/cli-agent-security.md).