Skip to content

README.md

Latest commit

 

History

History
181 lines (130 loc) · 6.23 KB

README.md

File metadata and controls

181 lines (130 loc) · 6.23 KB
Raw

OpenCode2API

Version License Node

Language: English | 简体中文

📖 Docs | 🚀 Quick Start | 🐛 Issues

Turn a local OpenCode runtime into an OpenAI-, Anthropic-, and Gemini-compatible API gateway. Use free models (Big Pickle, Ling, MiMo, Muse Spark, Nemotron) from any OpenAI, Anthropic, or Gemini client — the free lineup rotates, so query /v1/models for the live list.

✨ Features

Feature Description
🟢 OpenAI compatible /v1/models, /v1/chat/completions, /v1/responses
🟣 Anthropic compatible /v1/messages (tool_use / thinking / SSE)
🔁 Gemini compatible (thin) POST /v1beta/interactions (alias POST /v1/interactions)
🌐 Server-side web search web_search with web_search_call + url_citation
🔑 Multi-key auth API_KEY + OPENCODE_API_KEYS merge; Bearer or x-api-key; empty skips auth
🔀 Fallback proxy free-limit 429-only OPENCODE_UPSTREAM_PROXIES rotation
📡 Streaming SSE for Chat, Responses, Messages, Interactions
🧠 Reasoning control reasoning_effort / reasoning: {"effort": "high"}
🐳 Docker deploy One-command with auto backend
🛡️ Tool safety Disabled by default
🔧 External tool bridge Client tools as tool_calls / function_call, isolated built-ins
🌐 Built-in passthrough Opt-in web_fetch only when no tools

🚀 Quick Start

Docker deploy (recommended)

# 1. Clone and configure
git clone https://github.com/samson910022/OpenCode2API.git
cd OpenCode2API
cp .env.example .env

# 2. Edit .env and set your config
# Required: API_KEY, OPENCODE_SERVER_PASSWORD

# 3. Start
docker compose up -d

# 4. Test
curl http://127.0.0.1:10000/health

No host mount by default (keeps container node_modules intact); Docker is production, local Node is dev — see Docker and Getting Started.

Node.js (local dev)

# 1. Install the OpenCode CLI
npm install -g opencode-ai
# Linux/macOS: curl -fsSL https://opencode.ai/install | bash

# 2. Clone and run
git clone https://github.com/samson910022/OpenCode2API.git
cd OpenCode2API
npm install
cp config.json.example config.json
npm run build
npm start

📖 Full guide: Development · 🚀 Getting Started

💡 Usage Examples

Chat Completions

curl -X POST http://127.0.0.1:10000/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/big-pickle",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'

Responses API (with reasoning)

curl -N -X POST http://127.0.0.1:10000/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/muse-spark-1.3-contributor-free",
    "input": "Say hi in one sentence",
    "reasoning": {"effort": "high"},
    "stream": true
  }'

More examples: API Reference

⚙️ Configuration

  • Base: API_KEY, OPENCODE_SERVER_PASSWORD, OPENCODE_SERVER_URL, OPENCODE_PROXY_PORT (PORT).
  • Tool safety: DISABLE_TOOLS=true default; external tools bridged/isolated, built-ins disabled unless allowlisted.
  • Observability: /health/details and /metrics with configurable exposure/auth.
  • Timeout & retry: OPENCODE_PROXY_REQUEST_TIMEOUT_MS, OPENCODE_PROXY_RETRY_MAX_RETRIES; OPENCODE_UPSTREAM_PROXIES only on free-limit 429.

📄 Full reference: Configuration

🔌 API Reference

Endpoints

Method Path Description
GET /health Health check
GET /health/details Structured diagnostics (configurable exposure/auth)
GET /metrics Prometheus metrics (configurable exposure/auth)
GET /v1/models List available models
POST /v1/chat/completions Chat Completions API
POST /v1/responses Responses API
POST /v1/messages Anthropic Messages API (max_tokens required, supports x-api-key)
POST /v1beta/interactions Gemini-compatible thin layer (text + google_search grounding, previous_interaction_id, store, SSE without [DONE])
POST /v1/interactions Alias of /v1beta/interactions

Protocol fidelity

Use each client's native endpoint; cross-protocol conversion is best-effort — see Architecture and Troubleshooting.

Model name formats

Formats: opencode/big-pickle, gpt5-nano (auto-resolved) and opencode/gpt5-nano — see API Reference.

🔧 Troubleshooting

Hangs: try OPENCODE_USE_ISOLATED_HOME=false. Missing model: check /v1/models. No reasoning: use Responses API with stream: true + reasoning.effort.

📖 Full guide: Troubleshooting

🔨 Development

npm run typecheck   # tsc --noEmit
npm run build       # tsc -> dist/
npm run dev         # tsx watch index.ts
npm start           # node dist/index.js
npm test -- --runInBand
docker compose up -d --build  # Docker dev

📖 Full guide: Development · 🤝 CONTRIBUTING

📄 License

MIT · See LICENSE

🙏 Acknowledgments

Maintained at samson910022/OpenCode2API, forked from TiaraBasori/opencode2api and inspired by dxxzst/opencode-to-openai and lucasliet/opencode-openai-proxy. Upstream code remains under its original MIT license; see LICENSE.