AI Issues - Yapper Help

Yapper’s AI features — AI Transform and AI Q&A — require an AI provider and internet connection. If they’re not working, this guide will help you diagnose the problem.

AI Features Not Working

Check Basic Setup

First, verify AI is properly configured:

Open Settings → AI
Verify a Provider is selected
Check that your API Key is entered
Ensure a Model is selected
Test your internet connection

Test Your Configuration

Start a recording and say “Hey Yapper, what is two plus two?” If you get an answer in the floating panel, your AI is working correctly.

AI Transform Issues

Transform Not Activating

AI Transform activates when text is selected before recording. If it’s falling back to normal dictation:

Verify text is selected — Highlight text in the app before pressing the shortcut
Check Accessibility permission — Settings → Preferences → Permissions should show a green checkmark for Accessibility
Try a different app — Some apps don’t expose selected text to the Accessibility API
Restart Yapper — Quit and reopen if Accessibility was just granted

Text Not Being Replaced

If the AI generates a response but the original text isn’t replaced:

Check Accessibility permission is granted
Ensure the text field still has focus during processing
Don’t switch apps while the AI is working
Try a simpler app (like TextEdit) to verify it works

Poor Rewrite Quality

Be more specific — “Fix grammar” works better than “fix this”
Try a quality model — Claude Sonnet, GPT-5 Mini, or Gemini Pro
Simplify the instruction — One clear instruction works better than multiple
Check the language — Ensure your voice instruction is in a language your speech model supports

AI Q&A Issues

”Hey Yapper” Not Detected

The wake phrase uses fuzzy matching, but if it’s consistently missed:

Say it clearly — Pronounce “Hey Yapper” as two distinct words
Say it first — The wake phrase must come at the beginning of your recording
Check your language — Ensure your transcription language is set to the language you’re speaking
Speak naturally — Over-enunciation can cause the speech model to produce unexpected spellings

No Answer Appearing

If Q&A activates but no answer shows:

Check your internet connection
Verify your API key has available credits
Try a different AI provider or model
Check the provider’s status page for outages

API Key Issues

”Invalid API Key” Error

Regenerate the key — Go to your provider’s website and create a new key
Copy carefully — Make sure you copy the entire key with no extra spaces
Paste fresh — Clear the API key field completely, then paste
Save and test — Click Save, then try a recording

Where to Get API Keys

Provider	URL
Google (Gemini)	ai.google.dev
OpenAI	platform.openai.com/api-keys
Anthropic	console.anthropic.com
xAI	x.ai

Key Format

API keys typically look like:

OpenAI: sk-... (starts with sk-)
Anthropic: sk-ant-... (starts with sk-ant-)
Google: Alphanumeric string
xAI: Provider-specific format

Network Issues

No Internet Connection

AI features require internet to communicate with the AI provider.

Open a website to verify connectivity
Try again once connection is restored
Basic transcription still works offline

Firewall or VPN Blocking

Some networks block AI provider APIs:

Try disabling VPN temporarily
Try a different network (phone hotspot)
Check with your IT department if on a corporate network

Timeout Errors

Try again — might be a temporary server issue
Try a faster model (Nano, Haiku, Flash variants)
Check the provider’s status page for outages

Provider-Specific Issues

Rate Limiting

AI providers limit how many requests you can make.

Symptoms:

“Rate limited” error
AI works sometimes, fails other times

Solutions:

Wait a few minutes and try again
Upgrade your provider plan if you hit limits frequently
Consider a different provider

Insufficient Credits/Quota

Most providers charge for API usage.