Start here
Jev API quickstart with OmniaKey
An independent guide by Jev AI · Reviewed · 阅读中文版
A Jev request asks a narrow question about a supplied state and returns a typed answer. This quickstart uses OmniaKey's dedicated Jev endpoint to check a synthetic input, so you can understand authentication and the response before adding business data.
You need an OmniaKey account that can access Jev, an API key and available account quota. Jev AI is an independent tutorial and playground; accounts, model availability and charges are managed by OmniaKey. Opening this guide does not make an API call.
What you will learn
- Use POST /v1/alpha/search with model, state and questions.
- Keep the key in your terminal or server environment.
- Read answers by question ID; do not expect chat messages.
On this page
1. Prepare an OmniaKey key
Open OmniaKey's key dashboard from the button on this page. Sign in or register if needed, then create a key scoped to the models and budget you intend to use. Check the account's current model access, balance and supported regions before running the example.
Set OMNIAKEY_API_KEY in the environment of the terminal running the example. It is a variable name, not a credential supplied by this guide. Do not put the real value in a public repository, a browser bundle or a NEXT_PUBLIC variable. In a deployed application, read it on your server from the host's secret settings.
2. Understand the three request fields
Use the dedicated Jev route rather than a chat-completions route. The request below uses the jev-latest alias and asks whether a short synthetic statement describes an integration test. You can change the state without changing how your application reads the answer.
Give each question a stable ID. Here, is_test is the ID your program will look up in answers. Changing that ID changes the response lookup, even if the natural-language question stays the same.
| Field | What to provide |
|---|---|
| model | jev-latest, or an available version you have tested |
| state | The text or structured context to evaluate |
| questions | Named questions with a supported type and instructions |
3. Run one request, then inspect it
Use curl in a shell or save the Node.js example below as jev-example.mjs. Node.js 20 or newer provides the fetch and timeout APIs used here. Both examples send the same JSON directly to OmniaKey; they do not require installing a Jev SDK.
The examples stop waiting after 25 seconds and do not automatically retry. A timeout means the client stopped waiting; it does not prove that the upstream request was never processed. Check provider usage before repeating an expensive batch.
For a visual workflow, open the custom Jev preset, replace its JSON with this example's model, state and questions, and run with your own key. The default custom preset contains a different refund-review example; the full request remains editable.
4. Separate a working connection from a useful decision
A recorded Jev AI integration check on September 20, 2026 returned HTTP 200, model jev-1.13.0, 402 input tokens and 62 output tokens. That separate synthetic test exercised Choice, Score and Noul and took about 1.48 seconds. It is a historical connectivity result, not a latency promise or a test of the business examples in these guides.
After your own request succeeds, record the resolved model version and inspect answers and usage. Test several inputs with known expected labels before connecting the result to your application. If reproducibility matters, verify the available versioned model and pin it after evaluation rather than relying indefinitely on a moving alias.
Request and code examples
Create an API key in OmniaKey and set OMNIAKEY_API_KEY in your terminal or server environment. The curl example requires curl 7.76 or newer for --fail-with-body; the JavaScript example requires Node.js 20 or newer. Use synthetic inputs. Requests use your account balance; check OmniaKey for current pricing and availability.
Save the JavaScript as jev-example.mjs, then run node jev-example.mjs. Keep the key out of frontend code and Git. Example inputs stay in English to match the playground presets; evaluate other input languages separately.
curl
curl --fail-with-body --max-time 25 'https://api.omniakey.com/v1/alpha/search' \
-H "Authorization: Bearer ${OMNIAKEY_API_KEY}" \
-H 'Content-Type: application/json' \
--data '{
"model": "jev-latest",
"state": "This is a synthetic integration test. No external action is requested.",
"questions": {
"is_test": {
"type": "noul",
"instructions": "Is the supplied state describing an integration test?"
}
}
}'Show the complete Node.js example
Node.js 20+
// Node.js 20+. Save as jev-example.mjs and run: node jev-example.mjs
// Set OMNIAKEY_API_KEY in the server/terminal environment first.
const key = process.env.OMNIAKEY_API_KEY;
if (!key) throw new Error("Set OMNIAKEY_API_KEY before running.");
const body = {
"model": "jev-latest",
"state": "This is a synthetic integration test. No external action is requested.",
"questions": {
"is_test": {
"type": "noul",
"instructions": "Is the supplied state describing an integration test?"
}
}
};
const response = await fetch("https://api.omniakey.com/v1/alpha/search", {
method: "POST",
headers: {
Authorization: `Bearer ${key}`,
"Content-Type": "application/json",
},
body: JSON.stringify(body),
signal: AbortSignal.timeout(25_000),
});
if (!response.ok) {
const retryAfter = response.headers.get("retry-after");
throw new Error(`Jev HTTP ${response.status}; Retry-After: ${retryAfter ?? "not supplied"}`);
}
const result = await response.json();
console.log(JSON.stringify(result, null, 2));
// Inspect and validate the answer before connecting it to any external action.
In the playground, select Custom Jev and paste the native JSON below into the editor before entering your key and running it.
Copy native JSON for the playground
Native JSON
{
"model": "jev-latest",
"state": "This is a synthetic integration test. No external action is requested.",
"questions": {
"is_test": {
"type": "noul",
"instructions": "Is the supplied state describing an integration test?"
}
}
}Interpret the result
For this request, inspect answers.is_test.type and answers.is_test.noul. Noul represents a value from 0 to 1 for the yes/no proposition; it is not a JavaScript boolean and has no separate confidence field.
Check the returned model and usage.input_tokens / usage.output_tokens as well. The exact model version and probability may differ between calls. A correctly shaped response confirms the contract; it does not establish that every future answer is correct.
Troubleshoot a failed request
- Invalid request (for example, 400)
- Check model, state, questions and each question's type, options or range. Do not send a chat messages payload to this endpoint.
- Authentication or account rejection (such as 401, 402 or 403)
- Check the key, balance, model access and current provider policy. A status alone does not uniquely identify the cause. Inspect your OmniaKey account without pasting credentials into support text.
- Rate limit (429)
- Read Retry-After if supplied, reduce concurrency and use bounded backoff. These examples do not retry automatically; duplicate requests may add cost.
- 5xx, network failure or timeout
- Check service status and connectivity before deciding to retry. The 25-second timeout ends the client's wait; it does not guarantee upstream cancellation or avoid billing.
- HTTP success with an unusable answer
- Validate the response shape, question names and answer types. Missing answers or unknown options need a fallback or review, rather than coercion followed by execution.
Checks before integration
- A clearly labeled synthetic test should be distinguished from an ordinary work request.
- A missing or invalid key should surface an authentication error, without printing the key.
- A missing questions object should be corrected before retrying.
- A timed-out call should leave the workflow in a reviewable state.
Common questions
Can I use a normal OpenAI Chat Completions request?
This integration uses OmniaKey's dedicated Jev route with state and questions. A messages array is not a substitute for that contract. The Node.js example uses fetch so the request shape stays explicit.
Is a successful request free?
Do not assume that. Calls use your OmniaKey account and its current pricing and quota. The playground does not provide shared credits, and a historical vendor price does not establish your gateway bill.
Sources and next steps
Protocol details were checked against OmniaKey's Jev guide and authentication documentation. Request examples pass local schema checks; this article does not claim a live performance evaluation of each workflow. This site is independent of the model developer and OmniaKey.
Try it with your own task
Start with a synthetic input and inspect the native request and model answer. Open OmniaKey key management with your account, or follow its sign-up flow if you are new.