Skip to content
SONOEDocs
EspañolESConsole

Migrate from Jev

Sonoe implements the same HTTP API as TypeSafe's Jev: the same endpoint, the same questions and the same answers. Code written for Jev moves to Sonoe by changing two settings.

The short version

export TYPESAFE_BASE_URL="https://api.sonoeai.com"
export TYPESAFE_API_KEY="sk_sonoe_..."   # a key from the Sonoe console

That's it. The official TypeSafe SDKs read both variables, so they send the same requests to Sonoe and get answers they understand. We test them against Sonoe as they are:

SDKVersion testedWhat we checked
typesafe-sdk (Python)0.7.5system_one sync and async, nouls / choices / scores, request_id, models.list(), zstd-compressed bodies, 401 and 422 errors
@typesafe-ai/sdk (JavaScript)0.7.0systemOne, withResponse(), models.list(), zstd-compressed bodies

If you call the HTTP API directly, change the host from api.typesafe.ai to api.sonoeai.com and the key. The path (POST /v1/systemone), the body and the answers stay the same.

Model names

You don't need to change the model field. Sonoe accepts Jev's names as aliases of its own current model:

You sendSonoe uses
jev-latest (the SDKs' default)sonoe-latest
jev-previewsonoe-preview
any jev-1.x.y, such as jev-1.13.0sonoe-latest
sonoe-latest, sonoe-preview, sonoe-1.1.0Sonoe 1.1

The answer's model field tells you what actually answered: sonoe-1.1.0. Any other name returns 404. When you're ready, set TYPESAFE_DEFAULT_MODEL=sonoe-latest (or defaultModel in the JS client) so your logs say what they mean.

What stays the same

  • POST /v1/systemone with state, model and questions; GET /v1/models returns { "models": [...] }.
  • Authorization: Bearer <key>.
  • Noul, Choice and Score questions, with instructions and criteria as strings, objects or arrays.
  • Answers: noul; choice + probabilities + confidence; score + legend + probabilities + confidence. Answers come back under the question ids you chose.
  • usage.input_tokens and usage.output_tokens.
  • Bodies compressed with Content-Encoding: zstd (what the SDKs send from 1 KiB on) or gzip.
  • An x-typesafe-request-id header on every response.
  • Status codes: 401 for a bad key, 422 for an invalid question (with the field's path), 429 when you're over a limit, with Retry-After so the SDKs wait the right time.

What's different

JevSonoe
Images and Box questionsSupported (preview)Not supported: 422. Sonoe reads text only.
Context64k tokens per requestSonoe reads up to 256 tokens for each pair of (state + question, option). A longer state is cut at the end.
Request bodyUp to 32 MiBUp to 64 KiB (after decompression), or 413.
Questions per requestNo fixed limitUp to 64.
Choice optionsUp to 2552 to 255.
Score levelsUp to 102 to 10.
usage.input_tokensTokens readTokens read: the state and question are read once per option, so many options or a long state cost more.
usage.output_tokensSmallAlways 0.
Long context headerTypeSafe-Danger-Zone-Long-ContextNot available; the header is ignored.
ConfidenceDerived from the probabilities1 − normalized entropy of the probabilities: 0 = no idea, 1 = certain. Comparable across 2 or 200 options.
Error messagesEnglishEnglish by default; send Accept-Language: es, pt or fr to get them in that language.
Error bodyJSONerror.type and error.message, plus detail (FastAPI style). Both SDKs read them.

A few smaller details:

  • Missing or null instructions are accepted: a Noul then uses its criteria; a Choice or Score asks which option or level fits best.
  • A Noul's criteria.true and criteria.false are read as part of the question ("Yes means: …", "No means: …").
  • Unknown top-level fields are ignored.

Check accuracy on your data

Sonoe 1.1 is a small multilingual model (a 118M-parameter cross-encoder based on multilingual-e5-small). It's fast and calibrated, but it's sensitive to wording in ways a larger model isn't. For example, on the state "I was charged twice. Please help ASAP.":

  • "Is this about billing?" scored low, well under 0.5.
  • "Is this about a payment or a charge?" scored about 0.97.

So, before you switch:

  1. Take a few hundred real requests you already know the right answer to.
  2. Send them to Sonoe (only the base URL changes) and compare with your labels and with Jev.
  3. Where Sonoe is wrong, try plainer words in instructions, and give every Choice option a short description in criteria instead of null.
  4. Look at confidence on the misses: often you can route low-confidence answers to a person or a fallback instead of trusting them.

Checklist

  • Create an account and a key at sonoeai.com.
  • Set TYPESAFE_BASE_URL=https://api.sonoeai.com and TYPESAFE_API_KEY=sk_sonoe_… (or change the host and key in your HTTP client).
  • Remove images and Box questions, or keep those requests on Jev.
  • Keep each state short: Sonoe reads up to 256 tokens per option.
  • Keep bodies under 64 KiB and requests under 64 questions.
  • Compare accuracy on your own labeled data.
  • Check your quota and per-minute limit in Errors and limits.
  • Optionally set the default model to sonoe-latest.