AI provider adapters expose declared capabilities through a shared registry and base interface. Provider connections store the configuration required to invoke a provider without coupling feature code directly to OpenAI or Gemini.

Administration pages show provider availability, connection state, supported use cases, test actions, and configuration scope. Secrets remain protected and must not be included in documentation or diagnostics.

Provider administration

Access

Only System Admins can open Configuration → Platform → AI. Org Admins may view their organization's finite balance and usage, but cannot change provider credentials, quality prices, monthly entitlements, or personal balances belonging to other users.

Provider connections

Blackcap supports multiple named OpenAI and Gemini connections at the same time, such as Production and Testing. A connection stores:

provider type and friendly name;
enabled state;
encrypted credential status;
safe test status and timestamps;
safe failure category.

Provider connections no longer have a provider-level Default Model. Each quality profile selects the model for its own use case, so there is only one authoritative model choice for a generation request. Changing a connection or model on a quality profile preserves the other compatible profile settings—such as token limits, Support Chat turn/history/retrieval limits, timeout, and social-media limits—rather than resetting the profile to defaults. Only a setting that is genuinely incompatible with the newly selected model is disabled or normalized.

Provider and profile model fields use Blackcap's curated capability catalog. Selecting a provider connection limits the model, resolution, aspect-ratio, provider-quality, and output-format controls to combinations supported by that Blackcap adapter. The catalog intentionally describes what Blackcap knows how to do with each model rather than assuming that every model returned by a vendor model-list API supports every Blackcap use case.

For saved provider connections, Blackcap also queries the provider's live model inventory and intersects it with the curated Blackcap capability catalog. For inexpensive text use cases, Blackcap additionally performs a tiny endpoint-specific capability probe against the API surface that Blackcap will actually use. This matters because a provider can report a model in its inventory while a particular project or API surface still returns a model-not-available response. Recipe image generation and transcription rely on inventory/capability metadata rather than generating billable test media merely to populate Configuration.

The availability checks apply across recipe image generation, social recipe extraction, Support Chat, and the OpenAI transcription model used by social recipe extraction. Existing profiles whose model is no longer usable remain visible with an Unavailable warning so the configuration can be repaired explicitly rather than silently changed.

Provider details show the complete Blackcap-supported model catalog for that provider using visual use-case badges: 🖼️ Recipe Image, 🎬 Social Recipe, 🛟 Support Chat, and 🎙️ Transcription. Models that the credential can see but Blackcap cannot actually use on the required API surface remain visible for troubleshooting, marked Unavailable with a red diagonal slash rather than silently disappearing. The same use-case badges appear on the main AI configuration page so the model capability display and configured use cases use one visual language.

Live model discovery and endpoint verification are cached briefly to keep Configuration responsive. The provider Test action forces a fresh model check. If provider discovery itself is temporarily unavailable, Blackcap preserves the curated catalog rather than destroying existing configuration. When a successful check proves that a model is unavailable for the credential/API surface, Blackcap does not offer it as a new selectable value. New provider connections cannot be live-filtered until their credential has first been saved.

OpenAI recovery-enabled generation currently uses gpt-image-2. Gemini supports gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-3-pro-image, and legacy gemini-2.5-flash-image. Gemini generation uses stateless Interactions API requests. The Gemini API does not accept Enterprise Agent Platform labels; Blackcap retains instance, organization, user, and job attribution in its own usage records instead. The Python Interactions path requests JPEG output and never retries the same request merely to remove unsupported fields.

A saved API key is never returned to the browser. Enter a new key only to create or rotate a credential. Connection tests do not consume AI Seeds. They make a minimal provider API request that may still be recorded or billed under the provider account.

Use case and quality profiles

Blackcap currently implements three user-facing AI use cases: 🖼️ Recipe Image Generation, 🎬 Social Recipe Extraction, and 🛟 Support Chat. Social Recipe Extraction may also use a specialized 🎙️ Transcription model where the provider workflow separates audio transcription from recipe extraction. Each use case can be enabled/disabled and can have one or more quality profiles.

