Connecting Model Providers and API Keys

ENGRAI is a bring-your-own-model client. It does not sell model access, provide API credits, or route requests through an ENGRAI server. Instead, the app connects directly to a hosted provider, a server on your local network, or a downloaded on-device model that you choose.

ENGRAI does not impose its own message cap. Your provider may still apply usage charges, credit balances, context limits, rate limits, regional restrictions, or daily quotas. Consumer chat subscriptions and API access are often billed separately, so check the provider's current API and billing documentation before creating a key.

Keep API keys private. Treat a key like a password. Never include one in a screenshot, support email, GitHub issue, character card, or exported prompt. If a key is exposed, revoke it through the provider and create a replacement.

Quick setup

1. Open ENGRAI's API or Connections area and create a new connection.

2. Give the connection a Preset Name. This is only the label shown inside ENGRAI.

3. Choose the provider's Format: OpenAI, Anthropic, or Google.

4. Paste the provider's Header URL (its API base address), not its homepage or account dashboard.

5. Paste the API Key if the endpoint requires one.

6. Use the refresh button beside Model Name to fetch available models, or type the exact model ID yourself.

7. Save the connection.

8. Open Session → Model Routing and choose which connection ENGRAI should use for Chat, Summary, and Image work.

The first connection you create automatically becomes the chat route. You can change the route at any time.

Before you begin

For a hosted provider, you normally need:

• an account with the provider;

• API access enabled for that account;

• an active credit balance, billing method, or API plan if required;

• a newly generated API key; and

• the provider's exact base URL and model ID.

Signing in to a provider's website is not enough. ENGRAI cannot use browser cookies, a ChatGPT/Claude/Gemini login session, or a consumer subscription in place of an API key.

For a local server, you need the server application running, a compatible model loaded, and the server's OpenAI-compatible address. Local servers commonly require no key unless you explicitly enable authentication.

Understanding the connection fields

Preset Name

The preset name is for your own organization. It doesn't go to the provider and doesn't need to match a model name.

Useful names describe the job of the connection, for example:

• Primary Chat

• Fast Summarizer

• Local Mac

• Image Model

Each connection stores one endpoint, one format, one model ID, and optional generation settings. If you want two models from the same provider, create or duplicate two connections and give each one a different model ID.

Format

The format tells ENGRAI how to construct the request and how to authenticate it. It is not merely the company name.

Choose the format documented by the endpoint operator. For example, a hosted platform may offer Claude models through an OpenAI-compatible endpoint. In that case, choose OpenAI, not Anthropic, because the endpoint shape—not the model's creator—determines the format.

Header URL

The Header URL field is the API base URL. A provider may also call it the base URL, API URL, server URL, or endpoint root.

Use an address such as:

https:

https:

https:

Do not paste:

• the provider's marketing homepage;

• the page where you manage keys;

• a playground or chat webpage;

• a documentation-page URL; or

• a URL for an incompatible endpoint such as /responses when the provider does not also support Chat Completions.

ENGRAI normalizes common forms. For OpenAI-compatible connections, all of these can resolve to the same chat endpoint:

The normalizer avoids doubling /v1 and removes recognized terminal paths such as /chat/completions or /messages. It deliberately does not guess at arbitrary provider-specific paths. When in doubt, use the base URL shown in the provider's official SDK example.

API Key

Most hosted endpoints require an API key. Generate it in the provider's console or account settings and paste only the key value into ENGRAI—do not add Bearer, quotation marks, a variable name, or surrounding spaces.

Leave the field empty only when the endpoint documentation says authentication is unnecessary. This is common for a server running on your own device.

ENGRAI sends the key directly to the configured endpoint using the header required by the selected format. ENGRAI does not provide, validate, recover, or reset provider keys.

Model Name

The model name is the provider's exact machine-readable identifier, not necessarily its marketing name. Capitalization, punctuation, organization prefixes, dates, sizes, and tags may all matter.

For example, a provider might present a model publicly as Example 8B but require an identifier shaped like:

After entering the format, URL, and key, select the refresh button beside Model Name. ENGRAI asks the provider's model-list endpoint for the IDs available to your account:

• OpenAI and Anthropic formats use /v1/models;

• Google format uses /v1beta/models.

If the provider does not implement a compatible model-list endpoint, returns no models, or restricts listing permissions, you can still type the model ID manually. Always copy it from the provider's current API documentation or model catalog.

Common connection examples

These are starting points, not permanent provider guarantees. Ports, paths, authentication, and model catalogs can change; the endpoint operator's documentation remains authoritative.

Do not copy a sample model ID from an unrelated provider. Use the refresh control or enter the ID exposed by the endpoint you actually configured.

Local and on-device models

ENGRAI supports two different kinds of local inference.

A local API server

Applications such as Ollama, LM Studio, llama.cpp, KoboldCpp, vLLM, and SGLang can expose an HTTP server. ENGRAI talks to that server using the same OpenAI-format connection used for hosted compatible APIs.

Before connecting:

1. Install and start the inference engine.

2. Download or load a chat/instruct model.

3. Start its OpenAI-compatible server.

4. Confirm the host and port shown by the server.

5. In ENGRAI's API area, enable Allow Local LLM and accept the local-model notice.

6. Create an OpenAI connection using the server's /v1 base URL.

On macOS, localhost means the same Mac that is running ENGRAI. On iPhone or iPad, localhost means the phone or tablet—not your Mac. To reach a server running on another computer:

• enable the server's serve on local network or equivalent option;

