aethex-studio/CLAUDE_API_SETUP.md

🤖 Claude API Setup Guide

This guide will help you set up the Claude API for AeThex Studio's cross-platform code translation feature - the core competitive differentiator that enables translating code between Roblox, UEFN, Spatial, and Core.

---

🎯 Why You Need This

Without a Claude API key:

• ✅ All features work (platform switching, templates, editor)
• ❌ Translation shows mock responses (not real AI translation)

With a Claude API key:

• ✅ Real AI-powered translation Roblox ↔ UEFN ↔ Spatial ↔ Core
• ✅ Intelligent code conversion with explanations
• ✅ Platform-specific best practices applied
• ✅ Your #1 competitive advantage unlocked 🔥

---

📋 Prerequisites

• An Anthropic account
• Credit card for API billing (Claude API is pay-as-you-go)
• Estimated cost: $0.001 - $0.01 per translation (very affordable)

---

🔧 Step-by-Step Setup

Step 1: Get Your Claude API Key

1. Visit Anthropic Console: https://console.anthropic.com/
2. Create Account (if you don't have one)
3. Navigate to API Keys: https://console.anthropic.com/settings/keys
4. Click "Create Key"
5. Copy your API key (starts with sk-ant-api03-...)

⚠️ Important: Save this key securely! You won't be able to see it again.

Step 2: Configure Environment Variables

Option A: Local Development (.env.local)

1. Create a file named .env.local in the project root:

# From project root
touch .env.local

2. Add your API key:

# .env.local
VITE_CLAUDE_API_KEY=sk-ant-api03-your-actual-key-here

3. Restart your dev server:

npm run dev

Option B: Production Deployment (Vercel/Netlify)

For Vercel:

1. Go to your project settings
2. Navigate to "Environment Variables"
3. Add:
   • Key: VITE_CLAUDE_API_KEY
   • Value: sk-ant-api03-your-actual-key-here
4. Redeploy your app

For Netlify:

1. Site Settings → Environment Variables
2. Add:
   • Key: VITE_CLAUDE_API_KEY
   • Value: sk-ant-api03-your-actual-key-here
3. Trigger new deploy

---

✅ Verify Setup

Test the Translation Feature

1. Open AeThex Studio in your browser
2. Switch Platform to Roblox (if not already)
3. Select a Template (e.g., "Hello World")
4. Click "Translate" button in toolbar
5. Choose Target Platform (e.g., UEFN)
6. Click "Translate"

If configured correctly:

• Loading spinner shows
• Real Verse code appears on the right side
• Explanation section shows key differences
• Warnings section (if applicable)

If NOT configured:

• Mock translation appears with comment: -- TODO: Replace with actual uefn implementation
• Warning: "Mock translation active - integrate Claude API for production"

---

💰 Cost Estimation

Claude 3.5 Sonnet Pricing (as of Jan 2025):

• Input: $3 per million tokens
• Output: $15 per million tokens

Typical Translation Costs:

• Small script (50 lines): ~$0.001
• Medium script (200 lines): ~$0.005
• Large script (500 lines): ~$0.015

Example monthly usage:

• 100 translations/day = $0.50/day = **$15/month**
• 500 translations/day = $2.50/day = **$75/month**

💡 Tip: Start with a $10 credit to test. Monitor usage in Anthropic Console.

---

🔒 Security Best Practices

✅ DO:

• ✅ Store API keys in .env.local (never in code)
• ✅ Add .env.local to .gitignore
• ✅ Use environment variables in production
• ✅ Rotate keys periodically
• ✅ Set spending limits in Anthropic Console

❌ DON'T:

• ❌ Commit API keys to Git
• ❌ Share keys publicly
• ❌ Hardcode keys in source code
• ❌ Use same key for dev and prod

---

🐛 Troubleshooting

Issue: "API key not configured" warning

Solution:

• Verify .env.local exists and has correct key
• Restart dev server (npm run dev)
• Check console for errors

Issue: "API request failed: 401"

Solution:

• Your API key is invalid or expired
• Generate new key in Anthropic Console
• Update .env.local

Issue: "API request failed: 429"

Solution:

• Rate limit exceeded
• Check usage in Anthropic Console
• Add billing method if needed
• Implement client-side rate limiting (future enhancement)

Issue: "API request failed: 400"

Solution:

• Invalid request format (shouldn't happen)
• Check browser console for details
• Report bug on GitHub

Issue: Translation returns mock data despite having API key

Solution:

1. Open browser console (F12)
2. Look for: "Claude API key not configured, using mock translation"
3. Check environment variable name: Must be VITE_CLAUDE_API_KEY
4. Restart dev server after adding key

---

🧪 Advanced Configuration

Custom Model Selection

Use a different Claude model (optional):

# .env.local
VITE_CLAUDE_API_KEY=sk-ant-api03-...
VITE_CLAUDE_MODEL=claude-3-opus-20240229

Available models:

• claude-3-5-sonnet-20241022 (default, recommended)
• claude-3-opus-20240229 (most capable, slower, expensive)
• claude-3-haiku-20240307 (fastest, cheaper, less accurate)

Rate Limiting (Future)

To implement client-side rate limiting:

// src/lib/translation-engine.ts
const MAX_TRANSLATIONS_PER_MINUTE = 10;

---

📊 Monitoring Usage

Anthropic Console

1. Visit: https://console.anthropic.com/settings/usage
2. View:
   • Total requests
   • Tokens consumed
   • Cost breakdown
   • Daily/monthly trends

Set Spending Limits

1. Console → Settings → Billing
2. Set monthly limit (e.g., $50)
3. Get email alerts at 50%, 75%, 90%

---

🚀 Next Steps

Once you have the API key configured:

1. Test All Translation Pairs:

   • Roblox → UEFN
   • UEFN → Roblox
   • Roblox → Spatial (when templates added)

2. Share with Team:

   • Each developer needs their own API key
   • Or use shared key in production only

3. Monitor Quality:

   • Review translations for accuracy
   • Report issues on GitHub
   • Suggest prompt improvements

4. Optimize Costs:

   • Cache common translations (future)
   • Batch similar requests (future)
   • Use cheaper model for simple code (future)

---

💡 Tips for Best Results

Writing Translatable Code

Claude works best with:

• ✅ Well-commented code
• ✅ Clear variable names
• ✅ Standard patterns (no weird hacks)
• ✅ Short to medium scripts (< 500 lines)

Using the Context Field

When translating complex code, add context:

Context: "This is a player spawn system that needs to work with UEFN's agent system"

This helps Claude understand the purpose and translate more accurately.

---

🆘 Need Help?

• Documentation Issues: https://github.com/AeThex-LABS/aethex-studio/issues
• Anthropic Support: https://support.anthropic.com
• API Status: https://status.anthropic.com

---

📚 Additional Resources

• Anthropic API Documentation
• Claude Pricing
• API Best Practices
• Rate Limits

---

🎉 You're all set! Your cross-platform translation engine is now powered by Claude AI. Start translating code between platforms and unlock your competitive advantage!