Each user-visible profile is provider-independent and contains:

display name and description;
enabled/default status and display order;
configurable AI Seed cost;
assigned provider connection and model;
provider-supported resolution, aspect ratio, quality control, and output format;
a small allowlisted provider-options object.

Changing a profile affects new jobs only. Every submitted job snapshots the approved price, provider connection, model, output settings, and prompt version. Disabling a connection before a queued job executes causes a safe failure and reservation release; Blackcap does not silently send content to a fallback provider.

Monthly organization allotments

A System Admin configures the recurring amount, anchor day, billing timezone, enabled state, and effective behavior.

Beginning next billing period preserves the current period and applies the new entitlement at the next non-overlapping boundary.
Adjust the current period now atomically updates the existing current monthly bucket’s boundaries and configured amount. Spent and reserved amounts are preserved, the operation cannot reduce the bucket below those commitments, and Blackcap does not create a second overlapping monthly grant. If an overlapping bucket already exists, the transaction is rejected and rolled back for review.

Anchor days 29, 30, and 31 clamp to the final valid day of a short month without permanently drifting. Period boundaries are calculated in the billing timezone, persisted in UTC, and treated as start-inclusive/end-exclusive. Scheduled maintenance and lazy balance reads both create a missing current-period grant idempotently.

Manual adjustments

System Admins may grant or correct organization and personal balances. A reason is mandatory. Adjustments create append-only ledger entries; the application never performs an unexplained mutable balance edit. Ordinary corrections cannot make available AI Seeds negative.

Usage reporting

The dedicated Administration → AI Usage page filters by date range, provider, connection, use case, profile, organization, user, outcome, source, and—when System Admin cost data is available—estimated provider-cost range. Provider, connection, and profile are linked facets: selecting any one narrows the compatible values in the other two. Selecting an organization narrows the user list to users associated with that organization, while generated regression-test and diagnostic-clone identities are excluded from the normal user selector.

The report tracks the quality-profile name, configured AI Seed usage, provider/model, outcome, normalized provider token usage, latency, and estimated provider cost. Configured AI Seed usage is recorded even for Unlimited accounts; Unlimited determines whether a finite balance is debited, not whether the product usage occurred. Provider request identifiers, estimated provider cost, and detailed provider-token diagnostics are visible only to System Admins. The report includes total estimated provider cost plus summaries for Recipe Image Generation, Social Recipe Extraction, and Support Chat, all using the current report filters.

AI Seed charges come from the profile snapshot, not from provider token usage. This preserves historical product pricing even when Blackcap changes providers, models, or provider costs.

Unused AI Asset Retention

This use-case setting controls how long Blackcap keeps generated image candidates that were not selected for a recipe. The purge job removes those unused or rejected candidate files after the configured number of days. Images accepted and saved with a recipe are moved into the normal recipe image/cache workflow and are not deleted by this setting.

Administration locations after the AI administration reorganization

Configuration → Platform → AI now contains only platform configuration: billing identity, provider connections, use cases, quality profiles, models, prices, and retention. Organization and personal balance editors are no longer duplicated on this page.

Use:

Administration → Organizations for organization AI Seed summaries and System Admin adjustments;
Administration → Users for global personal AI Seed summaries and System Admin adjustments;
Administration → AI Usage for authorized organization-scoped reporting and Provider Billing Reconciliation export;
Administration → Data Cleanup for asset-type-aware unused AI asset cleanup.

The Add Provider dialog has a static backdrop and explicit Cancel action, so an accidental click outside the dialog does not discard entered credentials or settings.

Unused AI Asset Retention help is generated from the selected use case’s asset metadata. Manual recipe image generation refers to unselected generated recipe images; unknown use cases use neutral AI-asset wording.

Administration APIs, Database resources, and tests

