Skip to content

AI Creative Studio & Marketing Assets Admin Manual

Module: AI Creative Studio Operations & BYOK Administration (M2)

Product: ebosAi AMP
Classification: Internal — Confidential
Version: 2.2 (BYOK Multi-Model Integration & Plan Gating)
Last Updated: September 2026

[!TIP] User Manual Reference:
For complete instructions on creative prompt engineering, tone of voice customization, storyboard generation, and marketing copy formats, refer to the AI Creative Studio User Manual (user-manual/AI_Creative_Studio_User_Manual.md).

1. Overview for Administrators

The AI Creative Studio at /admin/ai-studio is the company's central AI creative generation engine. As a Company Administrator (admin role) or Manager (manager role), you are responsible for: 1. Configuring Bring-Your-Own-Key (BYOK) Credentials: Connecting tenant-owned LLM API keys (OpenAI, DeepSeek, Anthropic, Gemini, OpenRouter, or custom endpoints). 2. Managing Role-Based Access Control (RBAC): Granting or revoking granular menu permissions for internal staff users. 3. Overseeing Subscription Plan Limits: Monitoring R2 asset quotas and plan tier gating. 4. Publishing to Partner Portal: Governing marketing collateral saved into Cloudflare R2 and published to /partners/assets.

flowchart TD
    A["Admin Configures BYOK Keys (/admin/ai-studio)"] --> B["AES-256-GCM Encryption in PostgreSQL (mh2603.tenant_ai_configs)"]
    B --> C["RBAC & Plan Gate Validation (require_module('ai-studio'))"]
    C --> D["Marketing Team Generates Collateral (User Guide Workflows)"]
    D --> E["1-Click Persistence: Cloudflare R2 + mh2603.marketing_assets"]
    E --> F["Admin Asset Registry (/admin/assets)"]
    F --> G["Published to Partner Portal (/partners/assets)"]
    G --> H["Partners Download via 15-Minute Secure Presigned URLs"]

2. Role-Based Access Control (RBAC) & Governance

The platform enforces strict role boundaries for the AI Studio:

Role Code Access to /admin/ai-studio Access to /admin/assets Key Management Permission
admin (Company Admin) Full Access Full Access Can connect, update, test, and revoke BYOK provider keys.
manager (Marketing Manager) Full Access Full Access Can generate creatives and save to R2; key changes logged to audit.
accountant (Staff Portal) Restricted (403) Restricted (403) No access. Staff portal is limited to commission verification.
user (Partner / Influencer) Restricted (403) Restricted (403) No access. Partners access finished collateral at /partners/assets.

Granular Level-1 & Level-2 Menu Permissions

Admins can grant or revoke AI Studio access for specific internal users under Internal Users (/admin/users): - Permission Key: ai-studio (/admin/ai-studio) under the "Marketing & Links" category. - When toggled off for a user, the AI Studio menu is suppressed from their sidebar, and API requests to /api/v1/admin/assets/ai/* return HTTP 403 Forbidden.

3. Subscription Plan Gating & Quotas

Access to the AI Studio is gated at both the frontend routing proxy and backend dependency layer:

Feature Dimension Starter (plan_1) Professional (plan_2) Enterprise (plan_3)
Module Entitlement (ai-studio) Disabled Enabled Enabled
Sidebar Route (/admin/ai-studio) Hidden / Gated Active Active
Supported Providers — OpenAI, DeepSeek, Anthropic, Gemini, OpenRouter All Providers + Custom LLM Endpoints
Max Marketing Assets in R2 10 Assets 100 Assets Unlimited Assets
Backend Dependency Enforcement HTTP 403 (Upgrade Plan) HTTP 200 HTTP 200

Backend Plan Gate Enforcement:

All AI Studio router endpoints in backend/app/api/v1/assets.py enforce: 

dependencies=[Depends(require_module("ai-studio"))]
If a tenant's subscription plan is downgraded to Starter, all AI generation and configuration endpoints are automatically locked.

4. BYOK Security & Key Management

4.1 Encryption Architecture

  • Zero Exposure: Provider API keys are never returned in plaintext in API responses, logs, or frontend state.
  • Encryption at Rest: Keys are encrypted using AES-256-GCM using the server's FIELD_ENCRYPTION_KEY before insertion into the mh2603.tenant_ai_configs table.
  • Frontend Display: The API returns only a masked preview string (e.g., sk-...9f2c) and a boolean has_api_key: true.

4.2 Step-by-Step Provider Setup

  1. Log in with admin credentials and navigate to /admin/ai-studio.
  2. Click Configure Provider & Keys in the upper-right corner.
  3. Select your organization's AI provider:
  4. OpenAI: Requires standard sk-... API key with model permissions (gpt-4o, dall-e-3).
  5. DeepSeek: Cost-effective high-performance reasoning (deepseek-chat, deepseek-reasoner).
  6. Anthropic: Claude 3.5 Sonnet / Haiku keys.
  7. Google Gemini: Gemini API key from Google AI Studio.
  8. OpenRouter: Universal key supporting open-weight models (Llama 3.3, Mistral, Qwen).
  9. Custom / Self-Hosted: Custom endpoint URL (e.g., https://llm.internal.company.com/v1) for private vLLM, Groq, or Ollama deployments.
  10. Click Save Configuration. The backend tests the connection and establishes the active provider.

5. Cloudflare R2 Storage & Asset Distribution

When marketing teams click Save to Marketing Assets in the AI Studio: 1. The backend (POST /api/v1/admin/assets/ai/save) generates the production asset file (SVG, PNG, or Markdown). 2. The file is streamed to the tenant's Cloudflare R2 bucket (CLOUDFLARE_R2_BUCKET). 3. An asset record is inserted into mh2603.marketing_assets with category tagging (Images & Banners, Videos & Reels, Social Copy & Scripts). 4. The asset becomes immediately visible in: - Admin Asset Library (/admin/assets): Admins can monitor download counts, preview files, or delete outdated collateral. - Partner Self-Service Portal (/partners/assets): Partners can view collateral and generate 15-minute presigned download URLs (GET /api/v1/portal/assets/{id}/download).

6. Administrative API Reference

All routes require amp_admin_token authentication with admin or manager role and ai-studio plan entitlement:

Method Endpoint Plan Gate Description
GET /api/v1/admin/assets/ai/config Pro / Ent Retrieve tenant BYOK provider, model, and active status.
POST /api/v1/admin/assets/ai/config Pro / Ent Save or update BYOK provider credentials.
POST /api/v1/admin/assets/ai/generate Pro / Ent Generate marketing copy, graphics, or video storyboards.
POST /api/v1/admin/assets/ai/save Pro / Ent Save generated creative into Cloudflare R2 and asset registry.
GET /api/v1/admin/assets All Plans List all marketing assets with category filtering.
DELETE /api/v1/admin/assets/{id} All Plans Soft-delete an asset from the library.
GET /api/v1/admin/assets/{id}/download All Plans Redirect to 15-minute presigned Cloudflare R2 download URL.