Scoring API

Beta. This reference describes the beta interface and may change.

Endpoint

POST https://api.spinf.com/v1/score
Authorization: Bearer ssk-...
Content-Type: application/json

POST https://api.spinf.com/v1/chat/completions accepts the same body, so the OpenAI SDKs work as they are: put the scoring block in extra_body. Its response is the same, plus "choices": [].

Create API keys in the console. Keep them on your servers: the scoring API refuses API keys sent from a browser. To try calls without code, use the playground.

How a question works

A question is a template: text read after your content, ending where the answer goes, marked {?}. You list the options (the answers) to score at that point, and spinf returns the probability of each one.

template: "\n\nWill {commodity} prices rise or fall next month?\nAnswer:{?}"
options:  [" rise", " fall"]

• {name} is a placeholder, filled from combinations: one template asks many questions (crude oil, natural gas, …). The content is read once and shared by every question.
• {?} must end the template: the model reads what comes right after it.
• Options are written as they would follow the template, usually with a leading space (" rise"). Don't put a space before {?} as well: the two spaces tokenize badly and the request is rejected (option_boundary).
• Write {{ and }} for literal braces.

Writing good templates

• Content first. The template is read after the content: start it with a line break ("\n\n…") and end it right where the answer goes.
• Short, distinct answers. One word each works best (" rise" / " fall"), written as the model would continue the template.
• The template is part of the question. Rewording it changes what the model is asked, and so p. Naming the answers ("… Answer rise or fall.") lowers the residual, but it can also move the lift. Check a template on a few examples you know the answer to before you rely on it, and keep it fixed once you compare scores over time.
• Skip the floor you already have. The floor depends only on the question, so you can keep the floor_p of an earlier call and send "empty_floor": false. Floors from different calls typically agree to within a few hundredths (reads packed in one call move slightly together); recompute them when system_fingerprint changes.

Request, one content

{
  "model": "spinf-12b",
  "messages": [
    { "role": "user", "content": [ { "type": "text", "text": "OPEC+ agreed on Sunday to extend its output cuts…" } ] }
  ],
  "scoring": {
    "queries": [
      {
        "id": "direction",
        "template": "\n\nWill {commodity} prices rise or fall next month?\nAnswer:{?}",
        "options": [" rise", " fall"],
        "combinations": [ { "commodity": "crude oil" }, { "commodity": "natural gas" } ]
      },
      {
        "id": "topic",
        "template": "\n\nThe article is mainly about{?}",
        "options": [" oil", " natural gas", " coal"]
      }
    ]
  }
}

Request, many contents

Send inputs instead of messages. The queries in scoring.queries are shared: every input is scored with all of them, or only those listed in its query_ids. An input can add its own queries (same shape). Packing many contents into one call is cheaper: one per-call minimum, and the empty floor of a shared question is computed once.

Here sector asks both articles, and dir asks Apple's input a grid ("all": every company × metric):

{
  "model": "spinf-12b",
  "inputs": [
    { "id": "apple",
      "messages": [ { "role": "user", "content": "Apple reported record iPhone revenue while Mac margins slipped." } ] },
    { "id": "exxon",
      "messages": [ { "role": "user", "content": "Exxon cut output after OPEC+ extended its supply cuts." } ],
      "query_ids": ["sector"] }
  ],
  "scoring": {
    "queries": [
      { "id": "sector",
        "template": "\n\nThis article is mainly about the{?}",
        "options": [" technology sector", " energy sector", " banking sector"] },
      { "id": "dir",
        "template": "\n\nWill {company}'s {metric} rise or fall next quarter?\nAnswer:{?}",
        "options": [" rise", " fall"],
        "combinations": "all",
        "values": { "company": ["Apple"], "metric": ["revenue", "margin"] } }
    ]
  }
}

An input with its own question:

{ "id": "a3", "messages": [ … ],
  "queries": [ { "id": "own", "template": "\n\nIs this good news for markets?\nAnswer:{?}", "options": [" yes", " no"] } ] }

Fields

Limits: up to 10,000 questions (templates × combinations) per content, a request body up to 2 MB, and up to 2M processed tokens per request.

Images, video and audio (preview, on request)

Preview. Image, video and audio input is in preview and not generally available: we enable it per account on request (contact us). Formats, limits and scores may change.

Content can include images and audio besides text, as OpenAI content parts. They are shared by every question of the input, like text:

