Прямой API

Ключи

Запросы из кода работают с любым действующим ключом: платным и контрактным. Режим ключа показывает GET /v1/account: billing_mode: metered — платный, решения оплачиваются с баланса; unmetered — контрактный, без оплаты.

Адрес и авторизация

Адрес сервера — https://capi.z3n.pro. Ключ передаётся заголовком Authorization: Bearer <ключ> или X-API-Key: <ключ>. Тот же ключ открывает кабинет. Не передавайте ключ в адресе запроса: он попадает в логи прокси и истории.

Запрос решения

POST /v1/solve/{тип}, где тип — text, hunt, geetest_icon, geetest_slide, geetest_nine, tencent_icons или yandex_icons. Для text модель задаётся полем model (gaijin, mojeid, nova), для hunt вид задания — полем type (happy_puzzle, swipe_goal). Тело — JSON с полем image (base64 картинки, допускается префикс data:image/…;base64,) и параметрами типа. Для типов с одной картинкой можно отправить сами байты с Content-Type: application/octet-stream, а параметры — в строке запроса: /v1/solve/text?model=nova.

Передавайте Idempotency-Key (1–128 символов), уникальный для каждой задачи. Повтор с тем же ключом и тем же телом вернёт сохранённый ответ без нового списания; другое тело с тем же ключом даёт 409. Параметры и примеры тела для каждого типа — на странице капчи, в разделе «Прямой API».

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

Ответ

Ответ содержит результат распознавания (поля зависят от типа) и task_id. По task_id можно узнать состояние задачи: GET /v1/task/{id}.

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

Оплата

metered: цена типа (GET /v1/prices) резервируется при приёме запроса и списывается, когда сервер вернул решение. Если распознавание завершилось ошибкой или таймаутом (500, 504), резерв освобождается и списания нет. При нехватке доступного баланса запрос получает 402 до запуска распознавания.

unmetered: решения не списываются, баланс и тарифы не нужны. Лимит задач в минуту на аккаунт действует в обоих режимах.

Пример на Python

Ключ берётся из переменной окружения CAPI_API_KEY.

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())},  # один ID на задачу, повторять с тем же
    json=payload,
    timeout=90,
)
response.raise_for_status()
task = response.json()
print("ответ:", task["text"])

Все маршруты

GET /v1/account — баланс, billing_mode. GET /v1/balance — баланс, резерв, доступно. GET /v1/prices — цена по типам. POST /v1/solve/{тип} — решение. GET /v1/task/{id} — состояние задачи, цена. Коды ошибок — на странице «Ошибки и повторы».