Loading
These docs are evolving. Playloop is in active development ahead of launch, so APIs and details may change as we polish.
Everything on the Settings → AI provider tab, pick a provider, paste your key, choose a model from a live catalog, set a monthly spend ceiling, and route Whisper transcription independently if you want to split cost-tracking.
Playloop runs structured-output AI calls against your playtest data (session insights, tester rollups, build summaries, fix suggestions, embeddings, transcription). Every one of those calls reads from the same settings surface, provider, model, BYOK key, monthly cap, transcription override. This page is the contract for what each of those controls does.
Pick one. Each provider radio is disabled until that provider's key is configured (or, for OpenAI on a managed-AI plan — Indie / Studio — a platform-managed key is available).
Independent per-provider key fields. AES-256-GCM storage, decrypted only at the moment of an AI call. Save + clear are step-up gated.
Bounds how much Playloop will spend on your BYO key in one calendar month. New calls pause at the ceiling and resume on the 1st at 00:00 UTC.
The picker has three provider radios across the top and a model dropdown beneath. Provider switches auto-save and clear the model override back to Auto; model switches auto-save the override.
Each provider radio is enabled only when that provider's key is configured , paste a key below and the radio lights up. During the beta, the OpenAI radio lights up the same way as the other two: only when a BYO key is pasted. When the Indie and Studio plans open, the platform-managed OpenAI key fallback will light the OpenAI radio without a pasted key.
The first option is always Auto (default for <Provider>). Picking Auto clears the model override and the SDK reaches for the safest default:
const DEFAULT_MODELS = { openai: 'openai/gpt-5-mini', anthropic: 'anthropic/claude-sonnet-4.6', google: 'google/gemini-2.5-flash',}Below Auto, the dropdown lists every model the catalog filter accepts. When a BYO key is configured for the active provider, that list is pulled live from the provider's /v1/models endpoint and cached server-side for 24 hours. Without a key (or when the provider is unreachable) it falls back to the hardcoded suggested list:
The model dropdown is for picking a structured-output chat model · Playloop's pipelines parse every AI response against a Zod schema (insight types, sentiment, severity, confidence, citations). A model that can't reliably emit JSON conforming to that shape is worse than no model at all: it'll burn the call and lose the result.
That's why each provider's catalog goes through a denylist before it reaches your dropdown.
vision, audio, realtime, search, image, tts). These models speak different output shapes than the structured chat completions pipeline expects.gpt-4o-transcribe, gpt-4o-mini-transcribe), speech-to-text only, won't return structured chat output. Surfaced in the separate transcription picker, not here.The settings tab has independent paste fields for each provider. You can save one, all three, any combination, they don't depend on each other.
# OpenAIsk-…sk-proj-… # Anthropicsk-ant-… # Google Gemini (from AI Studio)AIza…sk-…7f2a) that the settings UI reads for display.…7f2a) so you can reconstruct "who changed this and when" from Settings → Security.The cap is a user-set ceiling on how much Playloop will spend on your BYO key per calendar month (UTC). It protects you from runaway usage , a heavy week of analyses can't surprise your provider bill. It does not protect you from Playloop bugs (Playloop's own cost discipline is the per-call + daily caps below).
00:00 UTC on the 1st.status="failed"with a scary "cap reached" banner. The right way to pause BYOK is to remove the limit (then re-add it later) or clear the BYO key; both are one click in Settings → AI.Audio + video uploads (the /sessions/new path) run through OpenAI's Whisper before the analyzer sees them. Anthropic and Gemini don't host an equivalent endpoint, so the picker is OpenAI-only, regardless of which provider you chose for the chat analyzer.
OpenAI legacy. Stable, broad language support. Default when you haven't picked anything else.
Newer + ~50% cheaper than whisper-1. Good first move if cost is your concern.
The monthly BYOK cap protects your provider bill from a run of legitimate analyses. The rails below are Playloop's own discipline, they bound the platform managed key and the per-call budget so a single bad upload can't blow past sensible limits.
Managed Whisper rejects single files over 60 minutes with an "audio too long" reason. Checked pre-flight when a duration hint is available, post-flight using the duration the model reports back. Keeps a 6-hour recording from costing ~$2.16 on a single call.
The transcribe layer also enforces a 150 MB hard ceiling (≈ 60 min of 320 kbps stereo), files larger than that reject on sight without reading the bytes. Audio files upload directly, up to 500 MB, but anything over 150 MB won’t transcribe, so 150 MB is the effective limit when a transcript is what you’re after.
Managed Whisper sums each user's last 24 hours of audio seconds and caps total spend at 8 hours / day. Hitting the cap fails the session with a specific reason code ("daily audio cap reached") so the user knows what hit.
BYOK bypasses these caps. When the call uses your own OpenAI key, neither the per-call duration cap nor the daily minute cap fire, the Whisper invoice lands on your account, so the bounds that matter are your monthly BYOK cap and your OpenAI organisation's own limits.
Paste a key, pick a model, set a monthly cap. Two minutes end-to-end.
Your model picks the engine; your per-game AI prompt picks the lens. Genre-specific examples + common mistakes.
Sessions → rollups → digest → the AI summary, plus every per-game tuning knob between. The consumer of the provider config above.
Step-up reverification gates the BYOK key and budget saves; /docs/notifications has the full audit-kind list (including the BYOK rows).
Three-model picker (whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe) and an optional Whisper-specific BYO key so you can split audio spending from chat spending.
const SUGGESTED_MODELS = { openai: ['openai/gpt-5-mini', 'openai/gpt-5', 'openai/gpt-5-nano'], anthropic: ['anthropic/claude-sonnet-4.6', 'anthropic/claude-opus-4.7', 'anthropic/claude-haiku-4.5'], google: ['google/gemini-2.5-flash', 'google/gemini-2.5-pro', 'google/gemini-2.0-flash'],}A small badge next to the dropdown reads either live (the list came from the provider just now) or suggested (the fallback list is rendering, paste a key for that provider to flip it to live). Deprecated models drop off automatically the moment the provider retires them, and new models appear without a Playloop redeploy.
Models sort with the flagship of each family at the top, leading-numeric descending (gpt-5 beats gpt-4), then a tier-weight tiebreaker so the bare flagship outranks size-suffixed siblings:
gpt-5) > mini (gpt-5-mini) > nano (gpt-5-nano).chatgpt-4o-latest), not API-stable.-0613, -1106-preview, -2026-04-08). The canonical bare form (gpt-4-turbo) survives and gets picked automatically by the provider.-YYYYMMDD or -YYYY-MM-DD suffixes. Same reason as OpenAI: the bare canonical form is what surfaces.-0827, -001, -002, -YYYY-MM-DD).generateContent, embedding + caching-only models are filtered upstream.When you open the model dropdown, Playloop calls the provider's /v1/models endpoint over HTTPS using your stored BYO key, applies the denylists above, sorts the result, and returns the filtered list to the picker.
The denylist is conservative on purpose. If a provider ships a new family that the current filter doesn't recognise, drop us a line, contact link in the docs FAQ and we'll patch the allowlist. The fallback list also lives in source so the dropdown is never empty.
Save + clear on every BYO key field, and any change to the monthly cap below, opens Playloop's step-up modal before the request lands. A stolen session can't silently swap an attacker key in, can't lift your cap, can't exfiltrate the encrypted key. The modal flow is documented in full on the account-security page → Step-up reverification.
Every AI call Playloop makes with your BYO key is billed to your provider account. Playloop never sees your usage or invoices on the provider side. Before wiring a BYO key into a busy playtest, set a monthly spending cap with your provider (OpenAI · Anthropic · Google AI Studio) and run a handful of small playtest sessions first to gauge typical token cost for your game. When you exceed your tier's managed-AI quota, new sessions are marked failed with reason managed_ai_quota_exceeded until next month — add a BYO key to keep analyzing without interruption.
When a BYO key is configured for the active provider, all AI calls for your workspace route through it, your provider, your bill. When no BYO key is configured for the active provider:
status="failed". Add a BYO key any time to upgrade future runs to AI narratives.What you get without a BYO key. Every uploaded session is summarised deterministically from its event transcript:
complete, defeat, finish, unlock, win.die, death, crash, fail, quit, abandon, rage.What you don't get without AI: friction-cluster narratives, qualitative quote extraction, sentiment classification beyond the event-name heuristic, and the long-form build-summary prose. Insight rows produced by this path are tagged deterministic and no-ai so the UI can badge them.
used < cap: call proceeds, the cost is logged, the meter ticks up.used ≥ cap: the call is refused. The session that triggered it surfaces a clear "limit reached" error in the UI instead of a generic 500. Other workspace activity is unaffected.00:00 UTC the month-to-date sum returns to $0 and BYOK calls run again. You can also raise the cap (or remove it) at any time to unblock immediately.Changing the monthly cap is step-up gated · Playloop forces fresh MFA before any cap change lands. Without that gate, a stolen session could silently lift your cap and start draining the BYO key you already pasted.
Every cap change is audit-logged with the prior + new values (in cents), so the audit trail reads "$25 → $50", not just "$50".
The cap is user-managed, not mandatory. Hit Remove limiton the settings tab and you accept full responsibility for BYOK spend · Playloop stops enforcing a ceiling and BYOK calls run regardless of usage. Useful if you'd rather rely on your provider's own dashboard budget alerts.
Newer + higher fidelity on noisy audio. Same price as legacy; worth the swap if your tester recordings are rough.
The dropdown autosaves on change. An unknown value falls back to whisper-1instead of failing the OpenAI call, so a misconfigured upstream can't make us lose audio.
A separate paste field for an OpenAI key that's used for transcription only. Useful for:
When the Whisper key is unset (the common case), Playloop falls back through this chain for transcription:
The Whisper key save + clear go through the same step-up flow as the other BYO keys, fresh MFA required before the change lands. Audit log entries land with the same masked-tail fingerprint format the chat keys use, tagged for the Whisper provider so the trail is unambiguous.