Making requests

Osyra's documented native REST base is https://api.osyra.ai/api/v1. For drop-in OpenAI clients, Edge also exposes the deliberately narrow https://api.osyra.ai/v1 compatibility base. The verified compatibility subset on this page is chat/completions, chat/completions/stream, embeddings, and models; this page does not claim to inventory every native route.

The client sends the requested model through one API base and routing happens server-side. Available provider and model identifiers depend on the verified configuration in the target workspace; this page makes no failover, alias, or regional-routing guarantee. See Model routing for the narrow verified contract.

Chat completions

POST /v1/chat/completions (OpenAI-compatible alias)

The compatibility projection supports model, string-content messages (role, content, optional name), max_tokens, temperature, top_p, stop, stream, and stream_options.include_usage. Unknown OpenAI fields are currently ignored, not forwarded. Test any workload that depends on tools, multimodal content, response formats, log probabilities, or provider-specific extensions before migrating it.

Request

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "system", "content": "You are a precise technical assistant." },
    { "role": "user", "content": "Explain TCP slow-start in two sentences." }
  ],
  "temperature": 0.2,
  "max_tokens": 200
}

The compatibility projection ignores unknown OpenAI fields. In particular, it does not currently forward an OpenAI user field or record that field as audit identity. Osyra derives authenticated identity and workspace authority from the presented credential instead of trusting an identity selector in the request body.

Response

{
  "id": "chatcmpl-9pQX8E2dQv4Tn7kL",
  "object": "chat.completion",
  "created": 1745001234,
  "model": "gpt-4o-mini-2024-07-18",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "TCP slow-start begins each new connection with a small congestion window and grows it exponentially per round-trip. Once a loss is detected the window collapses and a linear congestion-avoidance phase takes over."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 51,
    "total_tokens": 75
  }
}

Successful non-streaming responses expose the usage metadata that the Edge handler actually emits:

X-Osyra-Provider: openai
X-Osyra-Model: gpt-4o-mini
X-Osyra-Token-Count: 75

The current OpenAI-compatible handler does not emit an X-Osyra-Receipt response header. Retrieve persisted receipts through the authenticated control-plane query described under Audit receipts; never treat the model response id as a receipt.

Streaming

Set "stream": true. The response is OpenAI-compatible incremental text/event-stream; Edge projects broker chunks into that compatibility shape and flushes them as they arrive.

from openai import OpenAI
 
client = OpenAI(base_url="https://api.osyra.ai/v1", api_key=...)
 
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Count to ten, one number per line."}],
    stream=True,
)
 
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

The stream terminates at data: [DONE]. The current compatibility handler does not append a custom receipt event after that sentinel.

Embeddings

POST /v1/embeddings (OpenAI-compatible alias)

The compatibility projection accepts model, input as a string or string array, and optional dimensions. Edge carries the requested model identifier to the broker. Other provider-specific embedding fields are not part of the supported contract.

{
  "model": "text-embedding-3-small",
  "input": ["machine readable provenance", "vendor neutral routing"]
}

The supported response projection is a data array of { embedding: number[], index: number } objects plus model, object, and usage. Usage/model/provider headers follow the same contract as non-streaming chat; no receipt header is emitted on this path.

Retry safety

Chat completions and embeddings do not currently provide response-level idempotency. Edge does not cache model responses for an Idempotency-Key, and it does not emit an X-Osyra-Idempotent replay header on these routes.

For batch work, persist the successful response ID in your own job ledger and retry only requests whose outcome is known to be incomplete. A transport timeout can occur after a provider accepted work, so treat an ambiguous retry as a possible second model execution.

Provider failures and retries

Provider selection is outside this page's compatibility contract. Do not infer that a retry will use either the same provider or a different one, and do not infer a fixed attempt count. The model-routing review publishes only behavior backed by current service evidence.

Client retries remain subject to the ambiguity described above: a timeout can happen after upstream dispatch. Retry 429 and transient 5xx responses only when the operation is safe, honor Retry-After when it is present, and apply exponential backoff with jitter. Fix validation and policy failures instead of retrying them.

Timeouts

The current Model Broker bounds non-streaming chat and embeddings at 30 seconds and streaming at 60 seconds. These are service limits, not customer-editable Settings values. A deployment can impose a shorter upstream or infrastructure deadline.

When a deadline or dependency fails, preserve the actual HTTP status, OSY-* code, and X-Request-ID returned by that layer. Do not assume a timed-out request was never accepted upstream or that it is automatically non-billable; reconcile the outcome before replaying it.

What's next

• Model routing — verified request dispatch and provider-credential boundaries
• Rate limits — what each tier allows
• Errors — selected shared Edge codes with recovery guidance