Introduction

OpenAI-compatible HTTP gateway in front of every model provider we support. One contract, one key, one bill.

The Aivene API is an HTTP gateway that fronts dozens of upstream model providers behind a single, OpenAI-compatible surface. Point any OpenAI SDK at our base URL and your existing code keeps working - the gateway handles routing, normalisation, billing, and rate limits transparently.

https://api.aivene.com/v1

OpenAI SDKs work as-is

Override the baseURL (or OPENAI_BASE_URL env var) and pass an Aivene API key. No other code changes. See Quickstart for a step-by-step walkthrough.

Conventions

Transport - JSON over HTTPS. Content-Type: application/json is required for every body-bearing request.
Authentication - bearer token in the Authorization header. See Authentication.
Versioning - the /v1 prefix is the stable contract. Breaking changes ship under a new prefix; additive fields can appear any time.
Streaming - endpoints that support streaming use Server-Sent Events (text/event-stream) when stream: true is set on the request body.
IDs - object ids are opaque strings. Do not parse them.
Timestamps - Unix seconds (integer) unless explicitly noted.
Pagination - cursor-based via after / before query params on list endpoints. Responses include has_more and the last id.

Base URL

All endpoints are rooted at:

https://api.aivene.com/v1

Regional or dedicated deployments may use a different host - the path shape stays identical.

Request lifecycle

Client sends a request with Authorization: Bearer <key>.
The gateway authenticates the key and resolves the route + provider.
Inputs are normalised (role aliases, param names, content parts).
The upstream provider is called; responses are normalised back to the OpenAI shape.
Usage is metered and billed against your account balance.

Responses

Successful calls return a JSON body with a 2xx status. Streaming calls flush data: {...}\n\n frames terminated by a final data: [DONE] sentinel.

Errors

Every error follows the same envelope so you can handle them uniformly:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Human readable explanation"
  }
}

Status	`error.type`	When it happens
`400`	`invalid_request_error`	Schema violation. `param` names the offending field.
`401`	`authentication_error`	Missing or invalid API key.
`402`	`billing_error`	Account out of credit or hit a spend limit.
`403`	`permission_error`	Key lacks the required scope.
`404`	`not_found_error`	Resource (file, model id, etc.) does not exist.
`429`	`rate_limit_error`	RPM or TPM exceeded. Respect the `Retry-After` header.
`5xx`	`upstream_error`	Downstream provider failure. Safe to retry idempotent calls.

What's next

Authentication - how to mint and use API keys.
Chat Completions - the primary text-generation endpoint.
Models - the catalogue of ids you can pass as model.