AI Services

An AI service is one connection to one model: a provider, an endpoint, a model name and, usually, an API key. Configure them from the sidebar's AI destination, Services tab.

You can configure as many as you like. One of them is the default, marked with a badge; it is what the assistant uses unless a tool says otherwise. Use Set as Default to change it. If you never set one, the oldest service wins.

Adding or editing a service

Name is yours to choose. It is what you will see in menus, so make it descriptive: "Claude for proofreading", "Local Llama".

Provider picks the wire format and fills in a sensible endpoint. Grafida ships with OpenAI, Anthropic, Cohere, DeepSeek, Google, Groq, MiniMax, Mistral, OpenRouter, Perplexity, Scaleway and GitHub Models, plus two catch-alls:

• Custom (OpenAI Completions API) for anything that implements OpenAI's older /chat/completions interface. This is what most third-party and self-hosted servers speak.
• Custom (OpenAI Responses API) for anything implementing OpenAI's newer /responses interface.

On an eligible device there is also On-Device (Apple Intelligence) — see Using the on-device model, below.

Endpoint is the base URL of the API. Picking a known provider fills it in for you; you only need to change it for a custom or self-hosted endpoint, or for a provider that gives you a project-specific URL. Do not append the chat path — Grafida adds it. ⚠️ The endpoint must be https://, unless the server is on this device or your own local network. Grafida will not send an API key over a plain http:// address on the open internet, and refuses one with its own message rather than trying and failing later. See Using a self-hosted model for the local-network exception, which is what makes LM Studio, Ollama and llama.cpp on your own computer usable.

API Key is the provider's key. It is stored in the device's Keychain, not in Grafida's database — see App Lock for how the device itself is protected. When you edit an existing service the field is blank: leave it blank to keep the key you already have. For a self-hosted server with no authentication configured, the field may be left blank entirely.

Model is the model identifier, as the provider spells it. Fetch Models asks the provider for the list, which saves you looking it up — it needs the endpoint and key to be right first. Not every provider offers a models list; the button is absent, not disabled, when one does not (Cohere and Perplexity, today).

Parameters

All of these may be left on (Auto-detect), which means "send nothing and let the provider use its own default". Fill them in only when you have a reason to.

Temperature and Top P control how adventurous the model is. Lower values give more predictable text.

Max Tokens caps the length of the reply.

Streaming decides whether the reply is shown word by word as it arrives, or all at once when it is finished. Leave it on auto unless your provider does not support streaming.

The model can see images

Off by default. When on, the article's pictures are sent along with its text, so the model can comment on them or write alt text.

Pictures are scaled down to 1024 pixels and capped at eight per request before being sent, because an article image is routinely several thousand pixels wide and every vision model downsamples it on arrival anyway.

Only images hosted on your own site, or still local to Grafida, are sent. An image hotlinked from a CDN or a third-party site is skipped, and one picture Grafida cannot reach never blocks the rest.

Store the conversation, and resume for up to (days)

These two only appear for providers using the Responses API (OpenAI, and Custom (OpenAI Responses API)), which can remember a conversation on its own servers.

With Store on, a follow-up message sends only the new turn plus a reference to the previous reply, instead of re-uploading the whole conversation — which matters, because the first message in every Grafida chat carries the entire article. Resume for up to (days) is how long Grafida assumes the provider will keep it; the default is 15 days.

This is purely an optimisation. If the provider has forgotten the conversation, Grafida notices and retransmits the whole history automatically. Aborting a reply, or any error, drops the reference and the next message sends everything again.

Using a self-hosted model

A model server on your own hardware — LM Studio, Ollama, llama.cpp, vLLM, or anything else that speaks one of the two OpenAI wire formats — works well. Choose Custom (OpenAI Completions API) or Custom (OpenAI Responses API), whichever the server speaks, and give it the server's address. Most of these servers have no API key at all, and the API Key field may be left blank for both Custom providers.

These servers listen on plain http://, because they were written to talk to software on the same desk. Grafida accepts that — but only where "the same desk" is literally true:

Two things this does not change:

• Certificates are still checked. If you do use https://, the certificate must be one this device already trusts. A self-signed certificate is refused whether the server is on your network or not — use a certificate from Let's Encrypt for a publicly-resolvable host, or one from your organisation's own certificate authority, installed on the device through a configuration profile.
• Your Joomla site is not covered by any of this. A site is always https://, everywhere, with no exception — a Joomla API token never expires and can do everything its owner can do, so it is never put on a connection that could be read. The exception above exists for AI endpoints alone.

The reasoning behind the difference: article text sent to a model server on your own network was never going to leave that network anyway, and most such servers hold no credential at all. Anyone able to read it on that wire could simply ask the model server themselves.

Using the on-device model

On-Device (Apple Intelligence) needs no endpoint and no API key — it runs entirely inside the device's own chip, and nothing about the request leaves the device. It needs no configuration beyond adding the service.

Whether it is offered, and what it can do, depends on the device itself:

• Below iOS 26 or iPadOS 26, the option does not appear at all — there is nothing to turn on.
• On iOS 26 or iPadOS 26, it handles text only.
• On iOS 27/iPadOS 27 and later, it can also see images, on hardware capable enough to run that path — Grafida checks this for itself and simply does not offer images where it cannot.

None of this is a setting you choose; Grafida reads it from the device and shows you which case applies. If Apple Intelligence itself is not turned on, or the model is still downloading, the service form tells you so and updates on its own once that changes — you do not need to relaunch Grafida.

Using a model you downloaded

Apple Intelligence is not the only way to run a model on the device itself. On a device that reports enough memory (in practice an 8 GB-class device or better) you can download an open-weights model and use that instead — it needs no endpoint and no API key either, and it works on devices where Apple Intelligence is unavailable. It runs fastest on an M-series chip (M1 or later); on an A-series device it still works, just noticeably slower, and the model card says so before you download anything. See Local Models for the exact memory figure.

A downloaded model appears in this provider list only once its files are on the device, and disappears again if you delete it. See Local Models.

Two failures are specific to this model. A long article can exceed what it can hold in context at once — the article-too-long message names this cause specifically, rather than failing silently. And the model can decline to respond to particular content on its own; that is Apple's own safety filter, not a Grafida setting, and it is never retried and never quietly sent to a remote provider instead.

Deleting a service

Delete removes the service and its stored key. Any tool that pointed at it falls back to the default service.