🤖 AI Seeds and Usage

Audience: User, Org Admin, System Admin, Developer Related: Overview · Providers And Connections · Ai Image Generation · Data Retention

AI Seeds are Blackcap’s product currency for AI use. They are distinct from API Tokens. Usage flows reserve Seeds before provider work, commit actual usage when successful, and release or reconcile reservations when work fails or is abandoned.

The system supports organization AI Seeds, global personal AI Seeds, monthly allotments, provider-reported tokens, use-case pricing, usage reporting, and generated-asset retention. Legacy code-facing names may remain internally until migrated, but user-facing documentation and UI use AI Seeds.

What AI Seeds are

AI Seeds are Blackcap's credits for AI features. Each AI action shows its AI Seed cost before confirmation. Blackcap shows this explanation anywhere the term appears through an accessible help tooltip.

AI Seeds are not API Tokens. API Tokens continue to authenticate software integrations. Provider-reported tokens are usage measurements supplied by OpenAI or Gemini and do not determine the Blackcap AI Seed charge.

Organization and personal balances

• Organization AI Seeds are shared by authorized users in the active organization.
• My AI Seeds belong globally to the signed-in user and remain available across every organization that user may access.
• A finite monthly organization allotment expires at the next subscription-cycle boundary and does not roll over.
• Additional organization or personal grants do not expire unless a future grant explicitly includes an expiration.
• The Default organization is Unlimited. A System Admin’s personal AI Seed source is also unlimited, but organization funding still uses the selected organization’s actual finite or unlimited balance. Unlimited use still records the quality profile's configured AI Seed usage and provider usage; it simply does not debit a finite balance. This lets AI Usage compare product-credit consumption with provider cost even for System Admin/Unlimited activity.

The user selects the spending source before every metered generation. Blackcap never silently switches to the other source when the selected balance is insufficient.

Generate an image

AI image generation is currently available only for manually entered recipes.

1. Create or edit a manual recipe and save enough information to identify the dish: a title plus a description or ingredients.
2. Select Generate Image with AI. On a new manual recipe, use Save & Generate Image.
3. Choose a configured quality profile. Blackcap initially seeds Medium at 1 AI Seed and High at 10 AI Seeds, but a System Admin may change those prices.
4. Choose Organization AI Seeds or My AI Seeds.
5. Optionally add image notes such as composition, serving style, or camera angle.
6. Submit the job. The dialog shows honest stages rather than invented percentages.
7. Return later if needed. Queued and completed candidates are durable across navigation and application restarts.
8. Review the generated image beside the existing recipe image, when present.
9. Select Use this image, keep the current image, reject the candidate, or generate another image.

Generating another image creates another provider request and consumes the configured AI Seed price. Accepting an already generated image does not charge again.

Privacy and safety

Blackcap sends only the recipe details needed to create the image: title, description, relevant ingredients, cuisine or preparation context, and optional image notes. It does not send user contact details, organization secrets, API Tokens, provider credentials, or unrelated recipe-library data.

Returned files are checked for supported image type, file signature, decoded dimensions, maximum byte size, and Pillow readability before storage. Provider safety failures are normalized into a user-safe message; raw provider responses and credentials are not displayed.

Candidate retention

An unused candidate remains available for the platform-configured retention period, initially seven days. Accepted images follow normal recipe artifact retention. The scheduled purge removes expired unused candidate files while durable AI Seed ledger and usage records remain available for audit and reconciliation.

Where balances are shown and managed

Organization AI Seeds appear on the Organizations results list, Organization Details, and Current Organization. A bounded monthly allotment uses the purple blackcap-fruit meter and exact text; additional balances and reservations are also shown. The Organizations page can filter by no allotment, no active period, exhausted, less than 10% or 25% remaining, additional balance, reservations, and Unlimited. The Default organization is labeled Unlimited.

Global personal AI Seeds appear on the Users list and the signed-in user’s Account page. Personal balances do not use a percentage meter because they are not a bounded monthly entitlement. System Admins may adjust a user’s global personal balance from Users. Org Admins may view an active organization member’s available and reserved global balance, but cannot edit it or see usage from organizations they do not administer.

