OpenAI-compatible API

Ethen exposes an OpenAI-style chat-completions contract, but compatibility is bounded by the fields and response behavior implemented in the current route. Use this guide when adapting an existing client without assuming that every OpenAI endpoint or option exists.

No universal SDK guarantee or permanent production base URL is established by the supplied sources.

Compatibility work should be evaluated at three levels: transport, schema, and behavior. The transport is the verified Ethen route and Bearer-key convention. The schema includes the request fields and OpenAI-style response envelope present in the handler. Behavior includes Ethen readiness checks, provider routing, fallback metadata, and route-specific errors. A client may look familiar at the schema level while still needing changes for authentication, unsupported optional fields, models diagnostics, or the additional Ethen metadata returned with a response.

Compatibility model

A compatible envelope should be treated as a transport convenience, not as vendor identity. Provider selection remains an Ethen routing decision, and the selected provider may differ between requests without changing the client-facing endpoint.

Compatibility is limited to the request and response behavior implemented by the inspected chat route. The endpoint accepts an OpenAI-style chat-completions body, produces an OpenAI-style non-streaming object or SSE chunks, and adds Ethen routing metadata. That does not establish support for every OpenAI endpoint, SDK feature, optional request field, or error shape.

The verified public handlers are chat completions and the catalog-plus-diagnostics models route. Fields such as tools, tool choice, response format, penalties, seed, log probabilities, multiple choices, and arbitrary OpenAI extensions are not part of the supplied contract. Omit unsupported options rather than assuming that a familiar endpoint name will accept them.

The verified endpoint follows the chat-completions pattern for model, messages, optional generation fields, streaming, and response choices.

Non-streaming output uses a chat.completion object, while streaming emits chat.completion.chunk events.

Ethen adds route, provider, attempt, fallback, request, trace, and project metadata rather than hiding execution details.

Compatibility is intentionally scoped to the request and response shapes visible in the inspected handlers. It covers familiar chat-completion conventions, not every OpenAI endpoint, SDK behavior, optional field, or error representation.

Fields such as tools, tool choice, response format, penalties, seed, and logprobs are not verified by the supplied handler. Message content can be text or an array containing text and image URL entries, although image entries are currently replaced with a placeholder.

The verified request fields are model, messages, temperature, max_tokens, max_completion_tokens, stream, metadata, and providerOptions.gateway. Non-streaming output follows an OpenAI-style chat-completion envelope and adds an ethen object.

Base URL

Keep API versioning in the path. Replacing the verified route with a vendor-default /v1 path can send the request to a different handler or produce a misleading compatibility failure.

Use deployment-specific configuration for the host and append the verified relative route:

/api/gateway/v1/chat/completions

No permanent public hostname is established in the supplied implementation. Keep the base URL in environment configuration so the same client can target an approved deployment without hardcoding localhost, development, or administrative routes.

The repository verifies the path /api/gateway/v1/chat/completions.

Deployments can place that path behind different approved origins, so the sources do not support one permanent public hostname.

Configure the origin outside request-building logic and keep the verified path explicit.

Supported migration baseline

{
  "model": "YOUR_RUNNABLE_MODEL_ID",
  "messages": [
    {"role": "user", "content": "Summarize the supplied text."}
  ],
  "temperature": 0.2,
  "max_completion_tokens": 300,
  "stream": false
}

This baseline deliberately omits fields that are common elsewhere but not verified in the current Ethen handler.

Document the route as a relative API path unless an authoritative deployment source supplies a host. A localhost address, development origin, or assumed public domain must not become an evergreen base URL in generated documentation.

Streaming uses SSE chunks and a terminal [DONE] sentinel.

Authentication

The compatible chat surface still uses Ethen authentication. Supply the project-scoped Gateway key through Authorization: Bearer <key>. An OpenAI provider key, Anthropic key, or other BYOK secret belongs to provider configuration and must not be placed in this header.

Clients that previously inserted a vendor key directly into an OpenAI SDK configuration must change both the credential and the base route. Authentication errors are returned before provider routing, so vendor-specific retry logic should not process missing_api_key, invalid_api_key, revoked_api_key, expired_api_key, or insufficient_scope.

Send a project Gateway key using Authorization: Bearer <key>.

The route requires gateway:invoke and rejects revoked or expired credentials before model selection.

Provider credentials used through BYOK are not sent in this header.

Authentication differs from a provider-native OpenAI call because the Bearer value is an Ethen project key. Any OpenAI provider credential used through BYOK is resolved behind the Gateway after routing selects that provider.

Migrate the smallest request first. Remove fields absent from the inspected contract, confirm the baseline response, and add Gateway routing options afterward.

Supported request fields

The inspected route accepts model, messages, temperature, max_tokens, max_completion_tokens, stream, metadata, and providerOptions.gateway. Message content can be text or a supported content array, although image entries are currently converted to a placeholder rather than forwarded as a verified multimodal contract. Fields common in other OpenAI endpoints—such as tools, tool choice, response formats, penalties, seeds, or log probabilities—must not be assumed.

The handler recognizes model, messages, temperature, max_tokens, max_completion_tokens, stream, metadata, and providerOptions.gateway. Gateway routing options can narrow provider order, restrict providers, supply provider-specific model aliases, and set provider timeouts. The request still passes project allow-lists, policy preflight, runtime status, credential, and circuit-breaker checks.

