docs: hosted extra-openai-models.yaml gotchas (model_name, api_key_name, Chat Completions)

[cursor]

The extra-OpenAI YAML path works for a hosted Chat Completions host, not only localhost LocalAI. Three easy misses in https://llm.datasette.io/en/stable/openai-models.html#adding-more-openai-models and https://llm.datasette.io/en/stable/other-models.html :

1. model_name is required (KeyError without it). It is the upstream catalog id, not the local model_id.
2. If api_base is set, the saved openai key is not sent. Set api_key_name and llm keys set <name>.
3. Do not add responses: true unless you intend /v1/responses. Chat Completions is the default and the one that matches a generic OpenAI-compat /v1/chat/completions host.

PZERO is a live Chat Completions host. Public catalog: GET https://api.pzero.studio/v1/models. Default text id: deepseek-v4-flash. Prepaid Bearer key (pzero_…). api_base is the /v1 root.

Config dir: dirname "$(llm logs path)" then extra-openai-models.yaml:

- model_id: pzero
  model_name: deepseek-v4-flash
  api_base: "https://api.pzero.studio/v1"
  api_key_name: pzero

llm keys set pzero
llm -m pzero "ping"

Do not prefix openai/ on model_name here (that prefix is LiteLLM). Do not append /chat/completions to api_base. Do not set vision or embedding models unless the catalog id actually supports them.

No first-party plugin asked. If a named vendor subsection is too much, the three gotchas are the docs gap.

[mikemikimike]

I opened #1646 with a documentation fix for this issue. It adds a hosted OpenAI-compatible extra-openai-models.yaml example and calls out the three important settings: model_name is the upstream identifier, api_key_name is needed when api_base is set, and Chat Completions is the default unless responses: true is intentional.

Remote validation: the Read the Docs build passed. GitHub Test and Cog runs are action_required with no jobs; approving fork workflow runs requires repository admin rights (HTTP 403), so there is no code failure to fix.