# AI Settings

RankWiz uses OpenAI to generate content rewrite drafts. You provide your own API key (BYOK) and can customize AI behavior per site.

## OpenAI API Key

### Adding Your Key

1. Go to **Settings > AI** (from the user menu)
2. Enter your OpenAI API key (starts with `sk-`)
3. Click **Save**

Your key is encrypted at rest and never shared.

### Validating Your Key

After saving, click **Test Key** to verify it works. Validation makes a small test request to the OpenAI API.

### Validation Statuses

| Status | Meaning | Action |
|--------|---------|--------|
| **Valid** | Key is working correctly | Ready to generate drafts |
| **Invalid** | Key was rejected by OpenAI | Check the key, generate a new one if needed |
| **Quota exceeded** | Your OpenAI billing/quota is exhausted | Add credits at [platform.openai.com](https://platform.openai.com) |
| **Rate limited** | Too many requests to OpenAI | Wait a few minutes and try again |
| **Network error** | Temporary connectivity issue | Try again shortly |

### Updating Your Key

Enter a new key in the same field and save. The old key is replaced.

### Removing Your Key

Click **Remove Key** to delete your API key. This disables all AI features until a new key is added.

## Per-Site AI Settings

Each site can have its own AI configuration. Go to your site's **Settings > AI** page (from the site navigation).

### Model

Choose which OpenAI model to use for content generation:

| Model | Trade-off |
|-------|-----------|
| **gpt-4o-mini** (default) | Fastest, lowest cost |
| **gpt-4o** | More capable, higher cost |
| **gpt-4-turbo** | Highest capability, largest context |

### Temperature

Controls how creative vs. focused the output is.

- **0.0** — very focused, deterministic output
- **0.3** (default) — slightly creative, generally consistent
- **1.2** — highly creative, more varied output

Lower temperatures work well for factual, technical content. Higher temperatures suit creative or marketing content.

### Top P

Controls output diversity via nucleus sampling.

- **1.0** (default) — considers all token options
- Lower values — restricts to more likely tokens

Generally, adjust either temperature or top P, not both.

### Max Output Tokens

The maximum length of generated content, in tokens (roughly 0.75 words per token).

- **Default:** 1,200 tokens (~900 words)
- **Range:** 200 - 4,000 tokens
- Higher values allow longer rewrites but cost more

### Custom Instructions

Add site-specific guidance for the AI. Examples:

- "Write in a professional, technical tone"
- "Target audience is small business owners"
- "Always include the primary keyword naturally in the first paragraph"
- "Keep paragraphs short (2-3 sentences)"

**Maximum:** 2,000 characters.

Toggle custom instructions on/off without deleting them.

### Reset to Defaults

Click **Reset to Defaults** to revert all per-site settings back to the global defaults.