The Account page separates My Personal AI Seeds from Organization AI Seeds and shows recent personal-funded usage. It is read-only and does not include purchasing controls.

AI Usage reporting

Authorized administrators use Administration → AI Usage. Org Admins may report across one or all organizations they administer. System Admins may report across all organizations or one selected organization. The report uses server-side paging, sticky headers, an anchored Actions column, and the selected authorization scope.

Filters and sorting

The report can filter by date range, organization, user, provider, connection, use case, quality profile, result, and AI Seed source. System Admins can also enter minimum/maximum Estimated Provider Cost values to isolate expensive requests. Latency and estimated cost can be sorted lowest-to-highest or highest-to-lowest.

The selectors are faceted rather than independent. Selecting an organization narrows the user list to users associated with that organization. Regression-test and diagnostic-clone identities are omitted from the normal user selector. Provider, connection, and profile narrow one another in every direction, so an incompatible selection is not left behind when another facet changes.

What each usage row records

Each completed or meaningfully attempted provider operation records the use case, quality-profile key/name, provider connection, provider/model actually used, outcome, latency, configured AI Seed usage, and normalized provider usage when available. The Provider cell stays compact; the exact model is available from its tooltip/details. Provider request identifiers are visually truncated but can be copied from the row action for support/correlation. Whether a vendor's own dashboard can search that identifier depends on the provider.

Provider token details keep the label and value together. Input, cached input, output, reasoning/thinking, and image/media token counts appear only when that provider actually reports them; Blackcap does not display a meaningless Image: — row merely because the use case generated an image.

Configured AI Seed usage is tracked even when the funding account is Unlimited. For example, if a profile is configured for 10 AI Seeds, AI Usage records 10 Seeds used even though an Unlimited account has no finite balance deduction. Failed requests follow the existing reservation/settlement rules, while provider usage and estimated cost can still be recorded when the provider already performed billable work before Blackcap encountered a downstream failure.

Estimated provider cost

Blackcap stores an Estimated Provider Cost for AI use cases when enough actual request data is available. The estimate uses the provider/model actually used, normalized provider token/media usage and request settings, plus the versioned provider-pricing snapshot in effect at the time. Historical usage therefore does not silently change when public provider pricing changes later. It is a planning/reconciliation estimate, not an invoice.

The Quality Profile editor also shows a forward-looking estimate before use: image profiles use size/quality pricing, Support Chat shows per-turn/conversation envelopes, and Social Recipe Extraction shows realistic per-import estimates (including transcription/media assumptions where applicable). AI Usage is preferable for completed work because it can use the actual request's recorded usage.

System Admins see Total estimated provider cost plus use-case summaries for 🖼️ Recipe Image Generation, 🎬 Social Recipe Extraction, and 🛟 Support Chat. These summaries follow the current report filters. Support Chat additionally reports session/effectiveness metrics such as sessions, AI requests, successes/failures, resolved without support, escalations, provider failures, abandoned sessions, average turns, average latency, AI Seeds used, and estimated provider cost.

Row actions and retained artifacts

Support Chat usage can show 🛟 View support chat while the retained transcript is available. Generated-image usage can show 🖼️ View generated image while the generated candidate file is retained. Unused/rejected image candidates normally follow the configured AI asset-retention period (initially seven days); accepted images move into the recipe image/cache workflow and are not removed by the unused-candidate purge. When an artifact/transcript has been purged, the usage accounting remains and the corresponding action is disabled instead of turning the missing artifact into an application error.

System Admin rows also provide 📋 Copy Provider Request ID when Blackcap received a provider request identifier.

Provider request identifiers, detailed provider token counts, and estimated provider cost are System Admin-only. The Provider Billing Reconciliation CSV is also System Admin-only and accepts the same report scope and cost-range filtering. Billing-context metadata is retained in the underlying usage record/export for reconciliation but is intentionally not repeated as a visible AI Usage table column on a single Blackcap instance.

Authenticated administration clients and the API Tester can use GET /api/admin/ai/usage for the same authorized report as JSON. The API Tester also exposes the read-only Support Chat transcript action and documents the generated-image binary action. See AI Administration, AI Seeds, and Usage Reporting for the permission matrix, API Tester entries, Database Admin resources, and regression coverage.