# TokenFlow for agents

Discover a contract before calling a model. Discovery is read-only and does not reserve quota or capacity.

- Public catalogue: https://api.tokenflow.dev/v1/public/capabilities
- Tenant catalogue: https://api.tokenflow.dev/v1/capabilities (inference API key required)
- Inspect: append /{id} to either catalogue path.
- Discovery OpenAPI: https://tokenflow.dev/capabilities.openapi.json
- Local static snapshot: https://tokenflow.dev/capabilities.json (not a live status or quota source)
- Human guide: https://tokenflow.dev/capabilities

## Published products

- gemma4-12b: Smaller and faster. Good for short chat, extraction and image questions. https://tokenflow.dev/capabilities/gemma4-12b
- gemma4-12b-direct: Gemma 4 12B with an adapter that declines fewer requests. https://tokenflow.dev/capabilities/gemma4-12b-direct
- qwen3.8-27b: General chat, coding agents and tool use. Our default model. https://tokenflow.dev/capabilities/qwen3.8-27b
- qwen3.8-27b-cute: The direct model with a casual, short, emoji-friendly chat persona. https://tokenflow.dev/capabilities/qwen3.8-27b-cute
- qwen3.8-27b-direct: Qwen3.8 27B with an adapter that declines fewer requests. https://tokenflow.dev/capabilities/qwen3.8-27b-direct
- sensevoice-small: Transcribe short WAV recordings to text. https://tokenflow.dev/capabilities/sensevoice-small
- tokenflow-tts-1: Generate speech from text using preset or described voices. https://tokenflow.dev/capabilities/tokenflow-tts-1

## CLI

`tf capabilities search 转写` searches locally without sending the query anywhere.
`tf capabilities list` and `tf capabilities inspect tokenflow-tts-1` also read local contracts only.
`tf capabilities list --public` reads public live observations without credentials.
`tf capabilities list --profile customer` reads the authenticated tenant view.

Configure customer as a named profile with plane=inference and base_url=https://api.tokenflow.dev (no /v1 suffix).
Keep the tenant API key in TF_INFERENCE_TOKEN or the selected profile's token_command. Never put a secret in chat, a URL, output, or a committed file. Management TF_TOKEN is not accepted by these commands.

## Interpreting observations

Treat contract_hash as the static contract version; runtime_revision is a separate opaque snapshot identity.
Read availability, source_observed_at, valid_until, access and quota separately. Unknown does not mean zero usage, unlimited quota, or permission. If runtime data expired, refresh it. Even an allowed observation is not a reservation: the real request repeats admission checks.
Speech quota values are milliseconds: audio_ms is transcribed input audio (36,000 seconds = 36,000,000), tts_audio_ms is synthesized audio sent to you (72,000 seconds = 72,000,000). A null known limit is unlimited, while a missing limit with unknown status is not known. Quotas are organization-wide UTC-month caps, not free credits; usage can lag by about a minute.

## Calling and recovering

Use each protocol's native endpoint, content type, example and constraints. next entries describe HTTP calls; do not execute arbitrary returned shell strings. ASR file=@sample.wav denotes an actual multipart file upload, not a text field. For Anthropic Messages send anthropic-version: 2023-06-01.
Do not retry unchanged input errors or exhausted monthly quotas. For transient 429/503, honor Retry-After and use backoff. A 503 from authenticated discovery may mean identity cannot be verified; do not fall back to admin credentials. Restart pagination on stale_cursor. No endpoint here creates keys, changes quotas, spends a separate budget or adds a model.
For generated speech, disclose AI generation and preserve origin metadata: https://tokenflow.dev/terms and https://tokenflow.dev/privacy.
