Wity
Console

API reference

Errors, limits & billing

Errors#

Errors return JSON with an error (or detail) message that says what to fix.

{ "error": "Choice 'intent' criteria must map 2 to 256 options" }
400
bad request
The body is not valid JSON, or a field is missing, too long or of the wrong shape. Fix the request; retrying will not help.
401
unauthorized
Missing or invalid API key.
402
out of credit
Your account's balance is at zero. Add credit in the console, then retry.
429
rate limited
Over your key's limits (below). Wait for Retry-After seconds, then retry.
502
upstream error
The model could not produce a valid answer. Rare; safe to retry once.
503
unavailable
The service is starting, waking from idle (Retry-After: 90, about 1.5 to 2 minutes; see Status), or temporarily unavailable. Retry with backoff.

Retries

Decisions are read-only, so retrying a 502 or 503 is always safe. Use exponential backoff starting at about one second, and a client timeout of at least 60 s so thought answers can finish.

Limits#

Context window
model
128K tokens: the size of the model's context. The request limits below are what the API accepts today.
Rate
per key
20 requests per second with bursts of up to 40, and 32 requests in flight. Beyond that: 429 with Retry-After. Need more? Email us.
Request body
size
Up to 12 MB, including an image.
image
count
One per request, as a data URL.
generate max_tokens
count
1 to 512 accepted; Wity writes at most 100 tokens per request.
extract
size
Up to 60,000 characters and 16 fields per request; at most 30 values per field. Extractions share capacity with decisions: when too many are running, one waits briefly, then answers 429.
split text
length
Up to 60,000 characters per request. Splits share capacity with decisions: when too many are running, a split waits briefly, then answers 429.
state
length
Up to 32,000 characters (objects and arrays are measured after JSON encoding).
instructions
length
Up to 4,000 characters per question.
choice options
count
2 to 256 per question; ids up to 128 characters, descriptions up to 2,000.
score levels
count
2 to 10 per question.
Question names
length
Up to 128 characters.
Skills
per account
500 skills, 20,000 examples each, 1,000 examples per call. See Skills.
Sessions
per session
100,000 events, 100 per call; kept 7 days by default, up to 90. See Sessions.

Billing#

You pay for what you send, counted once: $0.042 per million input tokens. Decisions have no output to pay for; text written by generate is billed at the same rate. Nothing about how Wity reaches the answer is billed. See Pricing for examples.

Billing is prepaid. Every account starts with $5 of credit, which is spent first and expires 48 hours after sign-up; add more by card on the console's Billing page, and that never expires. Each successful call is charged to the balance of the key's account, and failed calls cost nothing. Once the balance reaches zero, calls answer 402 with "code": "insufficient_credits" until you top up; a call already running when credit runs out still finishes.

  • usage.input_tokens is your request (state, instructions and criteria) counted once per question.
  • usage.output_tokens is 0 for decisions; for generate it reports the text written, billed at the input rate.
  • An extraction is billed on its usage.input_tokens: the document and the field list, counted once. No output tokens.
  • A split is billed on its usage.input_tokens: about the text's tokens plus a few hundred. Texts over about 5,000 characters are read in overlapping windows and count up to about twice. No output tokens.
  • Skills: a skill question is billed like the question it saves, plus each of its parts. Adding examples is billed once, on the tokens of their states. Learning, and reading or managing skills, is free.
  • Sessions: a decision is billed on what it reads, like the same request to /v1/systemone; a repeat answered from the session ("cached": true) costs nothing, and so do events and reads.
  • Each question is billed with the state it reads, so several questions cost about the sum of asking each. Asking them in one request saves round trips, not tokens; keep the state to what the decisions need.

Privacy#

Request and response bodies are not logged. We keep only operational records: which key made a request, when, its status and how long it took.

Previous

← Sessions: /v1/sessions

Next

Python SDK →