Getting started

1. Create an API key

1. Sign in to the dashboard and open Core > Projects (/app/core/projects).
2. Create a project (or open an existing one). Projects hold the routing mode, budgets, data policy and request log.
3. Under API keys, create a key and copy it. It is shown once.

Keys look like ory_live_... (real models, billed) or ory_test_... (test mode: the same API, simulated answers, not billed). Keep keys server-side and put them in an environment variable:

export ORYVOX_API_KEY=ory_live_...

2. Install an SDK

npm install @oryvox/sdk      # Node.js >= 18
pip install oryvox           # Python >= 3.9

Any OpenAI-compatible client works too (see Migration from OpenAI).

3. Send your first request

oryvox-auto lets ORYVOX pick the best model for each request.

Node.js

import Oryvox from '@oryvox/sdk';

const client = new Oryvox(); // reads ORYVOX_API_KEY

const response = await client.responses.create({
  model: 'oryvox-auto',
  input: 'Explain HTTP caching in two sentences.',
});

console.log(response.output_text);
console.log(response.oryvox); // { request_id, selected_model, provider, cost, saved, cache, fallbacks }
console.log(response._requestId); // also in the X-Oryvox-Request-Id header

Python

from oryvox import Oryvox

client = Oryvox()  # reads ORYVOX_API_KEY

response = client.responses.create(
    model="oryvox-auto",
    input="Explain HTTP caching in two sentences.",
)
print(response.output_text)
print(response.oryvox.selected_model, response.oryvox.cost)

cURL

curl https://api.oryvox.ai/v1/responses \
  -H "Authorization: Bearer $ORYVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "oryvox-auto", "input": "Explain HTTP caching in two sentences."}'

Test mode

ory_test_ keys run the full pipeline (guard, analysis, cache rules, token engine, routing, trace and request log) but the answer comes from a simulator: no provider is called and nothing is charged. Answers carry oryvox.test: true and oryvox.provider: "sandbox"; oryvox.selected_model is the model the router would have used.

• Plain requests get a short text saying which model was chosen and why.
• JSON mode (response_format json_object / json_schema) returns {"simulated": true, "model": "..."}.
• With tools, tool_choice: "required" (or a named function) returns a call to the first (or named) tool with {} arguments; auto does so when the message asks to call, use, run, check, look up or search.
• Streaming works for both /chat/completions and /responses.
• /embeddings returns simulated vectors (16 dimensions, deterministic) and is free.
• Put oryvox-test:<error> in the last user message to get that error and test your handling:

// retries off, so the first 429 surfaces
await client.responses.create({ model: 'oryvox-auto', input: 'oryvox-test:rate_limited' }, { maxRetries: 0 });
// -> throws RateLimitError

Scopes, IP allowlists, rate limits, budgets and policies apply as with live keys; no credit is needed. client.isTestMode / client.is_test_mode tells you which kind of key a client uses.

Next steps

• Pick a routing profile (oryvox-fast, oryvox-quality...) or a fixed model.
• Stream answers token by token.
• Set a budget and subscribe to webhooks.
• Look up any call in the request log: client.requests.retrieve(response.oryvox.request_id) (key scope requests, see Observability).
• Building agents? Name each step.