⚡ Puter API Bridge

Turn the Puter.js SDK into a free, unlimited OpenAI-compatible API server.

Puter API Bridge is a local server that translates OpenAI API requests into Puter.js SDK calls, giving you access to 500+ AI models — including GPT-4o, Claude, Gemini, Mistral, and more — through the familiar OpenAI API format. No API keys required. No usage limits. Completely free.

Features

• 🆓 Free & Unlimited — Powered by Puter.js's free AI tier
• 🔌 OpenAI-Compatible — Drop-in replacement for the OpenAI API
• 🌊 Streaming Support — Real-time token streaming via SSE
• 🤖 500+ Models — GPT-4o, Claude, Gemini, Mistral, DeepSeek, and more
• 🔧 Tool Calling — Full function/tool calling support
• 🔑 Optional Auth — Protect your local endpoint with an API key
• 🖥️ Background Mode — Runs as a daemon, terminable via CLI
• 📋 Logging — Request logging and log file viewing

Quick Start

Installation

npm i -g @npcoder/puter-api

Start the Server

# Start in background (daemonized)
puter-api start --api_key YOUR_API

# Or start in foreground
puter-api start --foreground

### Stop the Server

```bash
puter-api stop

### Check Status

```bash
puter-api status

Usage

With the OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8741/v1",
    api_key="unused"  # Any string works
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello, world!"}]
)

print(response.choices[0].message.content)

With the OpenAI Node.js SDK

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'http://127.0.0.1:8741/v1',
    apiKey: 'unused'
});

const response = await client.chat.completions.create({
    model: 'claude-sonnet-4',
    messages: [{ role: 'user', content: 'Hello!' }]
});

console.log(response.choices[0].message.content);

With cURL

curl http://127.0.0.1:8741/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Say hello!"}]
  }'

Streaming

curl http://127.0.0.1:8741/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

CLI Reference

| Command | Description | |---------|-------------| | puter-api start | Start the server (background) | | puter-api start --foreground | Start in foreground | | puter-api start --port 3000 | Use a custom port | | puter-api start --api-key my-secret | Require an API key | | puter-api start --default-model claude-sonnet-4 | Set default model | | puter-api stop | Stop the background server | | puter-api status | Check server status | | puter-api logs | View recent logs | | puter-api logs -f | Follow logs in real-time |

API Endpoints

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint. Supports:

• Messages array with system, user, assistant, and tool roles
• model — Any Puter-supported model name
• stream — Boolean for SSE streaming
• temperature — 0-2 sampling temperature
• max_tokens — Maximum response length
• tools — Function/tool definitions

GET /v1/models

Returns available models in OpenAI format.

GET /health

Health check endpoint.

Available Models

You can use any model available on Puter. Common ones include:

| Model | Description | |-------|-------------| | gpt-4o | OpenAI GPT-4o | | gpt-4o-mini | OpenAI GPT-4o Mini | | gpt-5-nano | OpenAI GPT-5 Nano | | gpt-5.4-nano | OpenAI GPT-5.4 Nano | | claude-sonnet-4 | Anthropic Claude Sonnet 4 | | claude-sonnet-4-5 | Anthropic Claude Sonnet 4.5 | | gemini-2.5-flash | Google Gemini 2.5 Flash | | gemini-2.5-flash-lite | Google Gemini 2.5 Flash Lite | | gemini-2.5-pro | Google Gemini 2.5 Pro |

Run GET /v1/models to see the full list of 500+ models.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PUTER_API_PORT | 8741 | Server port | | PUTER_API_HOST | 127.0.0.1 | Server host | | PUTER_API_KEY | (none) | Required API key | | PUTER_API_DEFAULT_MODEL | gpt-4o | Default model |

Authentication

On first run, Puter.js will open a browser window to authenticate your Puter account. This is a one-time setup. Your credentials are stored locally by the Puter.js SDK.

License

MIT