Skip to content

Install Skills ​

Higher credit usage on the first session is normal

Agents attach fixed tool definitions and a system prompt to every request, often tens of thousands of tokens. On the first session this content is written to the cache and billed as full input, so credit usage is higher. Later requests hit the cache and are billed at the much lower cached rate, so usage drops noticeably. This is expected behavior — you are not being overcharged. For high-volume usage, please contact support — we can offer discounts.

AI Agents overview: tools, API base URLs and FAQs

ModelFold offers two skills. Once installed, the agent knows how to use ModelFold:

SkillWhat it adds
modelfold-modelsGenerate images, video and speech, and call chat models
modelfold-chat-agentsConfigure Claude Code, Codex and Grok Build to run on ModelFold

Install both with one command ​

bash
npx skills add https://modelfold.ai -g -a claude-code -a codex -a grok -y

To install only one, add --skill modelfold-models or --skill modelfold-chat-agents. The flags are explained below.

Then set your API key (see "Step 2: Set your API key" below) and restart the agent.


Generate images, video and speech (modelfold-models) ​

modelfold-models teaches the agent how to use ModelFold: read the model list, pick the endpoint for the model type, send the request, wait for the result and save the file.


Prerequisites ​

  • A skill-aware coding agent such as Claude Code, Codex, Cursor or Grok Build.
  • Node.js 22.20 or later (required by npx skills).

Step 1: Install the skill ​

Run this in a terminal. The whole command can be copied as-is and does not prompt:

bash
npx skills add https://modelfold.ai --skill modelfold-models -g -a claude-code -a codex -a grok -y
  • --skill modelfold-models installs only this skill. Without it, every skill on the site is installed (there is also modelfold-chat-agents).
  • -g installs for the current user, available in every project. Without -g, the skill is installed only in the current project.
  • -a chooses the agents. The three names above are Claude Code, Codex and Grok Build.
  • -y skips the picker. Without -y and -a, a terminal stops and waits for a choice; with no interactive terminal the command fails and installs nothing.
  • Do not run the command in a project without these flags. Inside an agent, the CLI writes every skill into dozens of agent folders in the current directory.

Where it is installed:

AgentPath
Claude Code~/.claude/skills/modelfold-models
Codex~/.agents/skills/modelfold-models
Grok Build~/.grok/skills/modelfold-models

Claude Code and Grok Build are symlinks to the Codex copy.

Cursor ​

The skills CLI treats Cursor as a universal agent. With -g it does not write Cursor's global directory ~/.cursor/skills. Run this inside the project:

bash
npx skills add https://modelfold.ai --skill modelfold-models -a cursor -y

If Cursor needs a model ID typed by hand, copy it from All model IDs.

The skill lands in that project's .agents/skills/modelfold-models.

To use it from every project in Cursor, add a symlink after the global install:

bash
mkdir -p ~/.cursor/skills
ln -sfn ~/.agents/skills/modelfold-models ~/.cursor/skills/modelfold-models

To update later, run the same install command again.


Step 2: Set your API key ​

The skill reads the key from the MODELFOLD_API_KEY environment variable, so it never goes into your project.

macOS and Linux ​

Export it in the shell you start the agent from, or add it to your shell profile (~/.zshrc, ~/.bashrc):

bash
export MODELFOLD_API_KEY=your_key

Windows (PowerShell) ​

powershell
$env:MODELFOLD_API_KEY = "your_key"
setx MODELFOLD_API_KEY "your_key"

setx only affects windows opened afterwards. To use it right away, set $env: as well.


Step 3: Try it ​

Restart the agent from a shell where MODELFOLD_API_KEY is set, then ask in plain language:

text
Use the modelfold-models skill to list the image models on ModelFold, then generate a 1:1 product photo of a white ceramic mug on a light oak table with one of them. Save the image to ./output.

Have the agent pick a text-to-image model. The cheapest rows are usually image-to-image, upscale or background removal, and they fail without an image URL.


Security ​

  • Keep the API key in an environment variable. Don't paste it into chats, screenshots or files that get committed.
  • If a key leaks, revoke it in Console → API Keys and create a new one.

The default coding-agent recommendation is claude-opus-5-5; select media models separately for media tasks.


