Direct API

Keys

Requests from code work with any active key, paid or contract. GET /v1/account shows the key's mode: billing_mode: metered — paid, solutions are paid from the balance; unmetered — contract, no payment.

Address and authorization

Server address — https://capi.z3n.pro. Send the key in the Authorization: Bearer <key> or X-API-Key: <key> header. The same key opens the dashboard. Do not put the key in the URL: it ends up in proxy logs and history.

Solve request

POST /v1/solve/{type}, where type is text, hunt, geetest_icon, geetest_slide, geetest_nine, tencent_icons or yandex_icons. For text the model is set by the model field (gaijin, mojeid, nova); for hunt the task kind is set by the type field (happy_puzzle, swipe_goal). The body is JSON with an image field (base64 of the image; a data:image/…;base64, prefix is allowed) and the type's parameters. For single-image types you can send the raw bytes with Content-Type: application/octet-stream and pass parameters in the query string: /v1/solve/text?model=nova.

Send an Idempotency-Key (1–128 characters), unique per task. A repeat with the same key and body returns the stored response without a new charge; a different body with the same key gets 409. Parameters and body examples for each type are on the captcha page, in «Request example».

curl -X POST "https://capi.z3n.pro/v1/solve/text?model=nova"\
  -H "Authorization: Bearer $CAPI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @captcha.png

Response

The response holds the recognition result (fields depend on the type) and task_id. Use task_id to get the task state: GET /v1/task/{id}.

{
  "status": "ok",
  "captcha_type": "text",
  "model": "nova",
  "text": "7kx2p",
  "task_id": "3f0c9b7e2d6a4c1b8e5f0a9d7c6b5a43"
}

Billing

metered: the type's price (GET /v1/prices) is reserved when the request is accepted and charged when the server returns a solution. If recognition ends with an error or a timeout (500, 504), the reserve is released and nothing is charged. With too little available balance the request gets 402 before recognition starts.

unmetered: solves are not charged, no balance or tariffs needed. The per-minute task limit applies in both modes.

Python example

The key is taken from the CAPI_API_KEY environment variable.

import base64
import os
import uuid
from pathlib import Path

import requests

BASE = "https://capi.z3n.pro"
HEADERS = {"Authorization": f"Bearer {os.environ['CAPI_API_KEY']}"}

payload = {
    "image": base64.b64encode(Path("captcha.png").read_bytes()).decode("ascii"),
    "model": "nova",
}
response = requests.post(
    f"{BASE}/v1/solve/text",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},  # one ID per task, reuse it on retry
    json=payload,
    timeout=90,
)
response.raise_for_status()
task = response.json()
print("answer:", task["text"])

All routes

GET /v1/account — balance, billing_mode. GET /v1/balance — balance, reserved, available. GET /v1/prices — price per type. POST /v1/solve/{type} — solve. GET /v1/task/{id} — task state, price. Error codes are on the «Errors and retries» page.