Skip to main content

​
Overview

Knowledge Tooltip uses OpenAI’s GPT models to power advanced features like AI explanations and translations. You’ll need to provide your own OpenAI API key to use these features.

​
Features Requiring an API Key

AI Tab

Get simple explanations and ask questions about selected terms

Translate Tab

Translate text between English and Arabic using AI

​
Getting an OpenAI API Key

1

Create an OpenAI account

Visit platform.openai.com and sign up or log in
2

Navigate to API keys

Go to platform.openai.com/api-keys
3

Create a new secret key

Click “Create new secret key” and give it a descriptive name like “Knowledge Tooltip”
4

Copy your key

Copy the API key (starts with sk-) and store it securely. You won’t be able to view it again.
Never share your API key publicly. It provides access to your OpenAI account and you’ll be charged for any usage.

​
Adding Your API Key

1

Open the extension popup

Click the Knowledge Tooltip icon in your browser toolbar
2

Find the AI Features section

Scroll to the “AI Features (OpenAI)” section at the bottom
3

Enter your API key

Paste your OpenAI API key into the password field (starts with sk-)
4

Click Save

Click the “Save” button to store your key securely

​
How It Works

​
API Key Validation

The extension performs basic validation before saving: 
apiKeySaveBtn.addEventListener('click', async () => {
  const key = apiKeyInput.value.trim();
  
  if (!key) {
    apiKeyStatus.textContent = 'Please enter an API key';
    apiKeyStatus.className = 'api-key-status error';
    return;
  }
  
  if (!key.startsWith('sk-') || key.length < 20) {
    apiKeyStatus.textContent = 'Invalid key format (should start with sk-)';
    apiKeyStatus.className = 'api-key-status error';
    return;
  }
  
  await chrome.storage.local.set({ openaiKey: key });
  apiKeyInput.value = '';
  updateApiKeyUI(true);
});
The extension only checks the format (starts with sk- and is at least 20 characters). It doesn’t verify the key with OpenAI until you use an AI feature.

​
Secure Storage

Your API key is stored in chrome.storage.local, not chrome.storage.sync: 
// API keys are NEVER synced across devices
const keyResult = await chrome.storage.local.get(['openaiKey']);
const hasKey = !!keyResult.openaiKey;
This is critical for security:

chrome.storage.local

Stored only on this device. Never synced to the cloud or other browsers.

chrome.storage.sync

Used for preferences like language and toggle state. Safe to sync.

​
Storage Migration

Earlier versions stored the API key in sync storage. The extension automatically migrates to local storage: 
// One-time migration: move API key from sync to local storage
chrome.runtime.onInstalled.addListener(async () => {
  const sync = await chrome.storage.sync.get(['openaiKey']);
  if (sync.openaiKey) {
    await chrome.storage.local.set({ openaiKey: sync.openaiKey });
    await chrome.storage.sync.remove('openaiKey');
  }
});
If you used an older version of the extension, your API key was automatically moved to local storage for better security.

​
Using the API Key

When you use an AI feature, the background service worker retrieves the key: 
async function callOpenAI(messages, language, maxTokens = 500) {
  const result = await chrome.storage.local.get(['openaiKey']);
  const apiKey = result.openaiKey;
  
  if (!apiKey) {
    throw new Error('NO_API_KEY');
  }
  
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      model: 'gpt-5-nano',
      messages: messages,
      max_completion_tokens: maxTokens,
      reasoning_effort: 'minimal'
    })
  });
  
  // Handle errors...
}

​
Error Handling

The extension detects and reports specific API errors: 
if (!response.ok) {
  const status = response.status;
  
  if (status === 401) {
    throw new Error('INVALID_API_KEY');
  } else if (status === 429) {
    throw new Error('RATE_LIMITED');
  } else if (status === 402) {
    throw new Error('INSUFFICIENT_QUOTA');
  } else if (status === 400) {
    throw new Error(`INVALID_REQUEST: ${errorDetail}`);
  }
}
These errors are displayed to you in the UI:
  • INVALID_API_KEY: “Invalid API key. Please check your key in settings.”
  • RATE_LIMITED: “Too many requests. Please wait a moment.”
  • INSUFFICIENT_QUOTA: “Insufficient OpenAI quota. Please check your account.”

​
Removing Your API Key