• use that computer's private LAN address, such as http://192.168.1.25:1234/v1;

• keep both devices on the same network; and

• allow the server through the host computer's firewall.

Exposing a local server beyond 127.0.0.1 makes it reachable by other devices. Enable the server's authentication when available, and do not expose an unauthenticated inference port to the public internet.

An inbuilt model

An inbuilt model runs directly inside ENGRAI and does not use a Header URL or API key. Download it through the on-device model controls, then choose it for the Chat or Summary lane in Session → Model Routing.

Built-in models are currently text-only, so you can't assign them to the Image lane. On-device inference can also use substantially more memory, power, and battery than calling a hosted provider.

Model routing

Connections are reusable presets. Routing decides which preset performs each job.

The lanes can point to the same connection or to three different connections. A common arrangement is a larger chat model, a faster summary model, and a dedicated image model.

Anthropic format does not provide an image-generation endpoint in ENGRAI. Route Image to an OpenAI- or Google-format connection instead. A text model on an otherwise compatible provider does not automatically become an image model; the selected model ID must itself support image generation.

Advanced generation settings

Start with every override turned off. When an override is off, ENGRAI omits that field and allows the endpoint to use its own tuned default. This is the most portable configuration.

Not every provider or API format accepts every sampler. Unsupported fields may be ignored or rejected. Consult the endpoint's documentation before enabling them, and change one setting at a time.

JSON Override

The JSON Override field adds top-level properties to the request body. It is intended for provider-specific options without a dedicated control.

{
  "frequency_penalty"

{
  "frequency_penalty"

{
  "frequency_penalty"

The value must be a JSON object. Invalid JSON is not applied. Extra keys are merged after ENGRAI builds the normal request, so a duplicate key can replace a standard field such as model, stream, or messages and break the request. Never place an API key in this field.

For Google format, options inside generationConfig must follow Google's nested object structure. For Anthropic format, use only fields accepted by the Messages API. Provider-specific extensions may change without notice.

Display Reasoning

Display Reasoning affects presentation only. When a model returns a separate reasoning or thinking channel, ENGRAI can show it in a collapsible panel or hide it. Reasoning stays separate from the visible answer and isn't added back into the conversation transcript either way.

Troubleshooting

401 Unauthorized or 403 Forbidden

• Re-copy the API key without Bearer, quotes, or spaces.

• Confirm the key has not expired or been revoked.

• Confirm the account has API access, credit, and permission for the selected model.

• Verify that the selected format matches the endpoint. An Anthropic-format connection and an OpenAI-format connection send the key in different headers.

404 Not Found

• Confirm that the Header URL is an API base URL, not a provider homepage or dashboard.

• Check for a provider-specific prefix such as /api/v1 or /openai/v1.

• Confirm the endpoint supports OpenAI Chat Completions, Anthropic Messages, or Google generateContent, depending on the selected format.

• Prefer the base URL in the provider's official SDK example instead of guessing from a complete endpoint URL.

The model list is empty or cannot be fetched

• A model-list endpoint is convenient but not required for chat generation.

• Confirm the server is running and the key is valid.

• Some providers do not expose /models, restrict it by account, or return a nonstandard response.

• Type the exact model ID manually and save the connection.

A local endpoint is blocked

Enable Allow Local LLM in the API/Connections area and accept the notice. ENGRAI gates loopback, .local, and private-network addresses behind this acknowledgment.

Connection refused, timeout, or the local server cannot be reached

• Start the server and load the model before sending a message.

• Verify the port shown by the server.

• On iPhone or iPad, replace localhost with the server computer's LAN address.

• Make sure the server is listening on the LAN interface and the firewall allows the connection.

• A large local model may take time to load on its first request.

400 Bad Request or 422 Unprocessable Entity

• Turn off all Advanced overrides and retry.

• Reset JSON Override to {}.

• Confirm the model supports chat, not just completions, embeddings, audio, or images.

• Verify the provider's current model ID and parameter names.

Chat works, but image generation fails

• Assign a separate Image connection in Model Routing.

• Confirm that the model ID supports image generation through the configured endpoint.

• Use OpenAI or Google format; Anthropic and built-in formats are text-only for ENGRAI image routing.

Provider directory

The following services are examples, not recommendations or endorsements. Availability, pricing, model catalogs, privacy practices, and API compatibility can change. Read the provider's current terms, privacy policy, billing documentation, and acceptable-use policy before sending data or purchasing credit.

Direct model APIs

• OpenAI API

• Anthropic / Claude API

• Google Gemini API

• DeepSeek API

• Z.ai API

• Mistral API

• xAI API

Hosted OpenAI-compatible platforms and aggregators

• Groq

• Together AI

• Featherless AI

• Venice AI

• NanoGPT

• OpenRouter

• Ollama Cloud

Local inference engines

• Ollama

• LM Studio

• llama.cpp

• KoboldCpp

• vLLM

• SGLang

ENGRAI is not affiliated with any provider or inference engine listed above. Compatibility means that an endpoint implements the request and streaming response shape ENGRAI uses; it does not mean every provider feature, sampler, media type, or model is supported.

Privacy and provider responsibility

Hosted requests travel directly from your device to the endpoint in the URL header. Once content reaches that endpoint, its operator's retention, logging, training, moderation, and disclosure policies apply. ENGRAI cannot override those policies.

A local or built-in model can keep generation traffic on your device or private network, but local operation also means you are responsible for securing the server, choosing the model, maintaining backups, and complying with applicable law and the ENGRAI.