# aiqianshu Bulk Registration — Full Pattern Reference

## Service Profile

- **URL**: https://aiqianshu.com
- **Type**: OpenAI-compatible API gateway (NewAPI v1.0.0-rc.11)
- **API format**: `https://aiqianshu.com/v1` (OpenAI-compatible)
- **Key format**: Two variants:
  - **Browser-created**: `sk-` prefix, ~55 chars (e.g., `[REDACTED-KEY]`)
  - **API-created**: No prefix, ~48 chars alphanumeric (e.g., `X5nJtYPUNfdqx5NYDeb2mKPgHoPa9NEolffR2ksdxr3x4ynu`)
  - Both work identically for API access

## Email Domain Whitelist

aiqianshu has admin-enabled email domain whitelist:

| Domain | Status | Error |
|--------|--------|-------|
| `gmail.com` | ✅ Allowed | — |
| `web-library.net` (mail.tm) | ❌ Blocked | "email domain name whitelist… your email address is not allowed" |

**Always use Gmail +aliasing for this service.**

## Registration Flow (Working)

**Step 1 (SEND CODE) is BROWSER-ONLY — no API endpoint exists.**

All tested API paths return 404 or validation errors:
- `POST /api/verification` → 404
- `POST /api/user/sendcode` → 404  
- `POST /api/user/register` (email-only) → "Password field required" (validates, doesn't send)

Only browser form click on "Отправить код" triggers the email. Hermes `browser_type` fills 4 fields, then `browser_click` sends.

```
1. BROWSER: fill sign-up form, click "Отправить код"  → sends 6-char code to email
2. IMAP: read code from [REDACTED-NAME]+aqXXXX@gmail.com    → extract from HTML <strong>
3. POST /api/user/register                              → {success:true}
4. POST /api/user/login                                 → get session cookie + user_id
5. POST /api/token/ (New-Api-User: <id> header)        → create API key
6. POST /api/token/batch/keys {"ids":[<tid>]}           → extract unmasked full key
```

### API Details

**Register:**
```bash
curl -X POST https://aiqianshu.com/api/user/register \
  -H "Content-Type: application/json" \
  -d '{"username":"goth_aq0011","email":"[REDACTED-NAME]+aq0011@gmail.com","password":"Goth@2026xX","verification_code":"8a9a6f","agreement":true}'
# → {"message":"","success":true}
```

**Login (get user_id from response):**
```bash
curl -X POST https://aiqianshu.com/api/user/login \
  -H "Content-Type: application/json" -c cookies.txt \
  -d '{"username":"[REDACTED-NAME]+aq0011@gmail.com","password":"Goth@2026xX"}'
# → {"data":{"id":202,...}}
```

**Create token (New-Api-User header = numeric user_id):**
```bash
curl -X POST https://aiqianshu.com/api/token/ \
  -b cookies.txt -H "New-Api-User: 202" -H "Content-Type: application/json" \
  -d '{"name":"goth_aq0011","unlimited_quota":true,"remain_quota":999999999}'
# → {"message":"","success":true}
```

**Extract full key:**
```bash
# First find token ID
curl -s https://aiqianshu.com/api/token/?status_only=true \
  -b cookies.txt -H "New-Api-User: 202"
# Then get unmasked key
curl -X POST https://aiqianshu.com/api/token/batch/keys \
  -b cookies.txt -H "New-Api-User: 202" -H "Content-Type: application/json" \
  -d '{"ids":[165]}'
# → {"data":{"keys":{"165":"X5nJtYPUNfdqx5NYDeb2mKPgHoPa9NEolffR2ksdxr3x4ynu"}}...}
```

## Code Format

aiqianshu verification codes are **6-char alphanumeric** (not hex, not digits):
- Examples: `059cef`, `4509dd`, `8a9a6f`, `adbd18`, `2ece9a`, `038c6c`, `af8789`, `b83765`, `353f0e`
- Pattern: `<strong[^>]*>\s*([a-zA-Z0-9]{4,8})\s*</strong>`
- Codes valid for 10 minutes

## Rate Limiting — CRITICAL

- **All POSTs** share ONE rate limit pool (browser + API combined)
- **Window**: ~2-3 POSTs total, then **5-15 minute cooldown**
- **SEND-CODE is EXEMPT** — browser can keep sending codes while registration is 429'd
- **Maximum throughput**: ~2 registrations per 15 minutes across ALL methods
- **429 response**: empty body, no JSON — handle with `try: r.json() except: ...` or check `r.status_code` first
- **Scaling**: For 50+ accounts, proxy rotation (different IPs) is mandatory. Without proxies: ~2 registrations per 15 min = ~6 hours for 50 accounts.
- **Steady approach**: 5-minute cron job that registers 1 account per tick, plus browser code-sending loop. Achieves 8-12 accounts/hour without proxy infrastructure.
- **Mitigation**: Send ALL codes via browser first (no limit), then register in slow batches

### Practical Limits (measured 2026-06-18)
```
Browser send-code:  unlimited (~1 per 5-8s safe)
API login:          ~2 per 10 min (shares POST pool)
API register:       ~2 per 10 min (shares POST pool)  
API create token:   ~2 per 10 min (shares POST pool)
API batch/keys:     not rate-limited (GET endpoint)
Browser register:   same pool as API (429 if API already hit limit)
```

**Key insight**: Send ALL codes via browser first (unstoppable), then _slowly_ process registrations via API with 5+ min delays between accounts. For 50 accounts: send 50 codes in ~10 min via browser, then register 2 every 15 min = ~6 hours. Or use proxies to parallelize.

## Gmail +aliasing Pattern

Format: `[REDACTED-NAME]+aq{index:04d}@gmail.com`
All deliver to `[REDACTED-NAME]@gmail.com`.

**IMAP search (Python):**
```python
m.search(None, f'(TO "{email_addr}")')  # full address with quotes
```

**Code extraction regex:**
```python
codes = re.findall(r'<strong[^>]*>\s*([a-zA-Z0-9]{4,8})\s*</strong>', body)
```

## Bulk Script

Location: `C:/Users/User/AppData/Local/hermes/scripts/aiqianshu_bulk.py`
Keys file: `C:/Users/User/aiqianshu_keys.txt`
Format: `username|email|key`

Pool integration:
- Cron job `rotate-aiqianshu-key` (30 min) picks random key
- Provider in Hermes config.yaml: `custom:aiqianshu` with `base_url: https://aiqianshu.com/v1`

## IMAP App Password

Email: `[REDACTED-NAME]@gmail.com`
App password: [REDACTED] at https://myaccount.google.com/apppasswords → "Почта" → "Компьютер Windows"
Note: app passwords can expire/revoke without notice. Test with IMAP+SMTP if user claims it works.