> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jev

> TypeSafe Jev decision model: return choices, scores, yes/no probabilities, or image bounding boxes with confidence

## Introduction

Jev is TypeSafe's **System One decision model**. It **does not generate text**. Instead, it answers questions with a defined answer space (`questions`) about the content you provide (`state`), returning structured results your code can use directly:

* **Choice (`choice`)**: Select one of your options, such as which department should handle a support ticket.
* **Score (`score`)**: Rate content against your levels, such as customer anger: 0 calm / 1 dissatisfied / 2 angry.
* **Yes/no (`noul`)**: Return the probability of yes, such as whether the customer is requesting a refund.
* **Bounding box (`box`)**: Locate a described target in an image and return its four edges, such as scratches on a car.

Ask multiple questions in one request. The content is read once and each question is evaluated independently. Choice, Score, and Box answers include confidence; Noul answers return a probability. Use these decisions for ticket routing, moderation, sentiment scoring, intent detection, agent tool-call checks, and model routing.

> [!NOTE]
>
> The request structure and successful response fields follow TypeSafe's [System One API](https://docs.typesafe.ai/api/system-one). The platform may wrap error responses; see [Error handling](#error-handling).

> [!WARNING]
>
> Jev **does not support** conversational endpoints such as OpenAI's `/v1/chat/completions` or `/v1/responses`. Call it through `/v1/systemone` below. It does not write replies, generate code, or explain its reasoning.

## Authentication

**Authorization** `string` *required*

Bearer token, e.g. `Bearer sk-xxxxxxxxxx`

**Content-Type** `string` *required*