Configure Claude Code / Codex / Grok (modelfold-chat-agents) ​

ModelFold (modelfold.ai) serves its chat models over each vendor's own wire protocol. When the agent speaks the same protocol as the model, no adapter is needed. When they differ, a local translation proxy has to sit in between; see When protocols don't match below.

One section per agent, each self-contained: how to list the models that agent can run, what configuration it needs, and how it fails. Codex CLI, Claude Code and Grok Build are covered so far; other agents will be added later as sibling sections. The protocol-mismatch section is shared, so a new agent does not need its own pairing table.

WARNING

⚠️ Use the latest models for agent features

For agent features, use the latest model in each series. Some older models currently support chat requests only; connecting them to an agent may cause request errors or unexpected results. These models are marked "Chat only" on their model pages in the Market. The models each agent can use are listed in that agent's model listing.

Install ​

bash
npx skills add https://modelfold.ai --skill modelfold-chat-agents -g -a claude-code -a codex -a grok -y

Once installed, you can simply ask your agent, for example "Configure Codex to use ModelFold", and the skill follows the steps on that agent's page. You can also configure the agent by hand with the pages below.

Prerequisites ​

A ModelFold API key created at <https://modelfold.ai/account>, exported as MODELFOLD_API_KEY, and the agent you want to configure already installed.

The model-listing snippets need curl and jq on your PATH. Most systems do not ship jq: brew install jq, apt install jq or winget install jqlang.jq.

In PowerShell, curl is an alias for Invoke-WebRequest and does not accept these arguments. Write curl.exe as in the Windows snippets below. Under cmd.exe the snippets must be rewritten; they cannot be pasted as is.

The three agents at a glance ​

Summarized from the agent pages; see each page for details.

Claude Code ​

  • Protocol: Anthropic Messages
  • List models: GET https://modelfold.ai/anthropic/v1/models
  • Where the config goes: environment variables, or env in ~/.claude/settings.json
  • Base URL: ANTHROPIC_BASE_URL=https://modelfold.ai/anthropic
  • Credential: raw key in ANTHROPIC_AUTH_TOKEN

Set all four model variables: ANTHROPIC_MODEL selects the main model, and ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL map the three model tiers. Haiku is required, otherwise background tasks may request an original Claude model name and fail. The examples use claude-sonnet-5-5, claude-opus-5-5, and claude-haiku-5-5; use the ids returned by GET https://modelfold.ai/anthropic/v1/models with your ModelFold key.

bash
export ANTHROPIC_BASE_URL=https://modelfold.ai/anthropic
export ANTHROPIC_AUTH_TOKEN=$MODELFOLD_API_KEY
export ANTHROPIC_MODEL=claude-sonnet-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5

PowerShell and settings.json examples.

Codex CLI ​

  • Protocol: OpenAI Responses
  • List models: GET https://modelfold.ai/openai/v1/models
  • Where the config goes: [model_providers.ModelFold] in ~/.codex/config.toml
  • Base URL: https://modelfold.ai/openai/v1
  • Credential: env_key = "MODELFOLD_API_KEY"

Grok Build ​

  • Protocol: Responses (api_backend = "responses")
  • List models: GET https://modelfold.ai/xai/v1/models
  • Where the config goes: [model.ModelFold] in ~/.grok/config.toml
  • Base URL: https://modelfold.ai/xai/v1
  • Credential: env_key = "MODELFOLD_API_KEY"

Rules shared by all three agents:

  1. Take model names from the listing, not from memory. Re-run the listing every time; the model set changes.
  2. Authenticate with Authorization: Bearer. A header literally named apikey is rejected with 401.
  3. Do not put the full request URL in the base URL. The agent appends /v1/messages or /responses itself.
  4. Put the configuration in user-level files, not project-level ones. Project-level files are either ignored or committed to the repository.

When protocols don't match ​

Every agent here speaks one wire protocol, and every ModelFold listing is served over one protocol. When the two match, configure the agent as its page says and traffic goes straight to modelfold.ai. When they don't, you need a local translation proxy.

