Mock AI API

A local mock API for testing applications that integrate with OpenAI and Anthropic-compatible endpoints. It returns deterministic responses and can simulate streaming, tool calls, API errors, embeddings, moderation, files, batches, and response retrieval without making requests to a real provider.

Features

• OpenAI-compatible endpoints on port 8011
• Anthropic-compatible endpoints on port 8012
• Non-streaming and Server-Sent Events (SSE) streaming responses
• Scenario-based responses selected with a :mock-* model suffix
• Tool calls and tool-use streams
• Simulated rate limits and other API errors
• OpenAI models, completions, responses, embeddings, moderation, image, and audio endpoints
• Anthropic messages, token counting, batches, and file endpoints
• In-memory state with no API keys, accounts, or external services required

Requirements

• Python 3.11+

Quick start

Install the command-line server from PyPI with pipx:

pipx install mock-ai-api
mock-ai-api

If you prefer a virtual environment, install it with pip instead:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install mock-ai-api
mock-ai-api

From source

For local development or contributing, clone the repository and install the editable development dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
mock-ai-api

The requirements.txt file remains available for environments that prefer it: python -m pip install -r requirements.txt followed by python server.py.

The servers start at:

• OpenAI: http://127.0.0.1:8011
• Anthropic: http://127.0.0.1:8012

Use --openai-port or --anthropic-port to customize the launch:

mock-ai-api --openai-port 9001 --anthropic-port 9002
# or: python3 server.py --openai-port 9001 --anthropic-port 9002

Examples

Check both health endpoints:

curl http://127.0.0.1:8011/health
curl http://127.0.0.1:8012/health

Create an OpenAI-compatible chat completion:

curl http://127.0.0.1:8011/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-4.1:mock-text",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Request a simulated tool call:

curl http://127.0.0.1:8011/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-4.1:mock-tool-call",
    "messages": [{"role": "user", "content": "Write a file"}]
  }'

Create an Anthropic-compatible message:

curl http://127.0.0.1:8012/v1/messages \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514:mock-text",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Set "stream": true in supported requests to receive streaming events.

Scenarios

Append a scenario name to a model with :mock-*. The registry in app/scenarios.py is the source of truth for scenario behavior, documented examples, and advertised scenario models.

Extending scenarios

1. Add the scenario metadata to SCENARIOS in app/scenarios.py, including its provider, endpoint, response mode, optional error status, and example model.
2. Implement the provider-specific behavior in the relevant builder or streaming path.
3. The provider model catalog is generated from the registry; do not add a duplicate catalog entry by hand.
4. Add direct API tests, SDK coverage where the endpoint is SDK-supported, and update this table to describe the behavior.

Development

Run the test suite with:

python3 -m pytest -q

The test clients instantiate each application directly, so the servers do not need to be running when tests execute. The SDK compatibility suite starts isolated local Uvicorn processes and is tested with openai==2.16.0 and anthropic==0.76.0. Its process-level fixture relies on POSIX file-descriptor inheritance, so those integration tests are skipped on non-POSIX platforms.

Project layout

app/
  openai_app.py       OpenAI-compatible routes
  anthropic_app.py    Anthropic-compatible routes
  openai/             OpenAI response builders and catalog
  anthropic/          Anthropic response builders and catalog
  scenarios.py        Scenario registry and model-suffix parsing
  schemas.py          Request models
server.py             Starts both mock servers
tests/                API behavior tests

Limitations

This project is intended for local development and automated tests. It is not a production inference server: responses are mocked, state is process-local and in-memory, authentication is not implemented, and the supported API surface is intentionally incomplete.

License

This project is licensed under the MIT License.