droid2api

OpenAI 兼容 API 代理服务器，用于在不同 LLM API 格式之间进行转换。

功能特性

• 三种接口模式：
  • 统一格式接口：/v1/chat/completions - 支持所有端点类型，自动格式转换
  • OpenAI 透明代理：/v1/responses - 直接转发 OpenAI 请求，零转换
  • Anthropic 透明代理：/v1/messages - 直接转发 Anthropic 请求，零转换
• 标准 OpenAI API 接口：提供完全兼容 OpenAI 的 API 端点
• 多格式支持：支持 Anthropic 和自定义 OpenAI 格式之间的自动转换
• 流式响应：自动转换 SSE (Server-Sent Events) 流式响应为标准 OpenAI 格式
• 自动刷新 API Key：集成 WorkOS 认证，自动管理和刷新访问令牌（8小时有效期，每6小时自动刷新）
• 智能 Header 管理：自动添加和管理所有必需的 Factory 特定 headers
• 配置化路由：通过 config.json 灵活配置模型和端点映射
• 开发模式：详细的日志输出，便于调试

安装

npm install

配置

1. 配置端点和模型

编辑 config.json 文件：

{
  "port": 3000,
  "endpoint": [
    {
      "name": "openai",
      "base_url": "https://app.factory.ai/api/llm/o/v1/responses"
    },
    {
      "name": "anthropic",
      "base_url": "https://app.factory.ai/api/llm/a/v1/messages"
    }
  ],
  "models": [
    {
      "name": "Claude Opus 4",
      "id": "claude-opus-4-1-20250805",
      "type": "anthropic"
    },
    {
      "name": "GPT-5 Codex",
      "id": "gpt-5-codex",
      "type": "openai"
    }
  ],
  "dev_mode": false
}

2. 配置认证（二选一）

方式一：使用环境变量（推荐用于开发/测试）

export DROID_REFRESH_KEY="your_refresh_token_here"

刷新后的 API key 会保存到工作目录的 auth.json 文件。

方式二：使用配置文件（推荐用于生产环境）

确保 ~/.factory/auth.json 文件存在并包含有效的 tokens：

{
  "access_token": "your_access_token_here",
  "refresh_token": "your_refresh_token_here"
}

刷新后的 tokens 会自动更新到原文件。

使用方法

启动服务器

npm start

或使用快捷脚本：

./start.sh

服务器默认运行在 http://localhost:3000。

API 端点总览

端点	方法	支持类型	格式转换	适用场景
/v1/models	GET	-	-	获取模型列表
/v1/chat/completions	POST	anthropic, openai	✅ 自动转换	需要统一OpenAI格式
/v1/responses	POST	仅 openai	❌ 直接转发	已是目标格式，追求性能
/v1/messages	POST	仅 anthropic	❌ 直接转发	已是目标格式，追求性能

API 端点详细说明

1. 获取可用模型列表

GET /v1/models

示例：

curl http://localhost:3000/v1/models

响应：

{
  "object": "list",
  "data": [
    {
      "id": "claude-opus-4-1-20250805",
      "object": "model",
      "created": 1704067200000,
      "owned_by": "factory"
    }
  ]
}

2. 统一格式接口 - 对话补全（带格式转换）

POST /v1/chat/completions

功能特点：

• ✅ 支持所有端点类型（anthropic, openai）
• ✅ 自动转换请求格式到目标端点格式
• ✅ 自动转换响应为标准 OpenAI 格式
• ✅ 适合需要统一接口的场景

请求参数：

• model (必需): 模型 ID
• messages (必需): 标准 OpenAI 格式消息数组
• stream (可选): 是否使用流式响应，默认 true
• max_tokens (可选): 最大输出 tokens 数
• temperature (可选): 温度参数 0-1
• top_p (可选): Top-p 采样参数

示例（Anthropic 模型，自动转换）：

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "stream": true,
    "max_tokens": 2000
  }'

示例（OpenAI 模型，自动转换）：

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-codex",
    "messages": [
      {"role": "user", "content": "写一个 Python 快速排序"}
    ],
    "stream": false
  }'

3. OpenAI 透明代理接口（不做转换）

POST /v1/responses

功能特点：

• ⚠️ 仅支持 openai 类型端点
• ❌ 请求体不做任何转换，直接转发
• ❌ 响应体不做任何转换，直接转发
• ✅ 适合已是目标格式，追求最高性能的场景

限制： 使用非 openai 类型模型会返回 400 错误：

{
  "error": "Invalid endpoint type",
  "message": "/v1/responses 接口只支持 openai 类型端点"
}

示例：

curl http://localhost:3000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-codex",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

4. Anthropic 透明代理接口（不做转换）

POST /v1/messages

功能特点：

• ⚠️ 仅支持 anthropic 类型端点
• ❌ 请求体不做任何转换，直接转发
• ❌ 响应体不做任何转换，直接转发
• ✅ 适合已是目标格式，追求最高性能的场景

限制： 使用非 anthropic 类型模型会返回 400 错误：