When you need a proxy ​

  1. Read the agent's page: which protocol it speaks and which path it appends.
  2. Read the model's listing: which protocol ModelFold serves it over.
  3. Same protocol: no proxy. Different protocol: tell the user a local translation proxy is needed, and ask before writing one. The user may already have a proxy, or may not want one this time. Do not generate proxy code without asking.
  4. Once the user has a proxy, or has explicitly asked for one, point the agent's base URL at the proxy, not at modelfold.ai.
  5. List models from the model side's listing, not the agent's native listing. Fill the agent's model setting with an id from that list. Its built-in default names and aliases only hold for its native protocol.

What the proxy exposes ​

Model listingModelFold requestProtocol
GET /openai/v1/modelsPOST /openai/v1/responsesResponses
GET /anthropic/v1/modelsPOST /anthropic/v1/messagesMessages
GET /xai/v1/modelsPOST /xai/v1/responsesResponses

The proxy listens on the path the agent will build and forwards to the ModelFold request for that listing. Both directions must be translated, including the streaming and tool calls the agent actually sends. Authentication to ModelFold is Authorization: Bearer $MODELFOLD_API_KEY.

When a future agent's listing is not in this table, add a row. The rules in this section do not change.

When writing a proxy ​

Only write one when the user explicitly asks. Map honestly; do not invent platform behavior.

  1. Learn both protocol shapes from real agent requests and the official protocols, not from memory. Capture what the agent actually sends (claude --debug, Codex logs, GROK_LOG_FILE) and the shape ModelFold expects on the model path. Field tables pieced together from training data are usually incomplete.
  2. Forward the model id unchanged. Do not hard-code a default model name, and do not rewrite sonnet / opus / claude-* into GPT slugs, or the other way round.
  3. If the proxy serves GET /models, return the list in the shape the agent expects, with data from the model side's ModelFold listing. Passing the other side's document through as is has the wrong shape. A failed listing is an error; do not invent a fake model.
  4. Tool calls must complete a round. id / call_id / tool_use_id stay consistent between the request and the tool result in the next turn. Do not drop tools. If ModelFold rejects tools, pass that error back.
  5. Streaming must end the way the agent ends a turn. Emit the event sequence the agent consumes, including the terminal event. If ModelFold errors or the stream drops mid-way, the agent must see a failure, not an HTTP 200 with an empty completed turn.
  6. Do not inject new user/assistant content to work around protocol limits. Some Messages models reject a conversation that ends with an assistant turn. Inventing a follow-up user message makes the request valid but changes the meaning of the turn, and Codex will then keep continuing. Either reshape losslessly or return the server error as is.

Pointing the agent at the proxy ​

The listen address is whatever the proxy binds. The agent's base URL still follows the rules on its page: Claude Code appends /v1/messages to ANTHROPIC_BASE_URL, Codex appends /responses to base_url, and Grok Build appends /responses to base_url when api_backend = "responses". So leave that suffix out of the value.

Claude Code running a Responses model:

bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:<port>
export ANTHROPIC_AUTH_TOKEN=$MODELFOLD_API_KEY
export ANTHROPIC_MODEL=…
export ANTHROPIC_DEFAULT_SONNET_MODEL=…
export ANTHROPIC_DEFAULT_OPUS_MODEL=…
export ANTHROPIC_DEFAULT_HAIKU_MODEL=…

Replace every … in these four variables with an id from GET /openai/v1/models supported by your proxy, rather than the Claude ids above or built-in aliases.

ANTHROPIC_MODEL is an id from GET /openai/v1/models, not Claude Code's sonnet / opus aliases.

Codex CLI running a Messages model:

toml
model = "…"
model_provider = "ModelFold"
[model_providers.ModelFold]
name = "ModelFold"
base_url = "http://127.0.0.1:<port>/v1"
env_key = "MODELFOLD_API_KEY"
wire_api = "responses"

model is an id from GET /anthropic/v1/models. base_url still does not include /responses.

Do not leave the agent's base URL pointing at modelfold.ai while sending an id from another listing, and do not point the agent straight at the model side's ModelFold prefix without translation.

What this skill does not provide ​

This skill does not include, generate or name any translation proxy. It only states the listen path, the ModelFold path, which listing to read, and which agent setting takes the proxy address. Proxy code is written only when the user explicitly asks.

ModelFold — one API for all the best AI models.