Skip to Content

Gateway APIs

The regular-product gateway accepts customer-authenticated requests at https://gateway.preternatural.ai/v1. The Client SDK’s gateway configuration supplies the appropriate base URL, customer headers and fetch implementation. Provider credentials stay in Modem.

Subscription relays use their generated native-client URLs and authentication. They are not interchangeable with these regular-product routes.

Request protocols

The request protocols use POST routes. Paths include /v1; provider SDKs may append it themselves.

The gateway protocol inventory lists every mounted request path, its request shape, streaming support and applicable measures. It is generated from the shared metering catalog.

Chat Completions, Completions, Responses and Messages have streaming admission/metering support. Speech can return audio bytes incrementally through its provider handler; it does not use chat SSE. The other protocols are not general-purpose resumable streams.

The protocol inventory does not mean every provider or model supports every API. OpenAI provides its API-shaped text, embedding, image and audio routes. Anthropic offers translated Chat Completions and native Messages. xAI’s API-key integration uses OpenAI-compatible text requests. Jev uses System One. ElevenLabs and Rime AI use speech-specific fields. Native subscription protocols and entitlements are separate from API-key capabilities.

The currently registered Modem providers have these adapter paths. This table describes implemented adapters, not a live probe of every upstream model:

ProviderID / SDK enum memberAdapter APIs
OpenAIopenaiChat Completions, Completions, Responses, embeddings, image generation/editing, speech, transcription/translation
AnthropicanthropicChat Completions translation, native Messages
xAIx-ai / xAIChat Completions, Completions, embeddings adapter; select a model that actually supports the endpoint
Jev / TypeSafe AItypesafe-ai / typesafeAISystem One
ElevenLabselevenlabsSpeech; public model/language/voice catalogs
Rime AIrime-ai / rimeAISpeech; public model/language/voice catalogs
Preternatural AIpreternatural-ai / preternaturalAILocal test responses for chat, completions, Responses, Messages, embeddings, images and transcription/translation

See xAI API accounts, text to speech, and the built-in test provider. The much larger provider registry inside the underlying adapter library does not make those other providers selectable Modem accounts.

Use a model actually available to the provider account and a product usage rule covering that model and measure. A mounted route or public catalog entry does not grant an upstream feature. Feature-specific input remains subject to provider validation.

Use a provider SDK

The OpenAI guide and Anthropic guide show authenticated clients. Use the underlying provider SDK for fields the text-only client.chat helper does not expose, such as Responses input, image options or tool definitions. Follow Responses, images and audio uploads for typed results, multipart inputs and cancellation.

For example, after configuring the OpenAI client:

const embedding = await openai.embeddings.create({ model: 'text-embedding-3-small', input: 'Searchable text' })

That model needs an embeddings-compatible rule. A Chat Completions cost rule does not grant access to an unrelated API. Jev and text to speech have dedicated guides.

Raw HTTP headers

For ordinary customer authentication, send the values from the customer’s current session:

HeaderValue
x-preternatural-auth-providerapi-key for a customer access token
x-preternatural-api-keyCustomer access token
x-preternatural-customer-idCustomer ID
x-preternatural-project-idProject ID
x-preternatural-product-idProduct ID
x-preternatural-providerProvider ID, such as openai or anthropic

Normal customer sessions omit x-preternatural-sandbox-mode or set it to false, even when the customer belongs to a Sandbox project. That header selects synthetic-secret authentication, not project classification. Use the SDK to construct synthetic Sandbox headers; a synthetic secret is not a customer JWT. An admin API key is not a gateway customer token.

A request body must match its protocol. Use JSON content types for JSON APIs and let your HTTP client generate multipart boundaries for uploads. Do not manually label multipart data as JSON.

Public catalogs and headers

GET /v1/models, /v1/voices and /v1/languages provide catalogs. Models with a productId query or product header authenticate the customer and filter by product configuration. Repeated provider query values allow multiple providers on product-scoped model discovery. See Model discovery.

The /v1 ingress allows Modem customer/project/product/provider authentication headers, content negotiation/type/length, user-agent, and Anthropic version/beta headers. It drops unlisted headers, including caller authorization, caller x-request-id, and x-portkey-* routing or billing overrides. The gateway derives the provider credential and policy itself. /v1/logger separately allows Bearer admin authentication; see Admin logs.

Every /v1 response has a gateway-generated request ID. Browsers can read x-request-id and retry-after across origins. Other response headers visible in a native client may not be exposed by browser CORS. Relay paths have their own native header behavior.

Continue with limits and estimates, operational recovery and gateway errors.

Request size

The current gateway limits JSON and image-edit request bodies to 50 MiB and audio upload bodies to 26 MiB, including multipart overhead. Upstream providers can impose smaller file or model limits. A 413 requires a smaller request; retries do not change it. The gateway validates the consumed bytes rather than trusting Content-Length. These transport ceilings do not increase a model’s context window.

Last updated on