# API Relay Options — Session Notes (2026-05-19)

## OpenRouter KYC Issue

- OpenRouter's Alipay payment may trigger KYC verification (address, Google association popup)
- KYC popup appears as a modal that auto-closes when clicking "秒退"
- **Workaround**: Try small amount ($5) via Alipay in incognito/private browsing mode
- If KYC persists, consider alternative relays
- **Email verification required**: OpenRouter may block payments if email is not verified. Check at openrouter.ai/settings → verify email → check inbox (including spam) for verification link

## Relay Evaluation Results (2026-05-19)

### PoloAPI (ai.poloapi.com) ❌ UNAVAILABLE
- Domestic CN API relay, supports 300+ models
- Claims 6-7% discount vs direct pricing
- Compatible with OpenAI API protocol
- **ISSUE**: Stopped individual user registration as of 2026-05-19 — only enterprise accounts

### OpenKey (openkey.cloud) ✅ WORKING
- Supports Alipay and USDT payment
- No region restrictions
- Compatible with OpenAI API protocol
- Supports GPT-4o, Claude Opus/Sonnet, Gemini, DeepSeek, Grok, Qwen, Doubao, Kimi
- Pay-per-use, 9-month credit validity
- Online customer service (12/24×7)
- **NOTE**: Homepage mentions "Poixe AI" new platform migration — monitor for changes
- Team: "牛爷爷团队" established 2022-12-11
- **Status**: ✅ Fully working as of 2026-05-19. gpt-4o-mini confirmed responding in Chinese.
- **Pitfall**: `api_key_env` doesn't reliably work for new providers — use `api_key` directly in config.yaml
- **Pitfall**: Must set `model.provider: openkey` (not `openrouter`) and `model.default: gpt-4o-mini` (no prefix)

### API2D (api2d.com) ⚠️ LESS IDEAL
- Compatible with OpenAI API protocol
- Pay-per-token, ~1.5x OpenAI official pricing (more expensive)
- Supports GPT, Claude, StableDiffusion, Tencent Cloud
- **ISSUE**: No clear Alipay support mentioned on website
- Price is higher than OpenAI official — not cost-effective

### CloseAI / 九九中转 — Could not find working website
- Domain closeai-ai.cn and closeai.chat both failed to resolve
- May have shut down or changed domain

## Recommended Alternatives (Domestic CN, Alipay-friendly)

| Relay | Alipay | Free Tier | Image Support | Notes |
|-------|--------|-----------|---------------|-------|
| DeepSeek | ✅ | ✅ | ❌ | Best Chinese, can't see images |
| 智谱 GLM | ✅ | ✅ | ✅ (GLM-4V) | Good all-rounder |
| 通义千问 | ✅ | ✅ | ✅ (Qwen-VL) | Alibaba ecosystem |
| OpenKey | ✅ | ❌ | Depends on model | Overseas team,华人市场,✅ 已验证可用 |

## Key Consideration for 张哥's Setup

**Critical requirement**: Image input support (看截图) — DeepSeek is OUT for this reason
**Best candidates**: 智谱 GLM or 通义千问 (both support vision + Alipay + free tier)
**Current status**: OpenKey configured and working. gpt-4o-mini supports image input.

## How to Switch API Relay in Hermes

### Correct Procedure (validated 2026-05-19):

1. Add API key to provider in `config.yaml`:
```yaml
providers:
  openkey:
    base_url: https://openkey.cloud/v1
    api_key: sk-xxx          # Direct key, NOT api_key_env
    api_mode: chat_completions
```

2. Update model section (all three fields must match):
```yaml
model:
  default: gpt-4o-mini        # Just model name, no prefix
  provider: openkey           # Must match provider name above
  base_url: https://openkey.cloud/v1
  api_mode: chat_completions
```

3. Restart gateway: `sudo systemctl restart hermes-gateway` (requires approval)

4. Verify:
```bash
sudo systemctl status hermes-gateway    # Should be active (running)
journalctl -u hermes-gateway --since "1 minute ago" --no-pager  # No errors
```

5. Test via curl:
```bash
curl -s https://openkey.cloud/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxx" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"max_tokens":50}'
```

### Common Mistakes:
- ❌ Using `api_key_env` instead of `api_key` → 401 Invalid Token (gateway caches old env)
- ❌ Setting `model.provider: openrouter` with openkey model → 400 invalid model ID
- ❌ Using `openkey/gpt-4o-mini` as model name → should be just `gpt-4o-mini`
- ❌ Forgetting to restart gateway after config changes

## Server Location Note

张哥 asked about migrating from overseas cloud server to domestic CN server. After discussion:
- **Decision**: Do NOT migrate. Current overseas server is the longest-running Hermes instance.
- Reasoning: Previous Hermes instances died due to config/model issues, not server location