`application/json`, or `multipart/form-data` for multipart image uploads. See [Multipart image uploads](#multipart-image-uploads).

**TypeSafe-Danger-Zone-Images** `string`

Set to `true`. The official specification **requires** this header for requests containing images (`assets`) or Box questions (`box`).

**TypeSafe-Danger-Zone-Long-Context** `string`

Set to `true` to enable long context and raise the context limit from 64k to 262k. See [Context length](#context-length).

Create an API key on the platform's API keys page. Do not embed keys in frontend code, public repositories, or client installation packages.

## Model information

| Model name | Description | Question types | Input |
| - | - | - | - |
| `jev-latest` | Latest stable release; currently points to `jev-1.14.0` | choice / score / noul / box | Text, images |
| `jev-preview` | Latest release, including previews; currently also points to `jev-1.14.0` | choice / score / noul / box | Text, images |
| `jev-1.14.0` | Pinned Jev 1.14 version | choice / score / noul / box | Text, images |
| `jev-1.13.0` | Pinned Jev 1.13 version | choice / score / noul (**no box support**) | Text, images |

* `jev-latest` and `jev-preview` are aliases that move when TypeSafe releases new versions, so answers may change. The response's `model` field identifies the version that answered.
* If you have tuned confidence thresholds for a version, use its pinned model ID and switch only after evaluating the new version.

| Item | Description |
| - | - |
| Endpoint type | Synchronous response |
| Streaming | Not supported |
| Questions per request | No separate limit, provided the request fits the context limits |
| Image formats | PNG, JPEG |
| Billing | Input tokens only; output tokens are free |

## Endpoint

```http theme={null}
POST https://api.gravitex.ai/v1/systemone
```

## Request parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Model name; see [Model information](#model-information) |
| `state` | string / object / array | Yes | Content all questions evaluate; see [state](#state) |
| `questions` | object | Yes | At least one named question; keys are your question names and values are question definitions. See [questions](#questions) |
| `assets` | object | No | Images keyed by placeholders, with image definitions as values. See [assets](#assets) |

> [!NOTE]
>
> Jev has no sampling parameters such as `temperature` or `max_tokens`, and no output length setting is needed.

### state

Provide the content to evaluate in any of three forms:

* **String**: Text such as a customer message, support ticket, or complete contract.
* **Object**: Structured data such as `{"subject": "Duplicate charge", "message": "Please help"}`. Use it to combine messages, order records, and business rules.
* **Array**: Multiple pieces of text, such as a conversation history.

```json theme={null}
"state": {
  "customer_message": "My order was charged twice, and nobody has addressed it for three days",
  "orders": [{ "id": "A1024", "charged_times": 2 }],
  "refund_policy": "Duplicate charges are eligible for a full refund of the extra payment"
}
```

### questions

A collection of named questions. The response returns answers under the same names in `answers`. Each value defines a question:

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Question type: `choice`, `score`, `noul`, or `box` |
| `instructions` | string / object / array | No | What the model should evaluate |
| `criteria` | object / array | Depends on type | Options or scoring levels; see the table below |

| Question type | `criteria` format | Requirements |
| - | - | - |
| `choice` | Object: `{option_name: option_description}` | **Required**, 1–255 options. A description may be empty; the option is then interpreted by name alone. |
| `score` | Array of level descriptions, ordered from low to high | **Required**, 1–10 levels; at least 2 recommended. The first level is 0, increasing by 1. |
| `noul` | Object: `{"true": "What counts as yes", "false": "What counts as no"}` | Optional; provide at least `instructions` or `criteria`, otherwise the upstream service returns an error. |
| `box` | Omit | Only `jev-1.14.0` and aliases pointing to it support Box. An image and `TypeSafe-Danger-Zone-Images: true` are required. |

```json theme={null}
"questions": {
  "department": {
    "type": "choice",
    "instructions": "Which department should handle this ticket?",
    "criteria": {
      "billing": "Payments, charges, refunds",
      "technical": "Feature failures, errors",
      "sales": "Presales questions, plan upgrades"
    }
  },
  "anger": {
    "type": "score",
    "instructions": "How angry is the customer?",
    "criteria": ["Calm", "Somewhat dissatisfied", "Very angry"]
  },
  "wants_refund": {
    "type": "noul",
    "instructions": "Is the customer requesting a refund?",
    "criteria": { "true": "Explicitly requests money back", "false": "Does not request a refund" }
  }
}
```

> [!NOTE]
>
> * Questions are independent. Each is evaluated against `state` without seeing the other answers.
> * Specific option and level descriptions make decisions more consistent. Avoid overlapping options.

### assets

A collection of images keyed by your **placeholders** (a new UUID per image is recommended). A placeholder anywhere in a string in `state`, question `instructions`, or `criteria` is replaced with the corresponding image.

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | No | Must be `image` when supplied; explicitly included in the examples |
| `format` | string | Required with `data_base64` | `png`, `jpg`, or `jpeg`; the actual format is detected from the image bytes |
| `data_base64` | string | One of two methods | Base64 image data **without** a `data:image/...;base64,` prefix |
| `part` | string | One of two methods | Name of the image part in a multipart request. When set, `data_base64` is ignored. |

The following example uses a **280 × 280** PNG with a red rectangle on white. It is also used in the image and Box examples below. Do not replace it with a placeholder image below the minimum dimensions.

```json theme={null}
"state": "photo",
"assets": {
  "photo": {
    "type": "image",
    "format": "png",
    "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
  }
}
```

> [!WARNING]
>
> The official specification requires `TypeSafe-Danger-Zone-Images: true` for requests with `assets`. Images and Box questions are early features; request formats, answers, and limits may change between versions.

### Image limits

Images must satisfy all of the following [official limits](https://docs.typesafe.ai/images#limits). Images outside the dimension limits are not resized automatically; the whole request fails:

| Item | Limit |
| - | - |
| Format | Still PNG or JPEG; animated PNG is not supported |
| Width and height | **280–1568 pixels** each, inclusive |
| Total pixels | 78,400–2,458,624 |
| Single file | At most 16 MiB; Base64 is measured after decoding |
| Request body | At most 32 MiB, including JSON, Base64, or multipart overhead |
| All images / expanded request | Each at most 32 MiB; repeated image references count again toward the expanded size |

Every asset must be referenced in `state`, `instructions`, or `criteria`. Undersized images, invalid formats, and unreferenced assets typically return 400. Exceeding file, dimension, or request size limits may return 413.

### Multipart image uploads

For large or multiple images, upload the original files with `multipart/form-data` instead of Base64:

* The first part must be named `request` and contain the JSON request body (`Content-Type: application/json`).
* Each image follows in its own part. Part names must be unique, nonempty, and referenced by an asset's `part` field.

```bash theme={null}
curl --location 'https://api.gravitex.ai/v1/systemone' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'TypeSafe-Danger-Zone-Images: true' \
  --form 'request={"model":"jev-latest","state":"photo","questions":{"damage":{"type":"noul","instructions":"Are there visible scratches on the car?"}},"assets":{"photo":{"type":"image","part":"img1"}}};type=application/json' \
  --form 'img1=@./car.jpg;type=image/jpeg'
```

### Context length

Every request must fit both limits:

| Limit | Default | With long context |
| - | - | - |
| Per request (`state` + all questions) | 64k tokens | 262k tokens |
| Per question (`state` + that question) | 32k tokens | 262k tokens |

* Exceeding the limit returns an upstream 400 error with `max_tokens_exceeded`.
* For long contracts or conversation histories, send `TypeSafe-Danger-Zone-Long-Context: true`. Long context has the **same per-token price**, but is slower and slightly less accurate. Enable it only when needed.

## Usage examples

> [tab] Choice
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-latest",
>     "state": "Help! My payouts have been failing for 3 days.",
>     "questions": {
>       "department": {
>         "type": "choice",
>         "instructions": "Which team should handle this?",
>         "criteria": {
>           "billing": "Payments, invoicing, refunds",
>           "technical": "Bugs, outages, integrations",
>           "sales": "Pricing, upgrades, new accounts"
>         }
>       }
>     }
>   }'
> ```

> [tab] Multiple questions
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-latest",
>     "state": "My order was charged twice and nobody has addressed it for three days. Refund me or I will file a complaint!",
>     "questions": {
>       "department": {
>         "type": "choice",
>         "instructions": "Which department should handle this ticket?",
>         "criteria": { "billing": "Payments, charges, refunds", "technical": "Feature failures, errors", "sales": "Presales questions, plan upgrades" }
>       },
>       "anger": {
>         "type": "score",
>         "instructions": "How angry is the customer?",
>         "criteria": ["Calm", "Somewhat dissatisfied", "Very angry"]
>       },
>       "wants_refund": { "type": "noul", "instructions": "Is the customer requesting a refund?" }
>     }
>   }'
> ```

> [tab] Structured state
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-1.14.0",
>     "state": {
>       "customer_message": "My order was charged twice",
>       "orders": [{ "id": "A1024", "charged_times": 2 }],
>       "refund_policy": "Duplicate charges are eligible for a full refund of the extra payment"
>     },
>     "questions": {
>       "refund_allowed": { "type": "noul", "instructions": "Under the refund policy, should this order receive a refund?" }
>     }
>   }'
> ```

> [tab] Image evaluation
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Images: true' \
>   --data '{
>     "model": "jev-latest",
>     "state": "photo",
>     "questions": {
>       "has_red": { "type": "noul", "instructions": "Does the image contain something red?" }
>     },
>     "assets": {
>       "photo": {
>         "type": "image",
>         "format": "png",
>         "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
>       }
>     }
>   }'
> ```

> [tab] Bounding box
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Images: true' \
>   --data '{
>     "model": "jev-1.14.0",
>     "state": "photo",
>     "questions": {
>       "red_rectangle": { "type": "box", "instructions": "Locate the red rectangle." },
>       "has_rectangle": { "type": "noul", "instructions": "Is there a red rectangle in the image?" }
>     },
>     "assets": {
>       "photo": {
>         "type": "image",
>         "format": "png",
>         "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
>       }
>     }
>   }'
> ```
>
> Box questions have no "not found" answer: they return four edges even when the target is absent. To check whether it exists, add a Noul question to the same request, as above.

> [tab] Long context
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Long-Context: true' \
>   --data '{
>     "model": "jev-latest",
>     "state": "<Full text of a long contract>",
>     "questions": {
>       "has_termination_clause": {
>         "type": "noul",
>         "instructions": "Does the contract include a clause allowing either party to terminate the agreement early?"
>       }
>     }
>   }'
> ```

> [tab] Python
>
> ```python theme={null}
> import requests
>
> # Install the dependency first: pip install requests
> resp = requests.post(
>     "https://api.gravitex.ai/v1/systemone",
>     headers={"Authorization": "Bearer sk-xxxxxxxxxx"},
>     json={
>         "model": "jev-latest",
>         "state": "My order was charged twice. Refund me or I will file a complaint!",
>         "questions": {
>             "wants_refund": {"type": "noul", "instructions": "Is the customer requesting a refund?"},
>         },
>     },
>     timeout=60,
> )
> resp.raise_for_status()
> answer = resp.json()["answers"]["wants_refund"]
> if answer["noul"] >= 0.8:
>     print("Route to the refund workflow")
> ```

## Successful response

```json theme={null}
{
  "model": "jev-1.14.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1,
      "probabilities": { "billing": 1, "technical": 0, "sales": 0 }
    },
    "anger": {
      "type": "score",
      "score": 1.87,
      "confidence": 0.8,
      "legend": { "0": "Calm", "1": "Somewhat dissatisfied", "2": "Very angry" },
      "probabilities": { "0": 0, "1": 0.13, "2": 0.87 }
    },
    "wants_refund": {
      "type": "noul",
      "noul": 0.97
    }
  },
  "usage": {
    "input_tokens": 443,
    "output_tokens": 71
  }
}
```

**Box answer**

```json theme={null}
{
  "type": "box",
  "box": { "top": 0.2, "bottom": 0.66, "left": 0.19, "right": 0.68 },
  "confidence": 0.9
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `model` | string | Version that answered; an alias request returns a versioned ID such as `jev-1.14.0` |
| `answers` | object | Answers keyed by the question names in the request |
| `answers.*.type` | string | Question type: `choice`, `score`, `noul`, or `box` |
| `answers.*.choice` | string | Choice: option with the highest probability |
| `answers.*.score` | number | Score: probability-weighted expected level; may fall between integer levels, e.g. `1.87` |
| `answers.*.noul` | number | Probability of yes, 0–1. Near 1 favors yes; near 0 favors no; near 0.5 indicates uncertainty. |
| `answers.*.box` | object | `top`, `bottom`, `left`, and `right` edges as fractions of image height or width, 0–1, measured from the top-left corner |
| `answers.*.confidence` | number | Confidence for Choice, Score, and Box, 0–1; higher means more certain. Box confidence may be `null`. |
| `answers.*.probabilities` | object | Choice: probability per option. Score: probability per level, keyed by its index. Totals approximately 1. |
| `answers.*.legend` | object | Score: mapping of level indices to descriptions |
| `usage.input_tokens` | integer | Input token count; **basis for billing** |
| `usage.output_tokens` | integer | Output token count; currently **not billed** |

> [!NOTE]
>
> **Using confidence**: Probabilities and confidence are calibrated and can support automated decision thresholds. For example, automatically process `noul ≥ 0.8`, send `0.2 ~ 0.8` for human review, and allow `< 0.2`. Tune thresholds on a set of manually labeled examples.

## Billing

**Formula**: Cost per request = `usage.input_tokens` / 1,000,000 × input price

| Model | Input price (USD / million tokens) | Output |
| - | - | - |
| `jev-1.14.0` | 0.042 | Free |
| `jev-1.13.0` | 0.042 | Free |
| `jev-latest` | 0.042 | Free |
| `jev-preview` | 0.042 | Free |

* These are official base prices. Actual charges also apply the multiplier for the API key's group. Refer to the prices shown in the model marketplace.
* Input tokens include `state`, all question instructions, options, and level descriptions, plus image tokens when images are included.
* `output_tokens` is informational and currently not billed.
* Long context keeps the same per-token price and only permits longer inputs.

**Example**: If the multiple-question request above returns `input_tokens: 443`, the cost is 443 / 1,000,000 × 0.042 ≈ **USD 0.0000186**, or about USD 0.19 for 10,000 such requests.

## Error handling

Failed requests return a JSON error object. The platform may wrap upstream errors: `message` may contain a specific reason or only `openai_error`. Do not rely on this field alone to identify the cause. Example error format:

```json theme={null}
{
  "error": {
    "message": "max_tokens_exceeded",
    "type": "bad_response_status_code",
    "param": "",
    "code": "bad_response_status_code"
  }
}
```

> [!NOTE]
>
> Official API validation failures may return 422, while a gateway may return 400 with an `error` wrapper. Check the HTTP status first, then read the error fields. Do not assume every gateway preserves the official `detail` structure or specific error messages.

Common issues:

| Issue | Suggested action |
| - | - |
| Invalid API key | Check `Authorization: Bearer ...` |
| Missing `model` | Include `model` in the JSON body or the multipart `request` part |
| Missing `state` / `questions` | Both are required; `questions` must contain at least one question |
| Choice error | Supply `criteria` as an object with 1–255 options |
| Score error | Supply `criteria` as an array with 1–10 levels |
| Noul error | Supply at least one of `instructions` or `criteria` |
| Unknown question type | `type` must be `choice`, `score`, `noul`, or `box` |
| Image error | Send `TypeSafe-Danger-Zone-Images: true`; both dimensions must be 280–1568 pixels. Use still PNG / JPEG and Base64 without a `data:image/...;base64,` prefix. See [Image limits](#image-limits). |
| Box error | Use `jev-1.14.0` or an alias currently pointing to it, with an image and the Images header |
| `openai_error` | No specific cause was exposed. Check image dimensions, model/type compatibility, required fields, and context length. If needed, contact the platform with the request time and request ID. |
| `max_tokens_exceeded` | Reduce `state` or send `TypeSafe-Danger-Zone-Long-Context: true` |
| `/v1/chat/completions` fails | Jev is not a chat model; use `POST /v1/systemone` |

## Official references

* [System One API](https://docs.typesafe.ai/api/system-one)
* [Models, aliases, and context length](https://docs.typesafe.ai/models)
* [Image uploads and limits](https://docs.typesafe.ai/images)
* [Box questions and confidence](https://docs.typesafe.ai/primitives/box)
* [Request rules and errors](https://docs.typesafe.ai/api/errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.