Skip to content
Hayonix

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
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.

Python
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.

Python
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.

Python
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:

Python
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.

Python
# Every item, fetching further pages as the loop reaches them:
for secret in client.secrets.list(limit=2):
    print("secret:", secret["name"])
Python
# 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 += 1

Uploads 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).

Python
# 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.

Python
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:

Python
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

Python
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.

Python
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
pip install "hayonix[openai]"
Python
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)