The authenticated JSON report is available at GET /api/admin/ai/usage and is exposed in the curated API Tester together with the System Admin reconciliation CSV and read-only organization/personal balance endpoints. Non-System Admin report models remove provider request IDs, provider token counts, provider usage payloads, and provider response metadata before serialization.

Database Admin exposes the AI foundation tables plus metadata-oriented Support Chat Sessions, Support Chat Messages, and Support Chat Message Sources resources to System Admins. AI Usage exposes cached/reasoning token counts, Support Chat correlation IDs, prompt/documentation versions, and estimated provider cost where available. Credentials, raw prompts, Support Chat message text/context payloads, provider snapshots, file paths, provenance, and private JSON payloads remain hidden.

The deterministic regression suite verifies AI Usage authorization/privacy, filters and summaries, API Tester coverage, AI Database resources, Support Chat lifecycle/usage behavior, backup/restore of Support Chat session → message → source relationships, and the mocked recipe-image/accounting workflow without calling paid providers. The recipe-image phase uses a currently enabled configured profile and its authoritative AI Seed cost; it does not require the original seeded profile names or prices. See AI Administration, AI Seeds, and Usage Reporting.

Provider adapter architecture

Boundary

Recipe routes and templates call the provider-independent AI image service. They never construct OpenAI or Gemini requests. Provider-specific behavior belongs in an adapter registered by ai_provider_registry.py.

The current adapter contract supports:

validating a configured connection;
translating a normalized image request;
returning validated image bytes and MIME type;
returning model, safe request ID, and latency;
normalizing input, output, image, and provider-specific usage;
classifying authentication, rate limit, safety, timeout, unsupported setting, unavailable, invalid response, and permanent provider failures.

Current provider transport choices

OpenAI image generation defaults to the configurable gpt-image-2 model.
Gemini image generation defaults to the configurable gemini-3.1-flash-image model and uses the Gemini Interactions API. Requests set store=False so Blackcap does not opt into provider-side interaction retention.
Blackcap requires openai>=2.46.0 and google-genai>=2.13.0 so an ordinary requirements update advances existing environments to the current SDK lines used by these adapters. Blackcap does not retry an uncertain Gemini Interactions request through generateContent, because doing so could create and charge for a duplicate image.

Adding a provider

Implement AIProviderAdapter in a dedicated module.
Lazy-import the provider SDK so installations that do not configure that provider can still start.
Translate only allowlisted options. Never pass arbitrary UI JSON directly to an SDK.
Return AIImageResult; never attach images or alter AI Seed balances inside the adapter.
Raise AIProviderError with a normalized category and a user-safe message.
Do not log credentials, complete raw responses, or full prompts.
Register the adapter and add mocked success/failure/secret-redaction tests.
Add a paid live test only behind BLACKCAP_RUN_LIVE_AI_TESTS=1 and explicit provider model variables.

Job and accounting flow

route
  -> AI image service
  -> resolve use case/profile/connection
  -> snapshot configuration and price
  -> reserve selected AI Seed account transactionally
  -> durable job
  -> provider adapter
  -> validate and save candidate
  -> settle reservation exactly once
  -> usage event exactly once
  -> explicit user acceptance
  -> existing recipe image and cache services

If a provider fails before a usable image exists, the reservation is released. If a usable validated candidate exists but a later database or cache step fails, the candidate is preserved and the job enters recovery rather than releasing the reservation. Restart reconciliation settles and records that result once without issuing a second provider request.

Database rules

All SQL lives in inky_admin/repositories/ai_repository.py and uses the centralized application database service. Domain services, adapters, workers, routes, and templates contain no direct SQL. Every query uses explicit columns. PostgreSQL row locking and SQLite controlled write transactions remain behind the database service boundary.

Financial ledger and usage rows intentionally do not depend on purgeable job or reservation foreign keys. Candidate files and operational jobs may have different retention policies without destroying accounting history.

On this page