Quickstart
- Create an account at platform.bineric.com and copy an API key from API keys.
- Send a document as
stateand your questions asquestions.
Base URL
https://api.bineric.com
First request
curl https://api.bineric.com/v1/zuse \-H "Authorization: Bearer $BINERIC_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "zuse-27b","state": "Hi, I was charged twice for my monthly pass last week. I want my money back as soon as possible, this is the second time it has happened!","questions": {"team": {"type": "choice","instructions": "Which team should handle it?","criteria": {"billing": "Payments and refunds","technical": "The app or website is not working","travel": "Questions about routes and departures","other": "Other"}},"refund": {"type": "noul","instructions": "Is the customer asking for a refund?"},"urgency": {"type": "score","instructions": "How urgent is it?","criteria": ["Not urgent","Normal","Urgent","Critical"]}}}'
import osimport requestsresponse = requests.post("https://api.bineric.com/v1/zuse",headers={"Authorization": f"Bearer {os.environ['BINERIC_API_KEY']}"},json={"model": "zuse-27b","state": "Hi, I was charged twice for my monthly pass ...","questions": {"team": {"type": "choice","instructions": "Which team should handle it?","criteria": {"billing": "Payments and refunds","technical": "The app or website is not working","other": "Other",},},"refund": {"type": "noul", "instructions": "Is the customer asking for a refund?"},},},timeout=30,)response.raise_for_status()answers = response.json()["answers"]if answers["team"]["confidence"] >= 0.9:route_to(answers["team"]["choice"]) # act on itelse:send_to_human_review() # not sure enough
const response = await fetch("https://api.bineric.com/v1/zuse", {method: "POST",headers: {Authorization: `Bearer ${process.env.BINERIC_API_KEY}`,"Content-Type": "application/json",},body: JSON.stringify({model: "zuse-27b",state: "Hi, I was charged twice for my monthly pass ...",questions: {team: {type: "choice",instructions: "Which team should handle it?",criteria: { billing: "Payments and refunds", technical: "The app is not working", other: "Other" },},refund: { type: "noul", instructions: "Is the customer asking for a refund?" },},}),});const { answers } = await response.json();console.log(answers.team.choice, answers.team.confidence, answers.refund.noul);
Authentication
Send your Bineric API key as a bearer token. The same key works for the chat API and for the decision API, and both draw on the same credit.
Authorization: Bearer $BINERIC_API_KEY
Models
Pass the id as model. If you leave it out, the request goes to zuse-9b, or to zuse-27b while the 9B is not available.
| Model id | Use it for | Price per 1M input tokens |
|---|---|---|
zuse-27b | Highest accuracy, for the decisions you automate. | $0.75 |
zuse-9b | Fast and low cost, for routing at volume. | $0.12 |
POST /v1/zuse
Answers every question about one document in a single pass.
| Field | Type | Description |
|---|---|---|
model | string | Optional. A model id from the table above. |
state | string, object or array | The document or record to decide about. JSON is passed as is; you do not need to flatten it. |
questions | object | At least one question, keyed by an id you choose. The answers come back under the same ids. |
{"model": "zuse-27b","state": "Hi, I was charged twice for my monthly pass last week. I want my money back as soon as possible, this is the second time it has happened!","questions": {"team": {"type": "choice","instructions": "Which team should handle it?","criteria": {"billing": "Payments and refunds","technical": "The app or website is not working","travel": "Questions about routes and departures","other": "Other"}},"refund": {"type": "noul","instructions": "Is the customer asking for a refund?"},"urgency": {"type": "score","instructions": "How urgent is it?","criteria": ["Not urgent","Normal","Urgent","Critical"]}}}
Question types
| type | criteria | What you get |
|---|---|---|
choice | Object of option id to description, 1 to 255 options. A description can be null. | choice (the most likely option id), confidence, and probabilities for every option. |
noul | Optional. Use instructions to state the yes/no question. | noul: the probability that the answer is yes. |
score | Array of levels in order, lowest first, at least 2. | score (the expected level, counted from 0), confidence, legend and probabilities per level. |
Every question also takes instructions: the question itself, in any supported language (100+).
Response
The values below are an example. usage.input_tokens is what you are billed for;latency_ms is model time, without network.
{"model": "zuse-27b","answers": {"team": {"type": "choice","choice": "billing","confidence": 0.9912,"probabilities": {"billing": 0.9912,"technical": 0.0031,"travel": 0.0009,"other": 0.0048}},"refund": {"type": "noul","noul": 0.9874},"urgency": {"type": "score","score": 2.3001,"legend": {"0": "Not urgent","1": "Normal","2": "Urgent","3": "Critical"},"probabilities": {"0": 0.0102,"1": 0.0915,"2": 0.4863,"3": 0.412},"confidence": 0.4863}},"usage": {"input_tokens": 214,"output_tokens": 0},"latency_ms": 18.6}
Response headers
| Header | Meaning |
|---|---|
x-bineric-model | The model that answered. |
x-bineric-hosting | Where it ran, for example EU. |
GET /v1/models
Public, no key needed. The OpenAI-style data list has every model the API serves, chat and decision, with live prices and the context length; the decision models have category set to Decision. models lists the decision models again, with name and description only.
curl https://api.bineric.com/v1/models
Errors
Errors carry error.message and a machine-readable error.code, and most also carry the message in detail. A missing or invalid key (401) has no detail; a request the decision server rejects comes back as its own body.
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request, model_not_supported | Fix the request. A chat model id was sent, or questions are missing. |
| 401 | invalid_api_key, missing_api_key | Check the key. |
| 402 | insufficient_quota | Add credits. |
| 403 | payment_required | This model needs credit on the account. Add credits. |
| 404 | model_not_found | Use an id from GET /v1/models. |
| 400, 413, 422 | – | The decision server rejected the request, for example a malformed question or a document that is too long. The body comes back as the server sent it. |
| 429 | rate_limit_exceeded | Slow down and retry. |
| 500 | internal_error | Retry. If it keeps happening, contact support. |
| 502, 503, 504 | upstream_error, upstream_unavailable, server_busy, model_not_available, upstream_timeout | Retry with backoff. You are not billed for failed requests. |
Limits
- 1,200 requests a minute per API key, and 2,400 a minute per IP address.
- The document and questions must fit the model's context length, listed as
context_lengthin GET /v1/models. - Up to 255 options per choice question.
Billing
- You pay per input token, at the price in GET /v1/models. Zuse writes no text, so there are no output tokens to pay for.
- Failed requests are not billed. Usage shows in the dashboard next to your chat API usage.
- Credits are bought in the dashboard, with the same 8% fee as the rest of the Bineric API.
Using the probabilities
- Set a threshold per question and send anything below it to a person. On our European suite, 75.7% of the 27B model's answers clear the threshold that keeps errors under 5%.
- Add a “none of these” option to choice questions whose answer may not be in the list. The model is trained to pick it when nothing fits.
- Routing, reading comprehension and entailment automate well. Keep legal interpretation, grammar judgements and questions that need world knowledge review-first.