To remove your stored API key:
1

Open the extension popup

Click the Knowledge Tooltip icon
2

Find the saved key indicator

You’ll see ”••••••••••••••••” indicating a key is saved
3

Click Remove

Click the “Remove” button next to the masked key
4

Confirm removal

The status will change to “No API key set”
The removal code: 
apiKeyRemoveBtn.addEventListener('click', async () => {
  await chrome.storage.local.remove('openaiKey');
  updateApiKeyUI(false);
});
Removing the API key does not affect your other settings (language preference, toggle state, etc.).

​
Model Configuration

The extension is configured to use gpt-5-nano with optimized settings: 
body: JSON.stringify({
  model: 'gpt-5-nano',
  messages: messages,
  max_completion_tokens: maxTokens, // Default: 500
  reasoning_effort: 'minimal'
})
  • Model: gpt-5-nano - Fast and cost-effective for simple explanations
  • Max tokens: 500 for most requests, 1000 for translations
  • Reasoning effort: Minimal - optimized for quick responses

​
API Usage Limits

To prevent excessive API usage, the extension enforces limits:

​
AI Chat Limits

const MAX_AI_EXCHANGES = 5;

if (aiExchangeCount >= MAX_AI_EXCHANGES) {
  // Hide input and show limit reached message
  return;
}
You can ask up to 5 questions per tooltip session. Close and reopen the tooltip to reset the counter.

​
Context Limits

// Limit to ~500 chars centered around the selection
if (text.length > 500) {
  const selText = selection.toString().trim();
  const idx = text.indexOf(selText);
  if (idx !== -1) {
    const start = Math.max(0, idx - 200);
    const end = Math.min(text.length, idx + selText.length + 200);
    text = text.substring(start, end);
  } else {
    text = text.substring(0, 500);
  }
}
Page context is limited to 500 characters to keep API costs low.

​
Pricing Information

Check OpenAI’s pricing page for current rates. The extension uses gpt-5-nano which is one of the most affordable models.
Typical usage:
  • Explain Simply: ~100-200 tokens per request
  • AI Questions: ~150-300 tokens per exchange
  • Translation: ~200-500 tokens per translation

​
Security Best Practices

Your API key grants access to your OpenAI account. Follow these security practices:
  1. Never share your key: Don’t paste it in emails, chat messages, or public forums
  2. Use browser profiles carefully: If you share a browser profile, others may access your key
  3. Rotate keys regularly: Create a new API key every few months and delete the old one
  4. Monitor usage: Check your OpenAI dashboard regularly for unexpected usage
  5. Set spending limits: Configure billing limits in your OpenAI account

​
Troubleshooting

The key was rejected during validation. Make sure it starts with sk- and is the complete key from OpenAI. Try copying it again.
Your key may have been revoked or deleted in the OpenAI dashboard. Generate a new key and update it in the extension.
You may be hitting OpenAI’s rate limits. Wait a few minutes before trying again, or upgrade your OpenAI plan.
Your OpenAI account has run out of credits. Add a payment method or increase your spending limit at platform.openai.com.

​
Privacy Considerations

When you use AI features, the following data is sent to OpenAI:
  • The selected text
  • Your question (if asking in AI chat)
  • Brief surrounding context from the page (~500 chars)
  • The Wikipedia summary (if available)
No other browsing data, history, or personal information is shared.

​
Checking If a Key Is Set

The extension checks for an API key before showing AI features: 
if (message.action === 'checkOpenAIKey') {
  chrome.storage.local.get(['openaiKey'], (result) => {
    sendResponse({ hasKey: !!result.openaiKey });
  });
  return true;
}
If no key is found, you’ll see a prompt to add one: 
function renderAINoKey(contentArea) {
  const text = document.createElement('p');
  text.textContent = currentLanguage === 'ar'
    ? 'أضف مفتاح OpenAI API في إعدادات الإضافة لاستخدام ميزات الذكاء الاصطناعي.'
    : 'Add your OpenAI API key in the extension settings to use AI features.';
  
  const hint = document.createElement('div');
  hint.textContent = currentLanguage === 'ar'
    ? 'انقر على أيقونة الإضافة → أدخل مفتاح API'
    : 'Click the extension icon → Enter your API key';
}

Build docs developers (and LLMs) love

Get started for freeTalk to us