Zuse API

Short, typed answers about any document, with how sure the model is. Hosted in the EU.

Quickstart

  1. Create an account at platform.bineric.com and copy an API key from API keys.
  2. Send a document as state and your questions as questions.

Base URL

bash
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"
]
}
}
}'

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.

bash
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 idUse it forPrice per 1M input tokens
zuse-27bHighest accuracy, for the decisions you automate.$0.75
zuse-9bFast and low cost, for routing at volume.$0.12

POST /v1/zuse

Answers every question about one document in a single pass.

FieldTypeDescription
modelstringOptional. A model id from the table above.
statestring, object or arrayThe document or record to decide about. JSON is passed as is; you do not need to flatten it.
questionsobjectAt least one question, keyed by an id you choose. The answers come back under the same ids.
json
{
"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

typecriteriaWhat you get
choiceObject 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.
noulOptional. Use instructions to state the yes/no question.noul: the probability that the answer is yes.
scoreArray 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.

json
{
"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

HeaderMeaning
x-bineric-modelThe model that answered.
x-bineric-hostingWhere 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.

bash
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.

StatusCodeWhat to do
400invalid_request, model_not_supportedFix the request. A chat model id was sent, or questions are missing.
401invalid_api_key, missing_api_keyCheck the key.
402insufficient_quotaAdd credits.
403payment_requiredThis model needs credit on the account. Add credits.
404model_not_foundUse 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.
429rate_limit_exceededSlow down and retry.
500internal_errorRetry. If it keeps happening, contact support.
502, 503, 504upstream_error, upstream_unavailable, server_busy, model_not_available, upstream_timeoutRetry 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_length in 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.