POST /v1/decide answers questions about text. You send one text (or up to 64) and
the questions you want answered; each question is a choice between options, a
multilabel tag set, a bool, or a score on an integer range. The reply is,
per text and question, the best option, a probability for every option, and for
scores the expected value.
It is the hosted version of the open OpenDecision
models, which you can also run yourself.
This runs a model. The text is sent to Tokz and read by an OpenDecision model; it
is not stored or logged, and only counters are kept. Do not send what you would
not send to a hosted model. Building a fine tune is different:
that text goes to the services that train it.
A request
policy is the distribution over the options
(it sums to 1); value is the per-option probability that the option is correct, and
is what multilabel thresholds. Options can be strings or {"id", "name", "description"};
the description is read by the model, so use it to say what an option means.
Models and prices
GET /v1/decide/models returns the live list. Suite macro-F1 is the average over AG News,
CLINC150, IMDb, Rotten Tomatoes and XNLI in the technical report. It describes
classification over label sets of the kind the models were trained on; on label sets
they have not seen, some other open models score higher, so test on your own data.
model also takes the name of a fine tune your organization owns. Such a
model already knows its question and labels, so the request has no decisions.
What is billed
Input only; answers are free. A billed token is a token of the text plus the question, read once per 16 options, plus the option tokens. For a question with up to 16 options this is just the number of tokens you send. Questions with more than 16 options are billed at 3×, because they cost about that much more to serve. Every request bills at least 256 tokens. Serving cost is mostly per request, so send several texts in one call (up to 64) when you can: a batch of short texts costs the same per token as one long one. Cost is billed tokens at the model’s price, drawn from your prepaid credit (see Billing). You are charged only for a request that succeeds: a 4xx or 5xx costs nothing. At a zero balancePOST /decide returns 402 with
insufficient_credits.
Limits
Errors
A
429 or 503 can carry Retry-After in seconds. Fine tunes have a few more errors of
their own: see Fine Tune.
SDKs
decide() ships in @tokz/sdk 0.5+ (npm i @tokz/sdk) and the Python package
tokz 0.4+ (pip install tokz, sync Tokz and async AsyncTokz). Both send the
request above, return typed results, raise TokzInsufficientCreditsError on 402, and
never retry, since a retry could bill twice. listDecisionModels() /
list_decision_models() return the catalog. See TypeScript and
Python. Calling a fine tune by name needs @tokz/sdk 0.7+ or tokz 0.6+.
Send several texts in one call (up to 64) when you can: every request bills at least 256
tokens, and a batch shares one model pass.
Usage
GET /v1/decide/usage?days=30 returns the key’s requests, texts, decisions, billed
tokens and cost, by day and by model. In the dashboard, Usage shows the same for the
whole organization, and Playground runs requests against one of your keys.