👉 Full SDK Documentation | API Docs

A high-performance Rust implementation of an OpenAI-compatible API gateway for Claude Code CLI. Built on top of the robust cc-sdk, this project provides a RESTful API interface that allows you to interact with Claude Code using the familiar OpenAI API format.

🎉 Who's Using Claude Code API

• url-preview v0.6.0 - A Rust library for extracting structured data from web pages using LLMs. It leverages claude-code-api to provide Claude-powered web content extraction alongside OpenAI support.

✨ Features

• 🔌 OpenAI API Compatibility - Drop-in replacement for OpenAI API, works with existing OpenAI client libraries
• 🚀 High Performance - Built with Rust, Axum, and Tokio for exceptional performance
• 📦 Powered by claude-code-sdk-rs - Built on a robust SDK with full Claude Code CLI integration
• ⚡ Connection Pooling - Reuse Claude processes with optimized connection pooling for 5-10x faster responses
• 💬 Conversation Management - Built-in session support for multi-turn conversations
• 🖼️ Multimodal Support - Process images alongside text in your requests
• ⚡ Response Caching - Intelligent caching system to reduce latency and costs
• 🔧 MCP Support - Model Context Protocol integration for accessing external tools and services
• 📁 File Access Control - Configurable file system permissions for secure operations
• 🌊 Streaming Responses - Real-time streaming support for long-form content
• 🛡️ Robust Error Handling - Comprehensive error handling with automatic retries
• 📊 Statistics API - Monitor usage and performance metrics
• 🔄 Multiple Client Modes - OneShot, Interactive, and Batch processing modes
• 🔧 Tool Calling - OpenAI tools format support for AI tool integrations
• 🌐 WebSocket Bridge - Real-time bidirectional communication between CLI and external clients via WebSocket

🚀 Quick Start

Prerequisites

• Rust 1.75 or higher
• Claude CLI installed and configured
• (Optional) MCP servers for extended functionality

Installation

Option 1: Install from crates.io

cargo install claude-code-api

Then run:

RUST_LOG=info claude-code-api
# or use the short alias
RUST_LOG=info ccapi

Option 2: Build from source

git clone https://github.com/ZhangHanDong/claude-code-api-rs.git
cd claude-code-api-rs

Build the entire workspace (API server + SDK):

cargo build --release

Start the server:

./target/release/claude-code-api

Note: The API server automatically includes and uses claude-code-sdk-rs for all Claude Code CLI interactions.

The API server will start on http://localhost:8080 by default.

Quick Test

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-5-20251101",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

🤖 Supported Models

| Model | ID | Alias | |-------|-----|-------| | Opus 4.6 | claude-opus-4-6 | "opus" | | Sonnet 4.6 | claude-sonnet-4-6 | "sonnet" | | Haiku 4.5 | claude-haiku-4-5-20251001 | "haiku" |

# Use aliases — they always point to the latest version
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "sonnet", "messages": [{"role": "user", "content": "Hello"}]}'

📖 Core Features

1. OpenAI-Compatible Chat API

import openai

# Configure the client to use Claude Code API
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # API key is not required
)

response = client.chat.completions.create(
    model="opus",  # or "sonnet" for faster responses
    messages=[
        {"role": "user", "content": "Write a hello world in Python"}
    ]
)

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

2. Conversation Management

Maintain context across multiple requests:

# First request - creates a new conversation
response = client.chat.completions.create(
    model="sonnet-4",
    messages=[
        {"role": "user", "content": "My name is Alice"}
    ]
)
conversation_id = response.conversation_id

# Subsequent request - continues the conversation
response = client.chat.completions.create(
    model="sonnet-4",
    conversation_id=conversation_id,
    messages=[
        {"role": "user", "content": "What's my name?"}
    ]
)
# Claude will remember: "Your name is Alice"

3. Multimodal Support

Process images with text:

response = client.chat.completions.create(
    model="claude-opus-4-20250514",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "/path/to/image.png"}}
        ]
    }]
)

Supported image formats:

• Local file paths
• HTTP/HTTPS URLs
• Base64 encoded data URLs

4. Streaming Responses

stream = client.chat.completions.create(
    model="claude-opus-4-20250514",
    messages=[{"role": "user", "content": "Write a long story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

5. MCP (Model Context Protocol)

Enable Claude to access external tools and services:

# Create MCP configuration
cat > mcp_config.json << EOF
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}
EOF

# Start with MCP support
export CLAUDE_CODE__MCP__ENABLED=true
export CLAUDE_CODE__MCP__CONFIG_FILE="./mcp_config.json"
./target/release/claude-code-api

6. Tool Calling (OpenAI Compatible)

Use tools for AI integrations:

response = client.chat.completions.create(
    model="claude-3-5-haiku-20241022",
    messages=[
        {"role": "user", "content": "Please preview this URL: https://rust-lang.org"}
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "url_preview",
                "description": "Preview a URL and extract its content",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "url": {"type": "string", "description": "The URL to preview"}
                    },
                    "required": ["url"]
                }
            }
        }
    ],
    tool_choice="auto"
)

# Response will include tool_calls:
# {
#   "choices": [{
#     "message": {
#       "role": "assistant",
#       "tool_calls": [{
#         "id": "call_xxx",
#         "type": "function",
#         "function": {
#           "name": "url_preview",
#           "arguments": "{\"url\": \"https://rust-lang.org\"}"
#         }
#       }]
#     }
#   }]
# }

This feature enables seamless integration with modern AI tools like url-preview and other OpenAI-compatible tool chains. url-preview v0.6.0+ uses this exact format to extract structured data from web pages using Claude.

Agent Tools & Permissions

• Tools control (SDK): set allowed_tools / disallowed_tools and permission_mode in ClaudeCodeOptions to whitelist/blacklist and choose approval behavior.
• Runtime approvals (SDK): implement CanUseTool to decide {allow, input?/reason?} per tool call.
• MCP (server): configure via config/*.toml or mcp_config.json and use scripts under script/ (e.g., start_with_mcp.sh). The API reuses the SDK’s MCP wiring.
• Programmatic agents (SDK): define agents and setting_sources to pass