Bkper AI Provider

Bkper AI provides selected AI models through one endpoint using Bkper authentication and the AI allowance included with eligible plans. The Bkper CLI Agent is ready to use without a separate provider account or API keys. Other clients can connect through the Open Responses 2026-04-24 contract.

Bkper AI keeps provider credentials server-side. It routes requests, attributes usage, meters provider-reported tokens, and enforces the recorded monthly allowance. Compatible clients retain control of model and generation settings within provider-native capabilities.

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 Open Responses 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 for allowance scope, current rates, and provider-native capabilities.

Provider configuration

Setting	Value
Provider type	Open Responses 2026-04-24 profile
Base URL	https://ai.bkper.app/v1
Authentication	Authorization: Bearer <Bkper access token>
Model discovery	GET /v1/models
Inference	POST /v1/responses

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.

Bkper AI implements a documented subset of Open Responses. It does not claim full specification compliance.

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:

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 complete request

This request uses one current model ID as an example. Use GET /v1/models or Models and Usage for the current portfolio.

curl --fail-with-body https://ai.bkper.app/v1/responses \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "bkper-ai-source: my-harness" \
  --data '{
    "model": "openai/gpt-5.6-luna",
    "input": "Reply with exactly: connected",
    "store": false
  }'

The response is an Open Responses resource. Its model remains the public Bkper model ID, and store is always false.

The bkper-ai-source 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. The legacy bkper-agent-id header remains a fallback. Requests without a valid identifier appear with an unknown source.

Stream a response

Set stream to true to receive semantic server-sent events:

curl --no-buffer --fail-with-body https://ai.bkper.app/v1/responses \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "xai/grok-4.5",
    "input": "Explain the from-to movement model in one sentence.",
    "stream": true,
    "store": false
  }'

Each SSE event: name matches the event body’s type. Sequence numbers increase monotonically. A stream ends with one terminal response event followed by data: [DONE].

Supported profile

The Phase 1 profile supports:

• all model IDs listed by GET /v1/models;
• string input and explicit conversation item arrays;
• system, developer, user, and assistant messages;
• text and image input;
• inline PDF input through Base64 input_file.file_data for models that advertise native file support;
• JSON Schema structured output through text.format for models that advertise native schema support;
• function tools, function calls, function outputs, and multiple tool calls where the model supports them;
• model-supported reasoning effort pass-through and reasoning summaries;
• encrypted reasoning continuity where the provider supplies it;
• prompt_cache_key for short cache and session affinity;
• complete JSON responses and semantic SSE streaming;
• explicit conversation history across supported models and providers.

The server validates model-specific file, structured-output, output, and reasoning settings before provider dispatch. Valid client values pass through unchanged. Omitted values remain omitted when the native provider protocol allows omission. Context overflow errors are normalized after the provider performs native tokenization. Provider-reported usage drives deterministic allowance settlement.

Structured JSON output

Set text.format.type to json_schema and provide a standard JSON Schema. Bkper AI maps the schema to each model provider’s native structured-output mechanism.

• strict: true is preserved only when the selected model can enforce the submitted schema subset.
• strict: false supports schemas that require provider-supported flexibility, such as typed dynamic maps.
• Malformed supported keywords and incompatible schemas fail before provider dispatch. Bkper AI never silently changes a strict schema to non-strict behavior.

The returned structured JSON is contained in the assistant output_text and should still be parsed and validated by the client before use.

Inline PDF input

Use one inline PDF source with a filename:

{
    "type": "input_file",
    "filename": "document.pdf",
    "file_data": "<base64>"
}

Bkper AI validates the Base64 content and selected model capability before dispatch. It sends inline content through the provider’s native document input and does not upload it to a hidden provider Files API.

Inline files are available only on models that advertise native support. The current xAI model does not support inline file_data. Use GET /v1/models to inspect current capabilities.

Stateless behavior

Bkper AI does not persist response state:

• omitted store behaves as false;
• store: false is accepted;
• store: true is rejected;
• continue conversations by sending explicit prior items in input.

prompt_cache_key is a bounded cache hint. It is not a persisted response identifier.

Unsupported features

The current profile rejects:

• previous_response_id;
• background responses;
• response retrieval or deletion;
• client metadata;
• input_file.file_id and input_file.file_url;
• inline file types or models without advertised native support, including xAI inline files;
• remote HTTP/HTTPS image URLs for Gemini; send Gemini images as inline data URLs;
• hosted provider tools;
• compaction endpoints;
• WebSocket transport;
• image generation, audio, speech, batches, and fine-tuning.

Unsupported fields fail explicitly rather than being ignored or passed to only one provider.

Errors

Errors use an Open Responses-shaped envelope with stable Bkper error codes.

Status	Meaning
400	Invalid request, unavailable model, unsupported capability, or context overflow
401	Missing or invalid Bkper bearer token
402	The authenticated subscription payment is overdue
403	The account is not entitled to use Bkper AI
429	The monthly Bkper AI allowance is exhausted or the upstream provider is throttled
499	The client aborted the request
502	The selected upstream model provider or transport failed

Bkper AI blocks new requests once the recorded monthly allowance is exhausted. There are no automatic paid Bkper AI overages and no automatic fallback to another protocol. Review the authenticated Bkper AI usage dashboard for the current allowance and request attribution.

Bkper CLI Agent

The Bkper CLI Agent uses Pi’s standard openai-responses transport with Bkper authentication, source attribution, short prompt caching, and the public Bkper model IDs preconfigured.

bkper auth login
bkper agent

Next steps

• Compare models, provider capabilities, rates, and allowance rules.
• Use the preconfigured Bkper CLI Agent.
• Review Bkper CLI Agent security.