DEVELOPER GUIDE

API

Connect your application to JEV AI. Create a key, send a structured question, and read the result in your own code.

Let AI make your first call

Copy the full instruction into an AI coding assistant with terminal access. It includes this site’s URL, authentication, a sample request and result checks. Changing the question type below updates the instruction. Configure JEV_API_KEY in your execution environment first.

Preview the instruction

Use the JEV AI API to execute one example request and report the real result. Use your terminal or server-side HTTP tools; do not just explain the steps.

Base URL: https://jevai.info
Documentation: https://jevai.info/api
Model: typesafe/jev-1.13
Authentication: Authorization: Bearer <value of JEV_API_KEY>
Content-Type: application/json

1. Read JEV_API_KEY from the execution environment. If it is missing, ask me to configure it locally before continuing; never ask me to paste it into chat. Never print the key, include it in logs, or save it in frontend code. If you cannot execute HTTP requests, say so and provide runnable code instead of inventing a result.
2. GET https://jevai.info/api/jev/account?page=1 with the Bearer header. Check data.balance.ready, data.balance.pending, and data.balance.balance. A new request requires 32,000 available input tokens per question. If the service is unavailable, another operation is pending or the balance is insufficient, report that and stop. Do not purchase tokens or change account settings.
3. Generate a fresh UUID for requestId and send exactly one POST to https://jevai.info/api/jev/run with the following JSON (replace only requestId with the generated UUID):

{
"requestId": "123e4567-e89b-42d3-a456-426614174000",
"model": "typesafe/jev-1.13",
"state": "I was charged twice for my subscription. Please refund the duplicate payment.",
"questions": {
"decision": {
"type": "choice",
"instructions": "Which team should handle this support ticket?",
"criteria": {
"billing": "Payments, invoices and refunds",
"technical": "Errors, bugs and setup problems",
"other": "All other requests"
}
}
}
}

4. Read the HTTP status and JSON code/message. For a completed result, report data.id, data.status, data.result.answers, inputTokens and outputTokens. Query the account endpoint again for the remaining balance. The example's numbers are not a substitute for a real response.
5. A model call consumes purchased input tokens; output tokens are free. Do not repeat the example with a new UUID. On a timeout, inspect account history first. If a retry is necessary, reuse the exact original UUID and body, wait at least one second, and respect Retry-After. A reused UUID returns the saved record, including pending or released states; it does not restart a task. For needs_review or an unresolved operation, report the run ID and stop.

Return a concise execution summary. Keep the API key private.

01
Create your API key
Create a key in API Keys. Copy the full key with the copy button or by clicking its prefix. Older hash-only keys cannot be recovered; create a replacement if needed.
Manage API keys
02
Check your token balance
API requests use the same purchased token balance as the Playground. Create a key for free, then buy a token package before running a model request.
Buy tokens
03
Send your first request
Choose a question type and copy an example for your backend. Examples on this page do not run automatically or consume tokens.
View examples

Connection & authentication

Send Authorization: Bearer YOUR_API_KEY with every request. These examples call this site’s JSON API from your server; they do not use an OpenAI SDK or browser login cookies.

Base URL: https://jevai.info
Model: typesafe/jev-1.13

Terminal · environment variable

export JEV_API_KEY="YOUR_API_KEY"

Replace YOUR_API_KEY with your full key in your local terminal. Keep it in backend environment variables, never in frontend code or a public repository. This key works only on this site, not directly with the model provider.

Make a request

POST /api/jev/run

choice selects a category from 2–255 options. This example routes a support ticket to a team.

Use a Bash-compatible shell with curl 7.76+ and uuidgen. Set JEV_API_KEY in the same terminal first.

Shell

REQUEST_ID="$(uuidgen)"

curl --fail-with-body 'https://jevai.info/api/jev/run' \
  --request POST \
  --header "Authorization: Bearer $JEV_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "requestId": "'"$REQUEST_ID"'",
  "model": "typesafe/jev-1.13",
  "state": "I was charged twice for my subscription. Please refund the duplicate payment.",
  "questions": {
    "decision": {
      "type": "choice",
      "instructions": "Which team should handle this support ticket?",
      "criteria": {
        "billing": "Payments, invoices and refunds",
        "technical": "Errors, bugs and setup problems",
        "other": "All other requests"
      }
    }
  }
}'

