zefoy-client 0.1.2

Python client for zefoy.com — JSON-only API (login, services, send views/hearts/...)

zefoy-client

Python client library for zefoy.com.

• JSON-only API — every public method returns a dict (ready for json.dumps)
• No stdout noise from the library
• Captcha via ddddocr (optional manual captcha)
• Auto cooldown wait (IP-based server timer)
• Services: views, hearts, favorites, shares, followers, …

Disclaimer: Unofficial. Use at your own risk. Respect site terms and local laws. For educational / automation research purposes.

---

Install

PyPI

pip install zefoy-client

Optional extras:

pip install "zefoy-client[socks]"   # SOCKS4/5 proxy
pip install "zefoy-client[ocr]"     # pytesseract helper
pip install "zefoy-client[socks,ocr]"

GitHub

Repo: https://github.com/deno4908/zefoy_lib

# latest main
pip install git+https://github.com/deno4908/zefoy_lib.git

# specific branch / tag
pip install git+https://github.com/deno4908/zefoy_lib.git@main
pip install git+https://github.com/deno4908/zefoy_lib.git@v0.1.0

Clone rồi cài editable (dev):

git clone https://github.com/deno4908/zefoy_lib.git
cd zefoy_lib
pip install -e .
# pip install -e ".[socks,ocr]"

From local folder

cd zefoy-client
pip install -e .

Build / publish wheel

pip install build twine
python -m build
twine check dist/*
# twine upload dist/*

---

Quick start

import json
from zefoy import Zefoy

bot = Zefoy(
    use_ocr=True,       # solve captcha with ddddocr
    auto_wait=True,     # sleep on server cooldown
    # proxy="http://user:pass@host:port",
)

print(json.dumps(bot.login(), ensure_ascii=False, indent=2))
print(json.dumps(bot.services(), ensure_ascii=False, indent=2))

url = "https://www.tiktok.com/@user/video/1234567890"
print(json.dumps(bot.send_views(url), ensure_ascii=False, indent=2))

Proxy

proxy áp dụng cho toàn session (login + captcha + services + send).
Hỗ trợ URL string hoặc dict kiểu requests.

Loại	Ví dụ
HTTP	http://host:8080
HTTP + auth	http://user:pass@host:8080
HTTPS proxy	https://user:pass@host:8443
SOCKS5	socks5://user:pass@host:1080
SOCKS5h (DNS qua proxy)	socks5h://user:pass@host:1080
SOCKS4	socks4://host:1080

# SOCKS cần thêm dependency
pip install -e ".[socks]"
# hoặc: pip install PySocks requests[socks]

from zefoy import Zefoy
import json

# 1) HTTP proxy (string — gán cả http & https)
bot = Zefoy(proxy="http://1.2.3.4:8080")

# 2) HTTP có user/pass
bot = Zefoy(proxy="http://myuser:mypass@1.2.3.4:8080")

# 3) SOCKS5
bot = Zefoy(proxy="socks5://user:pass@1.2.3.4:1080")

# 4) SOCKS5 + resolve DNS trên proxy
bot = Zefoy(proxy="socks5h://user:pass@1.2.3.4:1080")

# 5) Dict tách http / https (giống requests)
bot = Zefoy(proxy={
    "http": "http://user:pass@1.2.3.4:8080",
    "https": "http://user:pass@1.2.3.4:8080",
})

# 6) Dùng với send
url = "https://www.tiktok.com/@user/video/123"
print(json.dumps(bot.login(), ensure_ascii=False, indent=2))
print(json.dumps(bot.send_views(url), ensure_ascii=False, indent=2))
print(json.dumps(bot.send_hearts(url), ensure_ascii=False, indent=2))

CLI:

zefoy --proxy "http://user:pass@host:8080" send views "https://www.tiktok.com/@u/video/123"
zefoy --proxy "socks5h://user:pass@host:1080" send hearts "https://..."

Proxy đổi IP → tránh / giảm cooldown theo IP của Zefoy. Proxy chết sẽ làm login/send trả ok: false.

Manual captcha

bot = Zefoy(use_ocr=False)
img = bot.get_captcha_image("captcha.png")  # open image yourself
print(bot.login(captcha_text="flower"))

Custom captcha solver

def my_solver(image):
    # image: PIL.Image
    return "answer"

bot = Zefoy(captcha_solver=my_solver)
bot.login()

---

API

Zefoy(...)

Arg	Type	Default	Description
use_ocr	bool	True	Auto-solve captcha
auto_wait	bool	True	Wait on IP cooldown
max_cooldown_retries	int	5	Max wait/retry loops
proxy	str | dict	None	Proxy URL hoặc dict requests (HTTP/HTTPS/SOCKS)
captcha_solver	callable	None	f(PIL.Image) -> str
user_agent	str	Chrome 131	Must stay consistent per session
on_event	callable	None	Optional debug hook f(dict)

Methods (all return dict)

Method	Description
login(captcha_text=None, max_tries=5)	Captcha + session
submit_captcha(text)	Submit captcha only
services() / get_services()	List available services
send(service, url)	Search + send order
send_views(url)	Shortcut
send_hearts(url)	Shortcut
send_favorites(url)	Shortcut
send_shares(url)	Shortcut
send_followers(url)	Shortcut
Zefoy.to_json(data)	json.dumps helper

service name examples: "views", "t-views", "hearts", "favorites", …

---

Response shape

Every call looks like:

{
  "ok": true,
  "...": "..."
}

login() success

{
  "ok": true,
  "status": "logged_in",
  "captcha": "flower",
  "attempts": []
}

services() success

{
  "ok": true,
  "count": 8,
  "services": [
    {
      "name": "t-views",
      "disabled": false,
      "action": "https://zefoy.com/c2VuZC9mb2xeb3dlcnNfdGlrdG9V"
    }
  ]
}

send_views() success

{
  "ok": true,
  "status": "sent",
  "service": "t-views",
  "target": "https://www.tiktok.com/@u/video/123",
  "video_id": "123",
  "zefoy_amount": 1000,
  "zefoy_amount_label": "1000 views",
  "wait_seconds": 552,
  "summary": "sent 1000 views | next_wait 552s"
}

Note: zefoy_amount is decided by Zefoy, not by the caller.

Error

{
  "ok": false,
  "error": "cooldown",
  "wait_seconds": 91,
  "message": "Please wait 91 seconds before trying again."
}

Common error codes: login_failed, captcha_rejected, cooldown, service_not_found, no_send_form, send_failed, max_retries.

---

CLI

After install:

zefoy login
zefoy services
zefoy send views "https://www.tiktok.com/@u/video/123"

Or:

python -m zefoy send views "https://..."

---

Flow (internal)

1. Login — fetch captcha image → OCR/manual → POST captchalogin + encrypted fingerprint
2. Search — POST /{base64_action} with HASH=full_tiktok_url
3. Send — POST same endpoint with HASH=video_id
4. Response body is reverse + base64 (same as site JS)

Server cooldown is IP-based, not local-session-based. New process on same IP still waits.

---

Project layout

zefoy-client/
├── pyproject.toml
├── README.md
├── LICENSE
├── MANIFEST.in
├── examples/
│   └── basic.py
└── src/
    └── zefoy/
        ├── __init__.py
        ├── __main__.py
        └── client.py

---

Publish to PyPI

python -m build
twine check dist/*
twine upload dist/*

Users install with:

pip install zefoy-client
# or from GitHub:
pip install git+https://github.com/deno4908/zefoy_lib.git

---

License

MIT