BYOK for AI Image and Video in Workflow Runs

Bring your own keys (BYOK) lets teams route workflow blocks through their Kling, Gemini, xAI, or other supported accounts while Wavemaker still provides compilation, moderation, memoization, and Hub distribution. You pay providers directly; Wavemaker bills a platform fee on BYOK nodes (20% of the platform-key price, minimum one credit). Estimates on /workflow-api separate engine lines from BYOK fees so finance can reconcile. Product setup: /product/byok; mechanics below.

When BYOK wins

Scenario	Why BYOK
Existing enterprise contracts	Commitments with Google, BytePlus, xAI
Regional data routing	Keys in your cloud boundary
Burst beyond platform pools	Your provider rate limits, not shared queues
Cost accounting	Provider invoices match internal chargeback

When you do not have negotiated rates, platform keys stay simpler — one credit ledger.

How blocks resolve credentials

Workflow blocks declare capabilities (image gen, video gen, TTS). At compile time, bindings pin model assets and optional BYOK provider ids. At run time:

1. Runner resolves org BYOK vault entry for the capability.
2. If present and block allows BYOK, adapter calls your API.
3. Platform fee line attaches to the node; provider usage is yours.

Keys never appear in logs, MCP tool results, or Hub listings. Decrypt happens in-block only (workflows overview).

Estimates and slug runs

curl -X POST https://api.wavemaker.io/api/v1/w/my-slug/estimate \
  -H "Authorization: Bearer mcp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"prompt":"…"}}'

Response itemizes:

• Generation credits (platform path)
• BYOK platform fees per node using your keys
• Creator premium on foreign runs
• Memo hits zero out repeated node charges (Memoized workflow runs)

Show end users the total held credits before submit — same envelope as execution.

MCP and agents

list_byok_providers returns names and status only — never secrets (Natural language workflow copilot). Agents should call estimate_workflow before run_hub_workflow when BYOK nodes exist. Dynamic tools inherit the same economics (Dynamic MCP tools).

Memoization and BYOK together

Memo keys hash outputs and params, not who paid the provider invoice. Toggle BYOK mid-project without busting memo for unchanged upstream scrape blocks — but change prompts and you should expect new charges.

Marketplace royalties

Open Hub workflows charge 10% royalty on settled platform credits from foreign runs. BYOK fee lines participate in platform share calculations where documented — creators still earn when platform fees apply. Detail: AI workflow marketplace economics.

Security checklist

• Rotate keys in org settings; bindings reference vault ids, not raw strings.
• Never paste keys into WorkflowSpec JSON or chat prompts.
• Use webhooks + metadata for run correlation (Idempotency and webhooks).

Binding overrides on run submit

Advanced runs pass binding_overrides on REST (and MCP equivalents where exposed) to swap LoRA or voice bindings per run without republishing — BYOK provider selection may participate when block manifests allow. Overrides still respect org vault tenancy; invalid overrides fail validation like bad inputs.

Creator vs runner BYOK

Creators may author graphs assuming platform keys; runners with BYOK vault entries pay provider invoices plus platform fees on BYOK nodes. Estimates on foreign premium workflows show both creator premium and BYOK lines — quote UI on /w/{slug} separates them for Hub visitors.

Compliance and key storage

BYOK vault entries are org-scoped secrets — not exportable via API. Audit access via admin logs where enabled. Rotating a key does not invalidate in-flight runs using the prior secret snapshot for already-started nodes; new nodes pick up rotation.

When not to use BYOK

• Demos and prototypes — platform keys reduce setup friction.
• Agents that cannot keep vault entries out of prompts — use platform billing until operators configure /product/byok.
• Blocks without BYOK-capable adapters — compile shows platform-only binding.

Mixing platform and BYOK nodes in one graph

A ten-block workflow might BYOK only the hero video step while images use platform Gemini routing. Estimates itemize per node — finance can allocate cost centers. Memoization still applies on unchanged upstream platform nodes when you BYOK only downstream video.

Claim-safe scope

BYOK covers supported provider adapters in the kernel manifest — not arbitrary HTTP endpoints. Unsupported models remain platform-key or block until mounted. Training Studio runnable hosts (krea2 / ltx / wan / etc.) follow Training Studio — Flux/SDXL library imports may be library-only until a host mounts.

Estimate / quote before a credit hold on a slug run.

Open royalty and BYOK together

Foreign runs on Open Hub workflows may generate royalty lines on platform credit share while BYOK nodes still charge platform fee minimums. Finance should map estimate line items to GL codes — not collapse into single “AI spend.”

Org admin workflow

BYOK setup requires org admin — agents cannot set vault entries via MCP without appropriate tools. Direct operators to /product/byok before expecting BYOK estimates to show non-zero fee lines.

Rollout checklist for platform teams

1. Enable BYOK in org settings and verify provider test calls from admin UI.
2. Update workflow bindings to allow BYOK on expensive video blocks only.
3. Run parallel estimate: platform keys vs BYOK — compare settled runs on identical inputs (memo may align).
4. Document provider rate limits for internal SRE — Wavemaker concurrency gates still apply at block level.
5. Train finance on estimate line item codes: generation, byok_fee, premium, memo_hit.

Rollback: switch bindings to platform keys — next run uses platform billing without deleting vault entries.

Provider outage behavior

When your BYOK provider returns rate limits or hard failures, blocks fail in-band with structured errors on the run node — Wavemaker does not silently fall back to platform keys unless the workflow author configured explicit fallback blocks (rare). Operators should monitor provider status pages and pause cron submits during outages to avoid burning platform fees on retries without memo benefit.

Auditing BYOK spend end to end

Finance reconciliation spans three ledgers: Wavemaker credits (platform fees + any platform-key nodes), provider invoices (BYOK API usage), and creator premiums on foreign Hub runs. Export run node detail via GET /kernel-runs/:id to attribute each line item. Memo hits appear as zero-charge nodes — do not double-count provider usage when memo skipped re-execution.

Key rotation without republishing workflows

Rotating BYOK vault credentials does not require republishing workflows — bindings reference vault ids. Schedule rotation during low traffic; monitor first runs after rotation for auth errors on BYOK nodes. Platform-key nodes continue unaffected. Document which blocks are BYOK-bound in internal runbooks so on-call knows which provider dashboard to check.

BYOK is optional per org — the default path remains platform keys with a single Wavemaker credit ledger. Choose BYOK when provider contracts, data residency, or burst capacity justify operational overhead. Every estimate still shows the full picture so product managers can compare without running two production pipelines.

Training blocks and voice blocks may use BYOK adapters independently within one workflow — mixed graphs are normal. Read each block’s manifest in compile output to see which nodes support BYOK before promising finance a single provider invoice covers the entire run.

Start BYOK rollout on one low-traffic slug run before enabling vault bindings on hero video blocks company-wide.

Where to go next

• /product/byok — setup and supported providers
• /workflow-api — slug runs with BYOK-aware quotes
• OpenAPI for generative media — fee fields in responses
• Workflow platform field guide — flags and economics