{
  "error": "Invalid endpoint type",
  "message": "/v1/messages 接口只支持 anthropic 类型端点"
}

示例：

curl http://localhost:3000/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024,
    "stream": true
  }'

API Key 自动刷新机制

代理服务器会自动管理 API key 的刷新：

1. 启动时刷新：服务器启动时自动获取新的 access token
2. 定期刷新：每次 API 请求前检查，如果距离上次刷新超过 6 小时则自动刷新
3. 令牌有效期：access token 有效期为 8 小时
4. 自动保存：刷新后的 tokens 自动保存到相应的配置文件

刷新日志示例：

[INFO] Refreshing API key...
[INFO] Authenticated as: user@example.com (John Doe)
[INFO] User ID: user_01K69S755R2TWYFWKPSP74TRKZ
[INFO] Organization ID: org_01K69S7KKYK6F2WYJ8CB384GW6
[INFO] API key refreshed successfully

接口模式选择指南

何时使用 /v1/chat/completions（统一格式）

✅ 推荐场景：

• 需要统一的 OpenAI 兼容接口
• 应用代码已使用 OpenAI SDK
• 需要在不同 LLM 提供商之间切换
• 不关心轻微的性能损耗

❌ 不推荐场景：

• 已有原生格式的请求/响应处理逻辑
• 对性能要求极高（需要避免格式转换开销）

何时使用 /v1/responses（OpenAI 透明代理）

✅ 推荐场景：

• 请求已经是目标 OpenAI 端点格式
• 追求最高性能，避免格式转换开销
• 只使用 OpenAI 端点

❌ 不推荐场景：

• 使用 Anthropic 端点（会返回错误）
• 需要格式转换

何时使用 /v1/messages（Anthropic 透明代理）

✅ 推荐场景：

• 请求已经是标准 Anthropic 格式
• 追求最高性能，避免格式转换开销
• 只使用 Anthropic 端点

❌ 不推荐场景：

• 使用 OpenAI 端点（会返回错误）
• 需要格式转换

格式转换说明

注意：仅 /v1/chat/completions 接口会进行格式转换，/v1/responses 和 /v1/messages 直接转发，不做任何转换。

Anthropic 格式转换（仅 /v1/chat/completions）

请求转换：

• messages → messages（提取 system 消息到顶层）
• max_tokens → max_tokens（默认 4096）
• 文本内容包装为 {type: 'text', text: '...'}
• 工具格式转换

响应转换：

• 转换 SSE 事件：message_start, content_block_delta, message_delta, message_stop
• 转换为标准 OpenAI chunk 格式
• 映射停止原因：end_turn → stop, max_tokens → length

OpenAI 格式转换（仅 /v1/chat/completions）

请求转换：

• messages → input
• max_tokens → max_output_tokens
• 用户消息：text → input_text
• 助手消息：text → output_text
• 提取 system 消息为 instructions 参数

响应转换：

• 转换 SSE 事件：response.created, response.in_progress, response.done
• 转换为标准 OpenAI chunk 格式

Header 管理

代理服务器会自动添加所有必需的 headers：

Anthropic 端点

• x-model-provider: anthropic
• x-factory-client: cli
• user-agent: a$/JS 0.57.0
• anthropic-version: 2023-06-01
• anthropic-beta: interleaved-thinking-2025-05-14
• x-stainless-helper-method: stream（流式请求）
• 自动生成的 UUID：x-session-id, x-assistant-message-id

OpenAI 端点

• x-factory-client: cli
• user-agent: cB/JS 5.22.0
• 自动生成的 UUID：x-session-id, x-assistant-message-id

开发模式

在 config.json 中设置 dev_mode: true 可以启用详细日志：

{
  "dev_mode": true
}

日志内容包括：

• 完整的请求和响应 headers
• 请求体和响应体
• 格式转换过程
• SSE 事件处理详情

端口冲突处理

如果端口 3000 已被占用，可以：

1. 修改配置文件：编辑 config.json 中的 port 字段
2. 或者结束占用进程：

   lsof -ti:3000 | xargs kill -9
   

故障排查

启动时报错 "Refresh token not found"

原因：未配置 refresh token

解决方案：

• 设置环境变量 DROID_REFRESH_KEY
• 或配置 ~/.factory/auth.json 文件

请求返回 401 错误

可能原因：

1. refresh token 已过期或无效
2. API key 刷新失败

解决方案：

• 检查日志中的刷新错误信息
• 重新获取有效的 refresh token
• 确认 ~/.factory/auth.json 中的 tokens 正确

响应格式错误

原因：模型类型配置错误

解决方案：

• 检查 config.json 中模型的 type 字段
• Anthropic 模型使用 "type": "anthropic"
• OpenAI 模型使用 "type": "openai"

技术架构

• 语言：Node.js (ES Modules)
• 框架：Express
• HTTP 客户端：node-fetch
• 认证：WorkOS OAuth 2.0 Refresh Token Flow

许可证

MIT