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:
| Provider | ID / SDK enum member | Adapter APIs |
|---|---|---|
| OpenAI | openai | Chat Completions, Completions, Responses, embeddings, image generation/editing, speech, transcription/translation |
| Anthropic | anthropic | Chat Completions translation, native Messages |
| xAI | x-ai / xAI | Chat Completions, Completions, embeddings adapter; select a model that actually supports the endpoint |
| Jev / TypeSafe AI | typesafe-ai / typesafeAI | System One |
| ElevenLabs | elevenlabs | Speech; public model/language/voice catalogs |
| Rime AI | rime-ai / rimeAI | Speech; public model/language/voice catalogs |
| Preternatural AI | preternatural-ai / preternaturalAI | Local 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:
| Header | Value |
|---|---|
x-preternatural-auth-provider | api-key for a customer access token |
x-preternatural-api-key | Customer access token |
x-preternatural-customer-id | Customer ID |
x-preternatural-project-id | Project ID |
x-preternatural-product-id | Product ID |
x-preternatural-provider | Provider 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.