Put catalog models in Raycast AI with one providers.yaml.

Quick answer: enable Custom Providers, edit one file.

Raycast's path for OpenAI-compatible endpoints is the Custom Providers feature, aimed at advanced users and disabled by default. Enable it at the bottom of the AI section in Raycast Settings, use Reveal Providers Config to open the config folder, and copy the shipped providers.template.yaml to providers.yaml. The file lives at ~/.config/raycast/ai/providers.yaml. Each provider entry takes an id, a display name, a base_url, and an api_keys block; each model you want in the picker is declared explicitly with its id, a display name, and its context window, plus an abilities block describing what Raycast may ask of it. The base_url shape follows the same convention as the built-in local-model examples, which point at a /v1 root, so APIsRouter's value is https://api.apisrouter.com/v1. The file holds credentials, so treat it like any secrets file.

providers:
  - id: apisrouter
    name: APIsRouter
    base_url: https://api.apisrouter.com/v1
    api_keys:
      default: sk-APIsRouter-...
    models:
      - id: claude-sonnet-4-6
        name: Claude Sonnet 4.6
        context: 200000
        abilities:
          temperature:
            supported: true
          tools:
            supported: true
      - id: claude-haiku-4-5-20251001
        name: Claude Haiku 4.5
        context: 200000
        abilities:
          temperature:
            supported: true

Two Raycast features that sound alike, and are not.

Raycast documents two ways to bring your own AI access, and searching for one reliably surfaces the other, so the distinction is worth stating plainly. Bring Your Own Keys, the BYOK page in the Raycast manual, connects your personal Anthropic, Google, or OpenAI key (OpenRouter on iOS) to Raycast AI. It is the simpler feature, documented as working without a Pro subscription, but it is not a custom endpoint: requests route through Raycast's servers for API unification, and the manual is explicit that only models already available in Raycast AI are accessible. A gateway key does not plug in there, because BYOK never asks for a URL. Custom Providers is the feature this page configures: your own base_url, your own key, your own declared models, requests going where you point them. It is the path for a multi-vendor gateway, for local servers, and for any model Raycast's built-in list does not carry. The trade is explicitness, Raycast does not fetch the endpoint's model list for you (that convenience is a standing feature request), so the picker shows exactly what your YAML declares, nothing more and nothing less.

Declaring models honestly: ids, context, abilities.

Because there is no autodiscovery, the YAML is a contract, and each field in it does real work. The model id must match the gateway's /v1/models listing exactly; it is what travels in the request. The name is only the label Raycast shows. The context value tells Raycast how much conversation history it may pack into a request, so understating it wastes capability and overstating it produces requests the model rejects; use the documented window for the id you are declaring. The abilities block is the one people get wrong. It declares what Raycast may rely on: temperature control, vision input, system messages, tool use, reasoning effort. Declaring an ability the model lacks produces confusing runtime failures inside Raycast features rather than clean errors, and omitting one the model has silently disables the corresponding Raycast behavior. Start minimal, temperature plus tools for the models you will use with AI extensions, and add abilities as you confirm them against the model's documentation. A community-maintained Raycast extension exists specifically to manage this file from a UI, with automatic backups before each change, worth knowing if YAML-by-hand is not your preference. Either way, Raycast reads the file from disk, so after editing, give the AI settings a moment or toggle the feature to make sure the picker reflects the current file.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50
# declare these ids verbatim in providers.yaml

Choosing models for a launcher.

Because every declared model bills through the same key, the comparison loop is a picker switch: run the same quick commands on two ids for a day, then read the per-model spend in the console and keep the one that earned its place.

• Launcher AI is burst work: summarize this, rewrite that, explain the selection. claude-haiku-4-5-20251001 and gemini-3.5-flash return before the window animation finishes, which is the feel Raycast users expect.
• AI Chat sessions and long drafting earn claude-sonnet-4-6 or gpt-5.5; declare them alongside the fast tier and switch per task in the picker.
• AI extensions that call tools need a model with dependable tool use, and the abilities block declared to match; claude-sonnet-4-6 is the safe first choice there.
• deepseek-v4-flash is the volume pick for users who wire AI into every text field they touch; constant small completions add up, and the fast tier keeps the habit invisible on the balance.
• Declare few models deliberately rather than many speculatively: every entry is a picker row you scroll past, and the YAML is easy to extend the day you need another id.

Pay-as-you-go · transparent per-model pricing

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Failure modes specific to Raycast.

Configuring BYOK when you meant Custom Providers is the top-level mistake, and it is not your fault: the features share a search space. If the flow you are in asks for a vendor key but never a URL, you are in BYOK, and the gateway does not belong there. Back out to Settings, AI, and the Custom Providers toggle at the bottom. The file being ignored usually means the feature toggle is off, the file is still named providers.template.yaml, or the YAML has a syntax error, in which case Raycast has nothing valid to load and the picker simply shows no custom models. Validate the YAML before suspecting anything deeper. A model that errors on some Raycast features but not others is an abilities mismatch: tool-using AI extensions fail while plain chat works when tools was declared on a model that lacks it, or never declared on one that has it. Requests rejected for size point at an overstated context value. And note the platform boundary honestly: Custom Providers is configured on the Mac, in a local config file. If part of your Raycast use is elsewhere, check the manual for what the feature supports there before assuming parity.

Who routes Raycast AI through a gateway.

• Power users who live in the launcher and want quick AI commands on fast catalog ids without a subscription deciding which models they may touch.
• People who already route their editor and terminal tools through a gateway and want the launcher on the same key, one usage log across every surface.
• Users who want models Raycast's built-in list does not carry, DeepSeek and GLM ids included, declared once in YAML and available everywhere in the app.
• AI-extension builders who need a specific tool-capable model behind their extension, pinned by id rather than subject to a hosted list.
• Developers without access to a given vendor's billing. Top-up based access with no card requirement removes the per-provider sign-up dependency.

Verify the endpoint and debug the first command.

Run the models curl first and copy ids from its output into the YAML; typing ids from memory is the leading cause of model-not-found errors here, because the file is the only model source Raycast has. Then enable the toggle, confirm the picker shows your declared names, and run one quick AI command on the fast model. An empty picker is the toggle, the filename, or the YAML syntax. An authentication error is the api_keys block. A not-found error is an id mismatch against the listing you just curled. A command that works in chat but fails in an AI extension is the abilities declaration on that model. Once commands flow, the APIsRouter console shows per-request model, token counts, and spend. Launcher AI is hundreds of small requests rather than a few large ones, and the usage log is where that pattern becomes a number, per model, per day, on the same page as every other tool you route through the gateway.

curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001",
       "messages":[{"role":"user","content":"ping"}]}'

FAQ