Making requests

Open Vertex Router speaks the OpenAI API. Requests you already send to OpenAI are valid as they are: same fields, same response shape, same error envelope. This page lists what the gateway exposes and the few places where it differs.

Endpoints

Endpoint	Purpose
POST /v1/chat/completions	Chat completions, with streaming.
GET /v1/models	The models your key can call, as data[].id.

Both work with or without the /v1 prefix. Other OpenAI paths, such as the legacy /v1/completions, Assistants, Batches or Realtime, are not available and return 403.

For request and response fields, use OpenAI’s chat completions reference. The gateway passes them through unchanged.

Streaming

Set stream to true to receive server-sent events, ending with [DONE]. To get token counts at the end of a stream, also set stream_options with include_usage:

curl

curl -N https://<your-gateway>/v1/chat/completions \
  -H "Authorization: Bearer $OVR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "Count to five."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Python

stream = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print(f"\n{chunk.usage.total_tokens} tokens")

JavaScript

const stream = await client.chat.completions.create({
  model: "gpt-4.1-mini",
  messages: [{ role: "user", content: "Count to five." }],
  stream: true,
  stream_options: { include_usage: true },
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  if (chunk.usage) console.log(`\n${chunk.usage.total_tokens} tokens`);
}

The last chunk carries usage and an empty choices array, which is why the examples check both.

What differs from OpenAI

• Model ids are bare names with no provider prefix: gpt-4.1-mini, claude-haiku-4-5, gemini-2.5-flash. GET /v1/models returns the exact ids. An unknown id returns 400. See Models & providers.
• No cost in responses. usage carries token counts only. Cost and balance live in the dashboard.
• Response headers. Every response carries x-request-id. Non-streaming responses also carry x-ratelimit-user-* headers describing your plan’s limits, and retry-after when you are throttled. Provider-specific headers are not forwarded. See Rate limits.
• Request tags. Attribute spend to a feature, an environment or a customer with the X-OVR-Tags header or a tags field in the body. See Request tags.
• Provider errors come back with the provider’s HTTP status, a neutral message and the request id. See Errors.

Handling failures

• 401: the key is invalid, revoked, or blocked because the account is out of credit. Do not retry; fix the key or top up.
• 429: rate limited or over the key’s budget. Retry with backoff, honoring retry-after.
• 5xx: retry once.
• Log the x-request-id header with every error and quote it in support requests.