Message content may be a string or an array containing text and image URL entries. In the inspected route, image entries are normalized to a placeholder rather than fully parsed, so the array shape must not be described as complete multimodal support.

Directly visible fields are model, messages, temperature, max_tokens, max_completion_tokens, stream, metadata, and providerOptions.gateway.

Gateway provider controls can set order, only, model aliases, and provider timeouts.

Do not pass unsupported OpenAI options on the assumption that the handler will interpret them.

Migration should begin with verified fields only. Remove tool calling, response-format controls, penalties, seed, log probabilities, and other uninspected options until a separate implementation source confirms support.

The models handler returns data plus parser diagnostics under meta rather than a strict OpenAI models response.

Response behavior

Error compatibility is also bounded. The handler exposes Ethen-specific codes for setup, catalog status, provider credentials, model readiness, project budget, provider streaming, and internal failure. Applications should preserve those codes rather than mapping every failure into one vendor exception. The X-Ethen-Model-Status header and Ethen response extension provide context that an ordinary OpenAI response model may discard.

The models route requires a separate parser because it returns {data, meta}. Reusing a client that expects only an OpenAI model array can hide diagnostics such as header mismatches, duplicate IDs, missing required rows, and parsed-count differences.

A non-streaming result uses a chat.completion object and includes Ethen fields for request, trace, project, selected provider, selected model alias, attempts, fallback, warnings, and usage. Preserve that extension when mapping the response into an application model; removing it discards the information needed to explain routing and fallback.

Streaming uses role, delta, and final usage chunks followed by [DONE]. A provider-stream error is emitted as an error chunk before termination. Client code should distinguish normal content events, the final usage event, and an error event rather than assuming every well-formed SSE stream completed successfully.

The normal response contains choices, usage when available, and Ethen execution metadata.

The response exposes X-Ethen-Model-Status and request or trace identifiers for operational correlation.

Image-array content is accepted by the interface but normalized to a placeholder in the current route.

The response preserves an OpenAI-style envelope while adding Ethen route information. Clients that deserialize strictly should account for the extension rather than discarding the identifiers needed for logs, attempts, and fallback analysis.

Applications should tolerate Ethen-specific metadata without treating it as an unknown error. Keep the OpenAI-style completion fields used by the application, then persist the routing extension separately for diagnostics. This also avoids coupling user-visible output to provider names while retaining enough information to explain fallback, attempts, and selected aliases.

Migration guidance

When adapting an existing client, inventory every endpoint and option it uses before changing the base request path. Keep only fields present in the inspected chat contract, map completion length to the supported token field used by the application, and preserve the response identifiers and Ethen metadata returned by the Gateway. Test non-streaming first because it exposes validation and routing errors as a normal JSON response. Add streaming only after the client can parse the verified event sequence. Any dependency on assistants, embeddings, tool calls, batch APIs, or undocumented headers requires separate implementation evidence.

Document the Ethen-specific differences in the client repository: the project key, relative endpoint, supported field subset, {data, meta} models response, routing metadata, and streaming error behavior. This prevents a future maintainer from simplifying the integration back to assumptions that the current handler does not support.

Compatibility testing should include both success and rejection cases. Verify that unsupported fields are removed, Ethen-specific errors remain visible, and streaming clients recognize the final usage event and error chunks. A migration is incomplete if it renders text correctly but discards routing metadata or misclassifies fallback as a normal primary request.

Migrate a client in layers. First send one non-streaming request with only model and messages. Then map the Ethen metadata fields into logging or tracing. Add optional temperature or completion-token fields only after the baseline succeeds. Introduce streaming and routing options as separate changes.

When adapting an existing OpenAI client, audit every configured field and endpoint. Retain only fields supported by the inspected handler, use the Ethen Bearer key, and do not assume that models-list parsing can reuse a strict OpenAI schema because the Ethen route includes parser diagnostics under meta.

Begin with a minimal text request and validate the returned structure before enabling optional parameters.

Remove client features that depend on unverified endpoints or fields, then add Ethen routing options deliberately.

Test both success and documented error codes because a compatible object shape does not erase Ethen catalog, policy, budget, or credential gates.

Treat migration as a behavioral test, not a search-and-replace exercise. Validate one non-streaming request, inspect error handling and metadata, add streaming if needed, and only then introduce request-level routing controls.

The evidence covers chat completions and the catalog-plus-diagnostics models route; it does not establish universal OpenAI SDK compatibility or a production host name.

Treat compatibility as an adapter boundary rather than a promise that every OpenAI client feature will work unchanged. Start with model, messages, and the Bearer header. Add temperature, one supported token-limit field, stream, metadata, or providerOptions.gateway only after the basic request succeeds. Fields such as tool definitions, tool choice, response formats, penalties, seeds, and log probabilities are outside the inspected contract and should be removed or gated in a migration layer.

Response parsing also needs one deliberate change: preserve Ethen’s request, trace, project, provider, attempt, and fallback metadata instead of discarding unknown fields. That information explains routing decisions and is necessary for troubleshooting. For streaming clients, parse server-sent events through the terminal [DONE] marker and capture the final usage chunk. A library that assumes a different event sequence or automatically reconnects must be tested against the implemented stream rather than trusted because the endpoint resembles an OpenAI path.