Every new operation needs a new UUID requestId. For a retry, reuse the exact original requestId and payload. Only POST /api/jev/run runs the model and can consume tokens.

View an example response

Illustrative data, not a live result. code: 0 means the request was accepted; also check data.status. Read answers from data.result.answers when status is completed and result is not null. Repeated requests can return an in-progress or released record.

JSON

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "example-run-id",
    "status": "completed",
    "inputTokens": 180,
    "outputTokens": 24,
    "questionCount": 1,
    "elapsedMs": 850,
    "createdAt": "2026-09-28T12:00:00.000Z",
    "result": {
      "model": "typesafe/jev-1.13",
      "answers": {
        "decision": {
          "type": "choice",
          "choice": "billing"
        }
      },
      "usage": {
        "input_tokens": 180,
        "output_tokens": 24
      },
      "elapsedMs": 850
    }
  }
}

Request parameters

Field	Type / value	Description
requestId	UUID	Required. UUID used to identify one operation and prevent duplicate model runs when retrying the same payload.
model	typesafe/jev-1.13	Optional. Defaults to this model; other model names are not accepted.
state	string \| string[] \| object	Required. Shared context for all questions. Strings must contain 1–16,000 characters; an array can contain 1–100 such strings. JSON objects are also accepted.
questions	object	Required. 1–8 named questions. Names begin with an ASCII letter, contain only letters, digits or underscores, and are at most 64 characters.
questions.*.type	choice \| score \| noul	Required for each question. Select a type to see its example above.
questions.*.instructions	string	Required. Describe the decision explicitly in 1–16,000 characters.
questions.*.criteria	object \| string[]	choice: an object with 2–255 option descriptions (a description may be null). score: 2–10 ordered descriptions. noul: omit this field.

The complete JSON body must be at most 32 KiB. Extra top-level or question fields are rejected. API paths have no /zh locale prefix.

Check balance & request history

GET /api/jev/account

curl --fail-with-body 'https://jevai.info/api/jev/account?page=1' \
  --header "Authorization: Bearer $JEV_API_KEY"

This endpoint does not call the model. Read available tokens from data.balance.balance and reserved tokens from data.balance.reserved. data.history.items contains up to 20 requests per page; increment page while hasMore is true.

Open token usage

How tokens are charged

Each question reserves 32,000 input tokens before execution, so your available balance must cover that amount. Completed requests settle against actual input usage and release unused reservations. Output tokens are free. Reservations awaiting review stay locked until resolved.

Retries without duplicate charges

Allow at least one second between requests and run one operation at a time per account. After a timeout, check history and retry only the same UUID and unchanged body. Reusing a UUID returns the saved record; it does not restart a released task. Start a new task only after confirming the previous one was released. For needs_review or a stuck operation, contact support with the run ID; never send your API key.

Troubleshooting

Errors return a non-success HTTP status. In the JSON body, code is -1 and message contains the error code. Check both the HTTP status and the body.

HTTP	Error code	What to do
400	invalid_request	Check JSON structure, question criteria, UUID format and the 32 KiB body limit.
401	unauthorized	Use the full active API key in the Bearer header. A prefix, a deleted key or a provider key will not work.
402	insufficient_tokens	Buy tokens or wait for a previous reservation to be released. Check available and reserved balances.
403	invalid_origin	This is the browser-session origin check. Server integrations should send a valid Bearer key instead of browser cookies.
409	idempotency_conflict	The requestId already belongs to different input. Use the original input for a retry, or a new UUID for a genuinely new task.
409	request_pending / account_busy	Another operation is pending or the account is busy. Check history and retry later; do not run requests in parallel.
429	rate_limited	Wait for the Retry-After interval before retrying the same operation.
502 / 503	needs_review / upstream_rejected / service_unavailable / account_unavailable	Inspect history before retrying. needs_review requires support review; do not start a replacement request. For temporary service errors, try later.

Contact support