δΈζθ―΄ζ | English
A complete OpenAI API compatible mock server that returns predefined test data without calling real LLMs. Perfect for developing, testing, and debugging applications that use the OpenAI API.
The easiest way to run Mock OpenAI API is using Docker from Docker Hub:
# Pull and run the latest image
docker run -p 3000:3000 zerob13/mock-openai-api:latest
# Run with custom port
docker run -p 8080:3000 zerob13/mock-openai-api:latest
# Run with verbose logging
docker run -p 3000:3000 -e VERBOSE=true zerob13/mock-openai-api:latest
# Run in background (detached mode)
docker run -d -p 3000:3000 --name mock-openai-api zerob13/mock-openai-api:latest
# Run with timezone setting
docker run -p 3000:3000 -e TZ=Asia/Shanghai zerob13/mock-openai-api:latest
Available environment variables:
PORT
: Server port (default: 3000)HOST
: Server host (default: 0.0.0.0)VERBOSE
: Enable verbose logging (default: false)TZ
: Timezone setting (default: UTC)NODE_ENV
: Node.js environment (default: production)
Create a docker-compose.yml
file:
version: '3.8'
services:
mock-openai-api:
image: zerob13/mock-openai-api:latest
ports:
- "3000:3000"
environment:
- PORT=3000
- HOST=0.0.0.0
- VERBOSE=false
restart: unless-stopped
Then run:
docker-compose up -d
npm install -g mock-openai-api
npx mock-openai-api
The server will start at http://localhost:3000
.
The mock server supports various command line options for customization:
# Start with default settings
npx mock-openai-api
# Start on custom port
npx mock-openai-api -p 8080
# Start on custom host and port
npx mock-openai-api -H localhost -p 8080
# Enable verbose request logging
npx mock-openai-api -v
# Combine multiple options
npx mock-openai-api -p 8080 -H 127.0.0.1 -v
Option | Short | Description | Default |
---|---|---|---|
--port <number> |
-p |
Server port | 3000 |
--host <address> |
-H |
Server host address | 0.0.0.0 |
--verbose |
-v |
Enable request logging to console | false |
--version |
Show version number | ||
--help |
Show help information |
# Development setup with verbose logging
npx mock-openai-api -v -p 3001
# Production-like setup
npx mock-openai-api -H 0.0.0.0 -p 80
# Local testing setup
npx mock-openai-api -H localhost -p 8080 -v
# Check version
npx mock-openai-api --version
# Get help
npx mock-openai-api --help
When the server starts, it will display the configuration being used:
π Mock OpenAI API server started successfully!
π Server address: http://0.0.0.0:3000
βοΈ Configuration:
β’ Port: 3000
β’ Host: 0.0.0.0
β’ Verbose logging: DISABLED
β’ Version: 1.0.1
# Get model list
curl http://localhost:3000/v1/models
# Chat completion (non-streaming)
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "Hello"}]
}'
# Chat completion (streaming)
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "Hello"}],
"stream": true
}'
# Image generation
curl -X POST http://localhost:3000/v1/images/generations \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "A cute orange cat",
"n": 1,
"size": "1024x1024"
}'
- β Full OpenAI API Compatibility
- β Support for streaming and non-streaming chat completions
- β Function calling support
- β Image generation support
- β Predefined test scenarios
- β Written in TypeScript
- β Docker support with multi-arch images (AMD64/ARM64)
- β Easy integration and deployment
- β Detailed error handling
- β Health check endpoint
GET /v1/models
- Get available model listGET /models
- Compatible endpoint
POST /v1/chat/completions
- Create chat completionPOST /chat/completions
- Compatible endpoint
POST /v1/images/generations
- Generate imagesPOST /images/generations
- Compatible endpoint
GET /health
- Server health status
Thinking Model - Shows reasoning process, perfect for debugging logic
{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "Calculate 2+2"}]
}
Response will include <thinking>
tags showing the reasoning process.
Function Calling Model - Supports tools and function calling
{
"model": "gpt-4-mock",
"messages": [{"role": "user", "content": "What's the weather like in Beijing today?"}],
"functions": [
{
"name": "get_weather",
"description": "Get weather information",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"},
"date": {"type": "string"}
}
}
}
]
}
Markdown Sample Model - Outputs standard Markdown format plain text
{
"model": "mock-gpt-markdown",
"messages": [{"role": "user", "content": "Any question"}]
}
Response will be a complete Markdown document with various formatting elements, perfect for frontend UI debugging. Note: This model focuses on content display and doesn't support function calling to maintain output purity.
Image Generation Model - Specialized for image generation
{
"model": "gpt-4o-image",
"prompt": "A cute orange cat playing in sunlight",
"n": 2,
"size": "1024x1024",
"quality": "hd"
}
Supports various sizes and quality settings, returns high-quality simulated images.
# Clone project
git clone https://github.com/zerob13/mock-openai-api.git
cd mock-openai-api
# Install dependencies
npm install
# Run in development mode
npm run dev
# Build project
npm run build
# Run in production mode
npm start
src/
βββ types/ # TypeScript type definitions
βββ data/ # Predefined test data
βββ utils/ # Utility functions
βββ services/ # Business logic services
βββ controllers/ # Route controllers
βββ routes/ # Route definitions
βββ app.ts # Express app setup
βββ index.ts # Server startup
βββ cli.ts # CLI tool entry
- Add new test cases in
src/data/mockData.ts
- You can add test cases for existing models or create new model types
- Rebuild the project:
npm run build
Example:
const newTestCase: MockTestCase = {
name: "New Feature Test",
description: "Description of new feature test",
prompt: "trigger keyword",
response: "Expected response content",
streamChunks: ["chunked", "streaming", "content"], // optional
functionCall: { // optional, only for function type models
name: "function_name",
arguments: { param: "value" }
}
};
Pre-built Docker images are available on Docker Hub and automatically updated with each release:
# Latest stable version
docker pull zerob13/mock-openai-api:latest
# Specific version
docker pull zerob13/mock-openai-api:v1.0.1
# Run the container
docker run -d -p 3000:3000 --name mock-openai-api zerob13/mock-openai-api:latest
# Production deployment with custom configuration
docker run -d \
--name mock-openai-api \
--restart unless-stopped \
-p 3000:3000 \
-e NODE_ENV=production \
-e PORT=3000 \
-e HOST=0.0.0.0 \
zerob13/mock-openai-api:latest
# Health check
curl http://localhost:3000/health
version: '3.8'
services:
mock-openai-api:
image: zerob13/mock-openai-api:latest
container_name: mock-openai-api
restart: unless-stopped
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- PORT=3000
- HOST=0.0.0.0
- VERBOSE=false
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health', (res) => { res.statusCode === 200 ? process.exit(0) : process.exit(1); }).on('error', () => process.exit(1));"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
If you want to build the Docker image yourself:
# Clone the repository
git clone https://github.com/zerob13/mock-openai-api.git
cd mock-openai-api
# Build the image
docker build -t my-mock-openai-api .
# Run your custom build
docker run -p 3000:3000 my-mock-openai-api
NODE_ENV
- Node environment (default: production)PORT
- Server port (default: 3000)HOST
- Server host (default: 0.0.0.0)VERBOSE
- Enable verbose logging (default: false)
# Test health check
curl http://localhost:3000/health
# Test model list
curl http://localhost:3000/v1/models
# Test thinking model
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "Explain recursion"}]
}'
# Test function calling
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4-mock",
"messages": [{"role": "user", "content": "What time is it now?"}]
}'
# Test Markdown output
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-markdown",
"messages": [{"role": "user", "content": "Any content"}]
}'
# Test streaming output
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "Tell me a story"}],
"stream": true
}'
# Test image generation
curl -X POST http://localhost:3000/v1/images/generations \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "A cute orange cat",
"n": 2,
"size": "1024x1024"
}'
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'http://localhost:3000/v1',
apiKey: 'mock-key' // can be any value
});
// Test chat completion
const completion = await client.chat.completions.create({
model: 'mock-gpt-thinking',
messages: [{ role: 'user', content: 'Hello' }]
});
console.log(completion.choices[0].message.content);
// Test streaming chat
const stream = await client.chat.completions.create({
model: 'mock-gpt-thinking',
messages: [{ role: 'user', content: 'Hello' }],
stream: true
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || '';
process.stdout.write(content);
}
// Test image generation
const image = await client.images.generate({
model: 'gpt-4o-image',
prompt: 'A cute orange cat',
n: 1,
size: '1024x1024'
});
console.log(image.data[0].url);
Issues and Pull Requests are welcome!
- Fork this project
- Create a feature branch:
git checkout -b feature/AmazingFeature
- Commit your changes:
git commit -m 'Add some AmazingFeature'
- Push to the branch:
git push origin feature/AmazingFeature
- Submit a Pull Request
This project is licensed under the MIT License. See the LICENSE file for details.
- Frontend Development: Rapidly develop and test AI features without waiting for backend API
- API Integration Testing: Verify application integration with OpenAI API
- Demos and Prototypes: Create demos that don't depend on real AI services
- Development Debugging: Debug streaming responses, function calls, and other complex scenarios
- Cost Control: Avoid API call costs during development phase
- Offline Development: Develop AI applications without internet connection
Mock OpenAI API enables you to quickly and reliably develop and test AI applications without worrying about API quotas, network connections, or costs. Start your AI application development journey today!