The internet and AI
Call web APIs with http, keep keys in secrets, let users point at their own server, and ask the user's AI model.
A plugin can call web APIs and the AI model the user set up in the keyboard. Both are risky permissions: the user sees them before install, and they stay off until the user turns them on for your plugin.
Asking for the internet
Section titled “Asking for the internet”Two lines in the manifest:
"permissions": ["network"],"hosts": ["api.open-meteo.com", "*.openfoodfacts.org"]hostslists every website your plugin may reach. Write only the name: nohttps://, no port, no path.*.example.comcoversexample.comand every name under it. Up to 16.- A plugin with
networkand nohostsis refused at install, unless it has a host setting.
In the editors, risky permissions count as allowed so you can test. After a
real install, each call raises PermissionError until the user turns
network on. When that happens, the keyboard shows the permission in your
panel with an Allow button that leads the user to the switch. They also
need risky permissions allowed for plugins as a whole:
Making requests
Section titled “Making requests”The http module looks like the popular
requests library:
from wm import http
r = http.get("https://api.open-meteo.com/v1/forecast", params={"latitude": 23.8, "longitude": 90.4, "current": "temperature_2m"})r.raise_for_status()temp = r.json()["current"]["temperature_2m"]| Call | Sends |
|---|---|
http.get(url, params=, headers=) | a GET request; params become ?a=1&b=2 |
http.post(url, json=) | a JSON body |
http.post(url, data={"a": "1"}) | a form |
http.post(url, data="text") or data=b"..." | text or bytes as they are |
http.post(url, data={"a": "1"}, files={"photo": ("front.jpg", jpeg, "image/jpeg")}) | a multipart form, the way a web page uploads a file |
http.put, http.patch, http.delete | the same, with that method |
http.request(method, url, ...) | any method |
Every call also takes headers=, timeout= (15 seconds at most) and
binary=True (keep the reply’s bytes for a picture or a file). A
Content-Type you put in headers is sent as it is, so data=png_bytes with
headers={"Content-Type": "image/png"} uploads a picture.
A value in files is (name, bytes, type), (name, bytes), plain bytes, or
the dict that files.pick and
files.photo give, so a picture the user took goes straight on:
files.photo(then=lambda photo: http.post(UPLOAD, data={"code": code}, files={"image": photo}, then=sent))What you get back is a Response:
r.status_code | 200, 404 and so on |
r.ok | True when the status is under 400 |
r.text | the body as text |
r.json() | the body read as JSON |
r.content | the body as bytes |
r.headers | a dict, with lowercase names |
r.url | the address that answered, after redirects |
r.raise_for_status() | raises http.HTTPError for 400 and up, else gives back r |
Errors
Section titled “Errors”| Error | Means |
|---|---|
PermissionError | network is not in the manifest, the host is not in hosts, or the user has not turned network on |
ConnectionError | no connection, the server could not be reached, or Data saver is on |
TimeoutError | no answer in time |
http.HTTPError | from raise_for_status(); e.response is the Response |
Catch them and tell the user. A plugin that lets an error escape stops, and the panel shows the error instead of your interface:
try: r = http.get(URL, params={"q": query}) r.raise_for_status()except PermissionError: state.error = "Allow internet access to search."except (ConnectionError, TimeoutError) as e: state.error = f"No connection: {e}"except http.HTTPError as e: state.error = f"The server said {e.response.status_code}."Without waiting
Section titled “Without waiting”http.get(url) waits for the answer, and the panel cannot react while it
waits. Pass then= and the call returns at once:
def search(): state.busy = True http.get(URL, params={"q": state.query}, then=got, on_error=failed)
def got(r): state.busy = False state.results = r.json()["items"] if r.ok else []
def failed(error): state.busy = False state.error = str(error)The keyboard calls got with the Response when it arrives, then draws the
panel again. If anything goes wrong, it calls failed with the exception
instead, even when the keyboard refused to send the request at all (the
internet not allowed, Data saver on, a host not in your list). Without
on_error, a refusal raises right at the call, and a later failure raises
when the answer arrives. Show
ui.progress() while state.busy is true. The tutorial
builds this step by step.
The rules every request follows
Section titled “The rules every request follows”- https only. No IP addresses and no
localhost, except the user’s own server on the local network (below). - Every redirect is checked against
hostsagain. - Replies up to 1 MB. 15 seconds at most. 60 requests a minute.
- Nothing is sent while Data saver is on.
- Each request shows in the keyboard’s Network activity under your plugin’s name, so the user can see what you sent and where.
- No cookies are kept between requests.
- The User-Agent is
WMKeyboard-Plugin, your plugin’s id and its version, such asWMKeyboard-Plugin com.example.weather/1.0.0. Services that ask apps to name themselves, such as Open Food Facts, Nominatim and Wikipedia, can tell your plugin apart. You cannot change it.
API keys
Section titled “API keys”Some services need a key. Never put yours in the plugin: anyone can unzip a
.wmplugin and read it. Let the user paste their own.
The simplest way is a secret setting. The app draws the row on your
plugin’s page with a hidden box, and you read the key like any other setting:
"permissions": ["network", "storage"],"settings": [ {"key": "api_key", "type": "secret", "label": "API key"}]from wm import plugin, ui, http
def render(): if not plugin.settings.api_key: ui.empty("Add your API key on this plugin's settings page.", icon="key") return ...The key is kept in secrets, which never appears in backups or the storage
inspector. secrets needs the storage permission.
You can also ask for the key inside your panel and save it with secrets
yourself. Saved under the same name as a secret setting, it shows on the
page as saved:
from wm import plugin, ui, http, secrets
state = plugin.state(api_key=secrets.get("api_key", ""))
def save_key(text): secrets.set("api_key", text.strip()) state.api_key = text.strip()
def render(): if not state.api_key: ui.input(label="Your API key", kind="password", on_submit=save_key) return ...
def search(q): return http.get(URL, params={"q": q}, headers={"Authorization": "Bearer " + state.api_key})The user’s own server
Section titled “The user’s own server”For a self-hosted service (a home server, a company instance), you cannot know
the address. Add a host setting. The app draws a box for it on your
plugin’s page, and the website the user types there is added to your hosts:
"permissions": ["network"],"settings": [ {"key": "server", "type": "host", "label": "Your server"}]The user may type a bare name (money.example.com) or a whole address with a
port and a path (https://money.example.com:8443/firefly). Only the host is
checked, so build your addresses from what they typed:
def base_url(): text = plugin.settings.server.strip().rstrip("/") if "://" not in text: text = "https://" + text return text
r = http.get(base_url() + "/api/items")A server on the local network
Section titled “A server on the local network”Many self-hosted services are reached at home as http://192.168.1.20:8080
or http://nas:9283. Add network.local to reach a server like that:
"permissions": ["network", "network.local"],"settings": [ {"key": "server", "type": "host", "label": "Your server", "summary": "Like https://money.example.com or http://192.168.1.20:8080"}]It is a risky permission with its own
warning, and it covers only the server the user typed: a private IP address,
a one-word name, or a name ending in .local, .lan, .home, .home.arpa,
.internal or .localdomain. There, plain http works too. Until the user
turns it on, a request to that server raises PermissionError.
The web editor cannot reach local servers, because browsers block a page
from doing so; a request there raises ConnectionError. Test those on the
phone, or with mock answers in automatic tests.
The AI model
Section titled “The AI model”With the ai permission, your plugin can ask the AI model the user chose in
the keyboard’s settings. That may be a model on the phone or a provider they
signed in to. You never see their key or which provider it is.
from wm import ai
reply = ai.ask("Write a short, friendly reply to: " + text, system="You write short text messages.")| Call | Does |
|---|---|
ai.ask(prompt, system=, max_tokens=) | waits, and returns the reply as text |
ai.ask(prompt, then=fn, on_error=fn) | returns at once; fn gets the reply |
ai.stream(prompt, on_chunk=fn, then=done) | fn gets each piece of the reply as it is written; done gets the whole reply |
ai.available() | whether the user has a model set up |
Models are slow, so prefer then= or ai.stream. Streaming feels fastest:
def write(): state.reply = "" ai.stream(state.prompt, on_chunk=add_piece)
def add_piece(piece): state.reply += pieceai raises RuntimeError when no model is set up, and ConnectionError when
Data saver is on. Check ai.available() first and show a hint instead of a
broken button.
In the web editor
Section titled “In the web editor”The web editor sends real requests from your browser to your hosts. A
browser can read the answer only if the website allows other pages to read it
(CORS). Many public APIs do. If one does not, the console says so; the phone
has no such limit.
The web editor has no AI model. ai.ask and ai.stream answer with a pretend
reply of the same shape, and the console marks it, so your code paths still
run. Install the plugin to try a real model.
