SDKs and CLI
Python SDK
Install and configure the hayonix package (sync and async), handle errors, tune retries and timeouts, paginate, stream, upload and download files, wait for resources and work with money.
The Python SDK has a method for every operation in the API reference, in snake_case: client.pods.create, client.serverless.submit_job, client.fine_tuning.list_events. Responses are plain dictionaries, typed as TypedDicts in hayonix.types. It needs Python 3.11 or later.
Install
pip install "hayonix[openai]"Configure
Client() reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL from the environment; keyword arguments override them (api_key, base_url, inference_base_url), along with timeout (seconds), max_retries, max_retry_wait, default_headers and your own http_client. Use it as a context manager, or call close(), to release its connections.
from hayonix import Client
# API_KEY, API_BASE_URL and INFERENCE_BASE_URL come from the environment by default.
client = Client(
timeout=30.0, # seconds per network operation of an attempt (default 60)
max_retries=3, # retries of a retryable failure (default 2)
)
me = client.caller() # the key's org, project and permissions
print("project:", me["project_id"])Path parameters are positional and everything else is a keyword argument: client.pods.exec(pod_id, command=[…]). Leaving an argument out omits it; None sends JSON null. Organization-level calls fill in the key's organization.
Errors
Every API error is an ApiError subclass chosen by the error's type; see Errors and retries.
from hayonix import ApiError, NotFoundError, RateLimitError
try:
client.pods.get("pod_00000000000000000000000000")
except NotFoundError as err:
print("not found:", err.message)
except RateLimitError as err:
print("slow down; retry after", err.retry_after_seconds, "s")
except ApiError as err:
print(err.status, err.type, err.code, err.param, "request", err.request_id)Retries and timeouts
Per-call settings go in request_options: timeout, max_retries, idempotency_key and headers.
secrets = client.secrets.list(limit=10, request_options={"timeout": 5.0, "max_retries": 0})
print("secrets on the first page:", len(secrets.data))Retries follow the rules in Errors and retries. Creating calls keep one Idempotency-Key across their retries; pass your own for retries from another process:
import uuid
from hayonix import Client, IdempotencyError
client = Client()
key = str(uuid.uuid4()) # store it with the work item, so a restarted job reuses it
first = client.secrets.create(name=name, value="example-value", request_options={"idempotency_key": key})
again = client.secrets.create(name=name, value="example-value", request_options={"idempotency_key": key})
print("same secret:", first["id"] == again["id"])Pagination
List methods return a page (data, next_cursor, next_page()) that is also an iterator over every item.
# Every item, fetching further pages as the loop reaches them:
for secret in client.secrets.list(limit=2):
print("secret:", secret["name"])# One page at a time: `data` and `next_cursor`, or `next_page()` until it returns None.
page = client.secrets.list(limit=2)
n = 1
while page is not None:
print(f"page {n}: {len(page.data)} item(s), next cursor: {page.next_cursor or 'none'}")
page = page.next_page()
n += 1Uploads and downloads
A file argument accepts a pathlib.Path (streamed from disk), bytes, a binary file object, or a (filename, content) tuple. Downloads return a BinaryResponse: read(), text(), iter_bytes() or save(path).
# Upload from disk (streamed, not read into memory), wait for validation, download again.
uploaded = client.files.upload(file=path, purpose="batch")
checked = client.wait_for.file(uploaded["id"])
print("file", checked["id"], checked["status"], checked["bytes"], "bytes")
client.files.get_content(uploaded["id"]).save(pathlib.Path(tmp) / "copy.jsonl")Waiting
client.wait_for polls until a resource reaches a state: pod, job, fine_tune, batch, file, dedicated_endpoint, sandbox and cluster, with timeout and on_update. It raises WaitTimeoutError or UnexpectedStateError.
done = client.wait_for.batch(batch["id"], on_update=lambda b: print("status:", b["status"]))Streaming
client.follow.job_stream and client.follow.fine_tune_events iterate live output until the job ends:
job = client.serverless.submit_job(endpoint["id"], input={"text": "hello from a worker"})
for chunk in client.follow.job_stream(job["id"]):
print("chunk:", json.dumps(chunk.get("data")))
done = client.wait_for.job(job["id"])
print("state:", done["state"], "output:", json.dumps(done.get("output")))Money
from hayonix import format_cost, format_usd, parse_usd
balance = client.billing.get_balance() # the key's org is filled in for you
print("available:", format_usd(balance["available"])) # e.g. "$25.00"
print("exact:", format_usd(balance["available"], max_decimals=9))
print("a tiny charge:", format_cost("184331")) # "<$0.01"
print("$5 in nano-USD:", parse_usd("5")) # "5000000000"Async
AsyncClient has the same methods as coroutines. Its list methods return a page you can await for the first page or iterate with async for.
from hayonix import AsyncClient
async def main() -> None:
async with AsyncClient() as aclient:
async for secret in aclient.secrets.list(limit=50):
print("secret:", secret["name"])
balance = await aclient.billing.get_balance()
print("available:", format_usd(balance["available"]))
asyncio.run(main())The OpenAI client
client.openai() (and AsyncClient.openai()) returns the official OpenAI client pointed at the inference base URL. It needs the openai extra:
pip install "hayonix[openai]"import os
from hayonix import Client
model = os.environ.get("MODEL", "qwen/qwen2.5-0.5b-instruct")
client = Client() # reads API_KEY, API_BASE_URL and INFERENCE_BASE_URL
openai = client.openai()
completion = openai.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "Name three uses for a GPU in one sentence."}],
max_completion_tokens=64,
)
print("reply:", (completion.choices[0].message.content or "").strip())
print("tokens:", completion.usage.total_tokens if completion.usage else None)