Effort
Low, medium or high: whether the model reads a call, when, and what each level costs.
Every POST takes effort: how hard a call is looked at. The free checks run
at every level. What changes is whether the model reads it, and when.
The three levels
effort | What the model reads | What it costs |
|---|---|---|
low |
Nothing. Word lists, checksums and shapes, in milliseconds. | 1 credit, always. |
medium |
Only what the free checks left in doubt: something they held for review, or a refusal resting only on evidence that needs reading to judge (profanity, shouting). A clean allow is not read, and neither is a refusal on hard evidence such as a wallet address or a card number. |
1 when the model did not read it; about 8 for a comment it read. |
high |
Everything, except what is already refused on evidence a reading cannot soften. A wallet address with a promised return is a scam whatever the sentence around it says. | About 8 for a comment, about 10 for an image. |
Doubt, at medium, only exists where the policy has a review line. A category
you set to block at 0.80 with no review line below it has nothing in between for the
model to settle, so a score of 0.60 there is an allow and is not read.
The default for each endpoint
The level that applies is the call's effort, then the policy's, then the
endpoint's own default:
| Endpoint | Default |
|---|---|
/text, /conversation | medium. Nearly all of it is an ordinary sentence the free checks settle. |
/image, /prompt | high. No free check can see what a picture shows, and the injection shapes the lists know are a small part of the ones that exist. |
/signup | low. A hot path where the lists and a DNS lookup catch what a signup usually is. medium and high are accepted. |
/name, /email, /url | low, and nothing else: no model reads them. An explicit medium or high is a 422 effort_unavailable. |
A policy can set its own level under
Effort in its Settings tab, so a site sets it once instead of on every
call. The dating and children templates start at high. A policy asking for
more on a name, an address or a link is not an error: those stay low.
An image is either looked at or not, since there is no free check whose doubt a reading
could settle. medium on an image is read as high, and the answer
says "effort": "high".
What the answer says
Every verdict carries the level it was judged at and whether the model read it:
"effort": "medium",
"model": { "read": false, "why": "settled" }
model is always there. why appears only when the level allowed a
reading and none happened:
why | Meaning |
|---|---|
settled | The free checks left nothing for a reading to add at this level: no doubt at medium, or a refusal on hard evidence at either. |
conversation_sampling | A message of a conversation the model deliberately skipped. Even at high, a thread is read when the free checks found something, when a lead type is half there, or every fifth message, rather than forty readings for forty messages. |
test_key | A test key, which never reaches the model. |
unavailable | The model could not be reached. The answer also says "degraded": true, and the call is billed as a check. |
The quota check before the call
Credits are taken after the call, from what the model actually used. Before it, at
medium or high, the quota is checked against one typical reading
(about 8 for text, 10 for an image), because the
level allows one. At medium that can refuse a call the free checks would have
settled for 1; an account close to zero gets through with
"effort": "low". See usage.
The legacy ai field
Clients written before effort existed sent "ai": true or
"ai": false. It is still accepted, as legacy: true means
"effort": "high" and false means "effort": "low", on
every endpoint, on a batch envelope and on each item. When a body sends both,
effort decides. "ai": true on an address, a name or a link is
refused with effort_unavailable, like "effort": "high". New code
should send effort: the answer only ever reports effort and
model, and the SDKs no longer offer ai.