TokenSpend Python

Official Python client for the TokenSpend API. It has no runtime dependencies. Requires Python 3.9+. Use a virtual environment.

Follow the canonical quickstart to set TOKENSPEND_API_KEY with hidden input. Use a TokenSpend rail key, never a provider or admin credential. Do not commit keys.

python3 -m pip install tokenspend

from tokenspend import TokenSpend

client = TokenSpend()
response = client.chat.completions.create(
    model="xai/grok-4.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
print(response.request_id)

Pass one stable key across retries of the same request:

response = client.chat.completions.create(
    model="xai/grok-4.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    idempotency_key="job-42-generation",
)

Changing the request requires a new idempotency key. The safe TokenSpend request id is available as response.request_id, on a streaming iterator, and as error.request_id when a duplicate returns 409. Keys are scoped to workspace and route for 24 hours. Duplicates do not replay the response. Use a new key after a failed request if you want another attempt.

Discover canonical ids and protocol capabilities from the live registry:

models = client.models.list()
model = client.models.retrieve("zai/glm-5.2")

Set stream=True to iterate over server-sent chunks. client.messages.create(...) uses the Anthropic-compatible Messages API. See https://tokenspend.dev/docs/router.

Other canonical IDs include meta/muse-spark-1.2, thinking-machines/inkling, and moonshot/kimi-k3. Capabilities differ by model and format. Muse needs max_tokens=2048 or greater for its visible-output contract.

Requests are billable. Match response.request_id to the cost receipt in Router activity. Check stream errors and completion state before accepting output.

Request logging is off by default. Opt-in history is encrypted and expires after 30 days. Disabling logging stops new storage; existing history keeps its expiry. Capture is metadata-only. TokenSpend does not currently offer provider ZDR. See Trust and the agent compatibility review. SDK smoke tests do not verify agent sessions. Responses tools are unsupported.

The SDK never accepts a serving-host selector.