Skip to main content

​
How Magpie connects to APIYI

Magpie is an open-source application for managing models and providers for AI coding tools. After adding APIYI to Magpie, you can choose models for Codex, Claude Code, and other tools in one interface. Magpie writes the settings to each tool’s configuration files. Requests pass through a local gateway before reaching APIYI:
Enter the APIYI URL and your real API key in Magpie’s provider settings. Magpie connects your coding tools to its local gateway, which listens on 127.0.0.1:3425 by default. Keep Magpie running while using the tools. Project: github.com/yetone/magpie; official getting started guide: usemagpie.ai/docs/start.

​
Before you start

  1. Download the desktop app for macOS, Windows, or Linux from usemagpie.ai, then install and open it.
  2. Install the coding tool you want to use. See the installation sections of the Codex configuration guide or Claude Code configuration guide.
  3. Prepare API keys on the APIYI token page. Confirm that your account has an available balance and the tokens can access your selected models.
This guide covers two provider entries: APIYI and APIYI Claude. If you use only one coding tool, configure just its corresponding entry. To create both entries, use two different tokens: a token with access to GPT models for the first entry, and a token in the ClaudeCode group for the second. Magpie treats configurations that use the same key on the same host as duplicate providers.
Magpie does not automatically read API key environment variables from your terminal. Paste your key into the provider form, or add it with the CLI commands below.

​
Configure through the desktop interface

​
Configure the provider for Codex

1

Add a custom provider

Open Providers → Add provider → Custom provider and enter:End the URL at /v1. Magpie appends the request path, so do not enter the full /chat/completions path.
2

Add a Responses endpoint for GPT models

Expand More endpoints and set Responses URL to https://api.apiyi.com/v1.This guide uses gpt-5.4, which supports both Chat Completions and Responses on APIYI. Codex can use the Responses endpoint when accessing this model through Magpie.Only configure an endpoint when APIYI supports that protocol for the selected model. Responses support in Magpie’s local gateway does not mean every model on APIYI supports native Responses.
3

Fetch and select a model

Click Fetch models, select gpt-5.4 from the model list, and save the provider.Select only this model for the initial setup. Before adding other GPT models, confirm that they support the same endpoints on APIYI. Do not add image, embedding, or other non-chat models to your coding tools’ model lists.If the model you need is missing from the list, add its exact model ID manually under Models. Enter gpt-5.4 in the provider’s model field without the apiyi/ prefix.

​
Configure the provider for Claude Code

Add another Custom provider using a different token from the ClaudeCode group: The URL here does not include /v1. Magpie appends /v1/messages. After fetching models, select only the Claude model you plan to use. You can also enter claude-sonnet-4-6 manually, then save.
Separate provider entries let you manage models, protocols, and token groups independently. For details about the ClaudeCode group, see Token groups.

​
Select a model for each coding tool

  1. Open Agents and find your installed Codex or Claude Code tool.
  2. Click the tool’s current model, then find and select the model under the provider you just added: APIYI → gpt-5.4 for Codex, or APIYI Claude → claude-sonnet-4-6 for Claude Code.
  3. Close the tool’s old session, restart it, and open a new session so it reads the configuration written by Magpie.
Magpie identifies models internally as provider-id/model-id, such as apiyi/gpt-5.4. The raw model ID entered in the provider form and the full identifier selected for an agent serve different purposes.
Magpie writes the API settings for tools it manages. When troubleshooting, also check existing environment variables, project settings, and other configuration managers to make sure they are not restoring a previous service URL.

​
Verify the connection

Run a test on the provider page first, then send a short request from your coding tool, for example:
After receiving a reply, check Magpie’s request or usage records and the call logs in the APIYI console. Confirm that the request used the intended model and provider. Then ask the tool to explain a small file in your project to verify your everyday coding workflow. Fetching models successfully only confirms that the model list endpoint is reachable. Chat requests also require a matching model, token permissions, and request protocol. Provider tests send a small number of real API requests, which are billed according to model usage.

​
Configure through the CLI

If you prefer the terminal, use the following commands instead of adding providers through the interface. First, confirm that the magpie command is installed and keep the desktop app running.
If you have already created the providers in the interface, do not run provider add again. Run magpie providers to check their actual provider IDs, then substitute those IDs in the test or model-selection commands. IDs created through the interface are generated from provider names; id= in a command requests a particular ID. If an ID is already taken, Magpie may add a suffix, so check the actual IDs after adding providers through the CLI too.

​
Add the two providers

Replace sk-your-api-key in the first command with your token for GPT models:
Replace sk-your-api-key in the second command with a different token from the ClaudeCode group:

​
List models and connect the tools

Run only the command for the tool you have installed and want to configure, then start a new session in that tool. These commands update configuration; the Magpie gateway must still be running when you use the tools.

​
Test the upstream providers and local gateway

provider test sends a small number of real requests to the configured upstream endpoints. healthcheck only checks the local gateway, so it cannot by itself confirm that model requests to APIYI work.

​
Troubleshooting

Check that the API key saved in the Magpie provider is complete and valid, your APIYI account has an available balance, and the token can access the target model. Use a token from the ClaudeCode group for the Claude Code configuration. Changing terminal environment variables does not automatically update a key already saved in Magpie; edit and save the provider instead.
Check the URL for the selected protocol: use https://api.apiyi.com/v1 for OpenAI compatible and Responses, and https://api.apiyi.com for Anthropic compatible. Do not append the full request path. Confirm that the target model supports the endpoint, and do not configure a Responses endpoint for a model that only supports Chat Completions.
Check that the model is selected and saved in the provider, then check the agent’s own list of visible models. Run magpie models to see the models currently exposed by Magpie. When adding a model manually, check its raw model ID; when selecting it for a tool, check the provider prefix and ID.
Magpie uses information such as the host and key to detect duplicate providers. The two entries in this guide require two different APIYI tokens. Changing only the provider name or protocol may still result in a duplicate warning.
Confirm that the tool is installed, then reopen Magpie to check whether it is detected. After selecting a model, start a new session in the tool. Check whether existing environment variables, project settings, or other configuration managers are overriding the configuration. See the corresponding guide on this site for tool installation instructions.
Your coding tools now connect to the local gateway. Closing Magpie stops forwarding if no other gateway process is running. Reopen Magpie, then run magpie healthcheck to check whether the local gateway is online.
The model IDs in this guide demonstrate the configuration process. Confirm endpoint support and token permissions before adding other models. Current model recommendations and prices are maintained on the following pages.

Model recommendations

Choose models for your coding needs and review usage recommendations.

Model prices

View current APIYI model prices and available models.

Codex configuration guide

Find tool installation, model configuration, and usage instructions.

Claude Code configuration guide

Review installation, token groups, and troubleshooting.
Official configuration reference: github.com/yetone/magpie/blob/main/docs/reference.md. The configuration steps in this guide were checked against the project documentation and source code. Verify model listing, streaming, and tool calling with actual requests using your selected model and protocol.