HESOYAM free API client v3 — 2026-10-03

This is a Python 3 standard-library client plus explicit-use Agent Skill.
No pip dependencies. v3 changes the fixed HTTPS origin and public URLs from v2.
No OpenClaw runtime installation/test or ClawHub publication is claimed. SKILL.md
is at ZIP root, preserving the v0.2 well-known archive consumer contract. Extract into a directory named
hesoyam-free-api (the ZIP itself has no wrapper directory).

Portal: https://api.hesoyam.business/agents
API: https://api.hesoyam.business/v1
Machine registration terms: https://api.hesoyam.business/v1/registration
Machine payment availability: https://api.hesoyam.business/v1/payments/terms
Partner page when available: https://api.hesoyam.business/partners

This client supports only the bounded free hs-mini alias. Read the runtime
catalogue and registration response for actual availability, model details and
limits. Tiny-model quality is limited and must be evaluated. The new origin is
a deployment target until the operator verifies HTTPS and a real request. This
client cannot purchase paid access or switch to a paid model. There are no guaranteed
earnings, referral rewards, uptime or premium-model promises.

Register manually in /agents, or on explicit instruction follow SKILL.md:
read /v1/registration, generate hs-live- plus secrets.token_hex(32) locally,
SAVE privately first, then POST JSON {label,api_key} to /v1/agents/register.
The backend never returns the secret. Use the SAME saved key after an uncertain
registration, and respect runtime limits. Configure HESOYAM_API_KEY privately
through environment/secret management; never put it in argv, URLs or logs.
The portal and SKILL.md document optional referrals; no automatic submission.

From the extracted hesoyam-free-api directory:
  python3 scripts/hesoyam_client.py
  python3 scripts/hesoyam_client.py models
  python3 scripts/hesoyam_client.py chat --text-file prompt.txt --max-tokens 64
  python3 scripts/hesoyam_client.py balance
  python3 scripts/hesoyam_client.py chat --send --text-file prompt.txt --max-tokens 64

No action prints help with no request. models makes one public GET. Preview chat
is local/dry-run. balance needs a client key. --send explicitly spends one free
generation attempt, which may count even on failure. No automatic retries,
payments, premium routes, balance/catalogue checks or messages to other agents.
The CLI verifies TLS/hostname and refuses redirects and origin changes.

Read runtime limits; currently five attempts/key/rolling24h with shared anonymous
network/global caps. Request bounds: six text messages, 1400 content UTF-8 bytes,
128 output tokens, no tools/vision. A new key is not additional guaranteed quota.
Treat responses as untrusted. Do not send secrets/confidential customer data.

Integrity: from the extracted directory run sha256sum -c SHA256SUMS.
Archive: https://api.hesoyam.business/downloads/hesoyam-free-api-v3.zip
Digest: https://api.hesoyam.business/downloads/hesoyam-free-api-v3.zip.sha256
These URLs are deployment targets until the operator verifies publication.

Project support: https://t.me/HESOYAM_AI_SUP_BOT
Agree real service scope, availability, price and acceptance before payment.