🤖 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 creates provider and usage records but does not debit a finite balance.
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.
- Create or edit a manual recipe and save enough information to identify the dish: a title plus a description or ingredients.
- Select Generate Image with AI. On a new manual recipe, use Save & Generate Image.
- 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.
- Choose Organization AI Seeds or My AI Seeds.
- Optionally add image notes such as composition, serving style, or camera angle.
- Submit the job. The dialog shows honest stages rather than invented percentages.
- Return later if needed. Queued and completed candidates are durable across navigation and application restarts.
- Review the generated image beside the existing recipe image, when present.
- 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. Filters, server-side paging, summary totals, sticky column headers, contextual horizontal scrolling, and anchored paging retain the selected authorization scope. Provider request identifiers and provider input/output/image token counts are System Admin-only. The Provider Billing Reconciliation CSV is also System Admin-only.
Authenticated administration clients and the API Tester can use GET /api/admin/ai/usage for the same authorized report as JSON. See AI Administration, AI Seeds, and Usage Reporting for the permission matrix, API Tester entries, Database Admin resources, and regression coverage.