{ "role": "user", "content": [
  { "type": "text", "text": "The chart in this filing:" },
  { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…", "detail": "auto" } },
  { "type": "text", "text": "Listen to this clip from the earnings call." },
  { "type": "input_audio", "input_audio": { "data": "UklGRiQ…", "format": "wav" } }
] }

• Where they are read: images are read first, before the text of the content, where the model reads them best; audio stays where you put it, so a short text part before it can introduce it.
• Images: data: URLs only (png, jpeg, webp, gif); we never fetch a remote URL. detail sets the image's token budget: low up to 70, auto (default) up to 280, high up to 1,120 tokens, depending on the aspect ratio, plus 2 marker tokens per image (a square image at auto is 258 tokens in all).
• Audio: base64 in wav, mp3, flac, ogg or m4a; 1 token per 40 ms (750 per 30 s), plus 2 marker tokens per 30 s segment.
• Video: sent as frames you sample from the video, each with its time, read in order where you put them; every question shares the frames. Both models read video. The format is shared with accounts in the preview.
• Media count as content tokens: billed like text, and within the 4,096-token content limit of an input.
• The request body stays under 2 MB: about 30 s of 16 kHz WAV, much longer compressed audio, or a 1–2 MP JPEG.
• Models: spinf-12b reads images and audio; spinf-31b (on request) reads images but not audio.
• Errors: 403 media_not_allowed (not enabled for your account), 400 media_not_supported (audio sent to spinf-31b), 400 invalid_media (the image or audio could not be decoded), 400 unsupported_content (a remote image URL, or another part type).

Tips. Questions about audio read better when a short text part introduces the clip. Yes/no questions about genre-like attributes of audio are weak: ask with a set of options instead (" jazz", " rock", " classical", …).

Prompt-packs

Add a ready-made, calibrated set of questions, like content moderation, with scoring.packs: it is scored on the same content in the same call as your own queries. See Prompt-packs.

"scoring": {
  "packs": [ { "id": "spinf/moderation" } ],
  "queries": [ … your questions … ]
}

Response

The response of the "many contents" request above (a live call to spinf-12b):

{
  "id": "req_01M3B149VXXH39YGQX5CEW3SY5",
  "object": "score",
  "created": 1790297909,
  "model": "spinf-12b",
  "system_fingerprint": "fp_87dd99dbf6",
  "results": [
    { "input_id": "apple",
      "queries": [
        { "id": "sector",
          "combinations": [
            { "values": {},
              "options": [
                { "text": " technology sector", "logprob": -8.439295, "p": 0.933484, "floor_p": 0.019076 },
                { "text": " energy sector", "logprob": -12.483436, "p": 0.016359, "floor_p": 0.41683 },
                { "text": " banking sector", "logprob": -11.363065, "p": 0.050157, "floor_p": 0.564094 } ],
              "residual": 0.999768, "floor_residual": 0.999993 } ] },
        { "id": "dir",
          "combinations": [
            { "values": { "company": "Apple", "metric": "revenue" },
              "options": [
                { "text": " rise", "logprob": -1.776795, "p": 0.801008, "floor_p": 0.525006 },
                { "text": " fall", "logprob": -3.169399, "p": 0.198992, "floor_p": 0.474994 } ],
              "residual": 0.788792, "floor_residual": 0.861084 },
            { "values": { "company": "Apple", "metric": "margin" },
              "options": [
                { "text": " rise", "logprob": -2.467582, "p": 0.564992, "floor_p": 0.595533 },
                { "text": " fall", "logprob": -2.729028, "p": 0.435008, "floor_p": 0.404467 } ],
              "residual": 0.849928, "floor_residual": 0.84605 } ] } ] },
    { "input_id": "exxon",
      "queries": [
        { "id": "sector",
          "combinations": [
            { "values": {},
              "options": [
                { "text": " technology sector", "logprob": -10.925335, "p": 0.010058, "floor_p": 0.019076 },
                { "text": " energy sector", "logprob": -6.343364, "p": 0.982723, "floor_p": 0.41683 },
                { "text": " banking sector", "logprob": -11.256995, "p": 0.007219, "floor_p": 0.564094 } ],
              "residual": 0.998211, "floor_residual": 0.999993 } ] } ] }
  ],
  "warnings": [],
  "usage": {
    "prompt_tokens": 112, "completion_tokens": 0, "total_tokens": 112,
    "prompt_tokens_details": { "content_tokens": 22, "query_tokens": 50, "floor_tokens": 40 },
    "billed_tokens": 1000
  }
}

The sector floor is the same for both inputs: it was computed once. The article lifts " rise" for Apple's revenue from 0.53 to 0.80; for its margin, p (0.56) sits near the floor (0.60), so the content says little about it. The sector residuals are close to 1 because its answers have two tokens each; p still separates them clearly.

Response headers: X-Request-Id, X-Spinf-Concurrency-Limit, X-Spinf-Concurrency-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining.

Billing

Each call is billed billed_tokens × price. A request needs at least $0.10 of credit to start, and its cost is charged when the scores are returned; a failed or refused request is not charged. Requests running at the same time can take the balance slightly below zero; new requests are then refused until you add credit.

Errors

Every error has the same shape:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_template",
    "message": "scoring.queries.0.template: {?} must end the template: text after it would never be read.",
    "param": "scoring.queries.0.template"
  },
  "request_id": "req_01J8ZB2Q6X4M3T"
}

Prompt-pack errors (unknown_pack, pack_media_not_supported, pack_conflict, …) are listed in Prompt-packs. Quote the request_id when you contact us about a request.

Other endpoints

• GET https://api.spinf.com/v1/models (no key): the models, the open-weights model each is based on (base_model), their other accepted names (aliases), status, price and minimum per call.
• GET https://api.spinf.com/v1/packs (no key): the prompt-packs, their categories, default thresholds and decision modes. GET https://api.spinf.com/v1/packs/{id} (API key) downloads a pack file.
• GET https://api.spinf.com/v1/account (API key): the key's account: balance, concurrency and rate limits, models enabled.

Models

Both models are Google DeepMind's open-weights Gemma 4 models, optimized by spinf for scoring at scale.

The spinf id and the standard names are interchangeable, in any case: the response's model is the name you sent, and usage and billing are the same. Gemma is a trademark of Google LLC; the Gemma 4 weights are released under the Apache 2.0 license.