Bkper AI Provider

Connect an Open Responses client or agent harness to Bkper AI inference using Bkper authentication.

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

The live GET /v1/models response is authoritative for the current default model, available IDs, capabilities, limits, and effective usage rates. Generic integrations can start with default_model. Capability-sensitive integrations should inspect the selected entry in data instead of relying on model IDs or capabilities shown in examples.

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.

Model IDs

Bkper AI publishes stable, versionless, slash-free family IDs such as gpt-luna, grok, and gemini-flash.

A family ID remains stable when Bkper upgrades its concrete provider revision. Provider revisions are an internal serving detail rather than a public version-pinning contract.

Older versioned and publisher-prefixed IDs still work as compatibility aliases, but they resolve to the current model family rather than pinning an older revision. Catalogs, responses, and usage reports return the canonical family ID.

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": "gpt-luna",
    "input": "Reply with exactly: connected",
    "store": false
  }'

The response is an Open Responses resource. Its model contains the canonical 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": "grok",
    "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.

Privacy, retention, and caching

Zero data retention where available. Minimum retention everywhere. Bkper disables provider application storage on every request and keeps prompt and response content out of usage logs.

Bkper applies these boundaries across the inference path:

omitted store becomes false, and store: true is rejected before provider dispatch;
Bkper usage records contain attribution, status, token, cache, and cost metadata—not prompt or response content;
detailed Bkper usage events are retained for 180 days, while daily aggregate usage remains available for allowance enforcement and reporting;
Cloudflare AI Gateway payload logging is disabled, while content-free request metadata remains available for observability;
exact, non-streaming structured JSON requests and responses may be cached by Cloudflare for up to 24 hours; other response requests bypass this cache;
provider-native prompt caches may hold content temporarily under the selected provider’s caching policy.

Provider retention controls differ:

Provider	Bkper configuration	Provider retention boundary
xAI	`store: false`; Zero Data Retention is active for Bkper’s xAI team	Prompt and response retention is disabled under the enabled Zero Data Retention control.
OpenAI	`store: false`; Bkper organization API-call logging is disabled	API data is not used for training by default. Customer content may remain in abuse-monitoring logs for up to 30 days because Bkper does not currently have OpenAI Zero Data Retention.
Google Gemini paid API	`store: false`; Bkper avoids Search and Maps grounding, the File API, and explicit context caching	Paid API content is not used for training. Content may be retained for limited abuse monitoring because Bkper’s AI Studio project does not currently have approved Zero Data Retention. Gemini may also use project-isolated in-memory caching for up to 24 hours.
Fireworks AI	`store: false`; Zero Data Retention is active by default; used as the current serving route for open-weight models	Fireworks does not log or persist prompt or generation data for open models without explicit opt-in. Prompt caching may retain data in volatile memory for several minutes. `store: false` prevents Response API conversation storage.

Public model identity is independent of serving infrastructure. The catalog’s owned_by field identifies the model creator. Bkper may change a serving route or upgrade the concrete provider revision without changing the canonical model family ID.

Caching is separate from response state and logging. A cache can temporarily retain an exact request and response without creating a retrievable conversation or including that content in usage logs. prompt_cache_key may be retained as usage metadata and displayed in the usage dashboard, so use an opaque identifier rather than customer or financial information.

Provider policies and Bkper configurations can change. Review these primary references for the current boundaries:

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