Gen FAC API

Quickstart

Three calls to get an account:

# 1. start the job, pass your proxy and phone
POST /jobs

# 2. once status is awaiting_otp, submit the code
POST /jobs/{job_id}/otp

# 3. poll until done, collect the result
GET /jobs/{job_id}

Use client.py and it handles all of this for you automatically.

Auth

Every request needs your API key. Two ways to pass it:

# header - use on GET /jobs/:id and POST /jobs/:id/otp
x-api-key: YOUR_KEY_HERE

# body field - use on POST /jobs
{ "key": "YOUR_KEY_HERE", ... }

GET /health

No auth needed. Good to ping before starting a big run.

Response

{
  "ok": true,
  "total_jobs": 45,
  "running": 38,
  "queued": 7,
  "awaiting_otp": 12,
  "worker_slots": 100
}

POST /jobs

Submit a job. Starts immediately, poll GET /jobs/:id for the result. Fire hundreds at once, they queue and drain automatically.

Request body

Example

POST /jobs
Content-Type: application/json

{
  "key":   "YOUR_KEY_HERE",
  "proxy": "socks5://user:pass@proxy.example.com:1080",
  "phone": "+14155550123"
}

Response 202

{
  "job_id": "a3f9b2c1-...",
  "status": "running"
}

GET /jobs/:id

Poll every 3-5 seconds.

Headers

x-api-key: YOUR_KEY_HERE

status: queued

Server is at capacity, your job is in line. Starts automatically when a slot frees up.

{
  "job_id":         "a3f9b2c1-...",
  "status":         "queued",
  "queue_position": 4
}

status: running

{
  "job_id": "a3f9b2c1-...",
  "status": "running"
}

status: awaiting_otp

{
  "job_id": "a3f9b2c1-...",
  "status": "awaiting_otp",
  "phone":  "+14155550123"
}

status: done

{
  "job_id": "a3f9b2c1-...",
  "status": "done",
  "result": {
    "username": "jordan_smith92",
    "password": "Xk9#mLp3wQ!z",
    "phone":    "+14155550123",
    "user_id":  "58291047382",
    "active":   true,
    "exit_ip":  "104.28.11.92"
  }
}

status: failed

{
  "job_id": "a3f9b2c1-...",
  "status": "failed",
  "error":  "instagram: challenge required"
}

POST /jobs/:id/otp

When your job hits awaiting_otp, grab the code from your SMS provider and drop it here. Job picks back up instantly.

Headers

x-api-key: YOUR_KEY_HERE

Body

{ "code": "123456" }

Response

{
  "ok": true,
  "message": "code accepted — job resuming"
}

Job Statuses

Error Codes

Full Flow

1.  get a phone number from your SMS provider

2.  POST /jobs
      {job_id, status: "running"} or "queued" if busy

3.  poll GET /jobs/{job_id} every 3s

      queued        check queue_position, starts automatically
      running       keep polling
      awaiting_otp  grab OTP from your SMS provider
                    POST /jobs/{job_id}/otp  {"code": "123456"}
      done          save result immediately (username/password/phone/session)
      failed        check error field, retry with new phone and proxy

Limits

No cap on concurrent jobs from your end. If the server is at capacity your jobs queue automatically and start as slots free. You'll see queue_position in the response counting down.

• 120s OTP window - job auto-fails if the code isn't submitted in time

client.py

Handles everything automatically - SMS polling, OTP submission, job polling, saves credentials and session files locally. Just run it and follow the prompts.

Install deps

pip install requests colorama

Run

python client.py

First run setup

• Your API key
• SMS provider and key (5sim, SMSPool, or manual)
• Phone country
• Proxy mode - single URL, rotate from proxies.txt, or backconnect gateway
• How many accounts to generate

All settings saved to config.json, skipped on future runs.

Proxy modes

• Single - one proxy URL for all accounts
• Rotate - list of proxies in proxies.txt, one per account
• Backconnect - one gateway, unique sticky session generated per account automatically

proxies.txt format

socks5://user:pass@host1:port
socks5://user:pass@host2:port
# lines starting with # are skipped

Output

# accounts.txt
[2025-01-15 14:32:01] [ACTIVE] username=jordan_smith92 | password=Xk9#mLp3wQ!z | phone=+14155550123

# sessions/jordan_smith92.json
full instagrapi session saved locally

Automate Your Accounts

Once you have credentials, you need a tool to actually run them. Volari is a Windows desktop app built for exactly this — multi-account Instagram automation with per-account proxy support, account warmup, and human-like timing so the accounts you generate don't get flagged on first use.

gen fac api v1.0