nezumi/transfer-api
1
0
Fork 0
mirror of https://github.com/Nezumi-2711/transfer-api.git synced 2026-09-22 13:48:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update bilingual README

Browse Source
This commit is contained in:
老王
2026-06-20 03:30:40 +08:00
parent cf79b0a749
commit d95c1f3f0f
1 changed files with 223 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+223 -35
View File
@@ -1,28 +1,42 @@
# unlimited.surf Transfer API Worker # unlimited.surf Transfer API Worker
Cloudflare Worker adapter for `https://unlimited.surf` that exposes OpenAI-compatible `/v1/*` routes and Anthropic-compatible `/v1/messages` plus `/anthropic/*` aliases. 中文 | [English](#english)
## Deploy from GitHub with Cloudflare 这是一个 Cloudflare Worker 中转适配器，用于把 `https://unlimited.surf` 转换成 OpenAI 兼容的 `/v1/*` 接口，以及 Anthropic/Claude Code 兼容的 `/v1/messages` 和 `/anthropic/*` 接口。
You can push this project to GitHub and let Cloudflare deploy it automatically on every commit. ## 功能概览
### 1. Push the project to GitHub - OpenAI 兼容：`/v1/chat/completions`、`/v1/responses`、`/v1/models`、`/v1/files`。
- Anthropic 兼容：`/v1/messages`、`/v1/models`、`/anthropic/v1/messages`、`/anthropic/v1/models`。
- unlimited.surf 原始接口代理：`/api/*` 会直接转发到上游。
- Web Search：映射到上游 `POST /api/search`。
- Merge AI：映射到上游 `POST /api/merge`。
- Files：上传/提取映射到上游 `POST /api/attachments/extract`。
- Agent Setup、Codex、MCP：提供说明和配置入口，分别是 `/v1/setup`、`/v1/codex`、`/v1/mcp`。
Create a GitHub repository, then push this project directory to it. Do not commit your unlimited.surf API key. 注意：MCP server 仍然需要在本地 agent、IDE 或 Claude Code/Codex 环境里运行。这个 Worker 只提供模型 API 端点，不会在 Cloudflare 边缘侧读取或修改你的本地文件。
### 2. Connect the GitHub repository in Cloudflare ## 通过 GitHub 关联 Cloudflare 自动部署
1. Open the Cloudflare Dashboard. 可以把本项目推送到 GitHub 私有仓库，然后让 Cloudflare 在每次提交后自动部署。
2. Go to `Workers & Pages`.
3. Choose `Create`.
4. Choose `Import a repository` or `Connect to Git`.
5. Authorize Cloudflare to access your GitHub account if prompted.
6. Select the repository that contains this project.
7. Set the project root directory to `/` unless you put this project in a subdirectory.
### 3. Configure build and deploy settings ### 1. 推送到 GitHub
Use these settings in the Cloudflare deploy form: 创建 GitHub 仓库并推送本项目。不要把 unlimited.surf API key 提交进仓库。
### 2. 在 Cloudflare 连接 GitHub 仓库
1. 打开 Cloudflare Dashboard。
2. 进入 `Workers & Pages`。
3. 点击 `Create`。
4. 选择 `Import a repository` 或 `Connect to Git`。
5. 按提示授权 Cloudflare 访问 GitHub。
6. 选择这个项目所在的 GitHub 仓库。
7. Root directory 填 `/`，除非你把项目放在仓库子目录里。
### 3. 配置构建和部署参数
Cloudflare 部署表单里可以使用：
```text ```text
Framework preset: None Framework preset: None
@@ -32,53 +46,53 @@ Root directory: /
Wrangler config: wrangler.toml Wrangler config: wrangler.toml
``` ```
If Cloudflare shows only one command field for Workers, use: 如果 Cloudflare 只提供一个命令输入框，可以填：
```bash ```bash
npm install && npx wrangler deploy npm install && npx wrangler deploy
``` ```
### 4. Add the API key as a Cloudflare secret ### 4. 添加 Cloudflare Secret
After the Worker project is created, add this secret in the Worker settings: 在 Worker 设置里添加 Secret：
```text ```text
UNLIMITED_SURF_API_KEY=<your unlimited.surf key> UNLIMITED_SURF_API_KEY=<你的 unlimited.surf key>
``` ```
In the Cloudflare Dashboard this is usually under: 通常位置是：
```text ```text
Workers & Pages -> your Worker -> Settings -> Variables -> Secrets Workers & Pages -> 你的 Worker -> Settings -> Variables -> Secrets
``` ```
Keep the key as a secret. Do not put it in `wrangler.toml`, `README.md`, or GitHub repository files. 请只把 key 放到 Secret 里，不要写进 `wrangler.toml`、`README.md` 或任何 GitHub 文件。
### 5. Deploy and verify ### 5. 部署后验证
Trigger a deploy from Cloudflare or push a new commit to GitHub. After deployment, open: 部署完成后打开：
```text ```text
https://<your-worker>.workers.dev/health https://<your-worker>.workers.dev/health
``` ```
You should see a JSON response with `"ok": true`. 看到 JSON 里有 `"ok": true` 即表示 Worker 正常运行。
Then test the OpenAI-compatible route: 测试 OpenAI 模型列表：
```bash ```bash
curl https://<your-worker>.workers.dev/v1/models curl https://<your-worker>.workers.dev/v1/models
``` ```
And test the Anthropic setup route: 测试 Anthropic/Agent 配置说明：
```bash ```bash
curl https://<your-worker>.workers.dev/v1/setup curl https://<your-worker>.workers.dev/v1/setup
``` ```
## Manual deploy with Wrangler ## 本地 Wrangler 手动部署
You can also deploy directly from your local machine: 也可以在本地直接部署：
```powershell ```powershell
npm install -g wrangler npm install -g wrangler
@@ -87,7 +101,181 @@ wrangler secret put UNLIMITED_SURF_API_KEY
wrangler deploy wrangler deploy
``` ```
Use your unlimited.surf key as the secret value. You can also omit the secret and pass a key per request with `Authorization: Bearer <key>` or `x-api-key: <key>`. `wrangler secret put` 时输入你的 unlimited.surf key。也可以不配置 Secret，而是在每次请求里传：`Authorization: Bearer <key>` 或 `x-api-key: <key>`。
## OpenAI 兼容接口
Base URL：
```text
https://<your-worker>.workers.dev/v1
```
支持接口：
- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /v1/responses`
- `POST /v1/search`
- `POST /v1/merge`
- `GET /v1/key`、`GET /v1/usage`
- `POST /v1/files`
- `POST /v1/files/extract`、`POST /v1/attachments/extract`
- `GET /v1/setup`、`GET /v1/codex`、`GET /v1/mcp`
示例：
```bash
curl https://<your-worker>.workers.dev/v1/chat/completions \
-H "Authorization: Bearer <key>" \
-H "Content-Type: application/json" \
-d '{"model":"gateway-gpt-5","messages":[{"role":"user","content":"Hello"}],"stream":true}'
```
## Anthropic / Claude Code 兼容接口
Base URL：
```text
https://<your-worker>.workers.dev
```
支持接口：
- `POST /v1/messages`
- `GET /v1/models`
- `POST /anthropic/v1/messages`
- `GET /anthropic/v1/models`
- `GET /v1/setup`、`GET /v1/codex`、`GET /v1/mcp`
Claude Code PowerShell 示例：
```powershell
$env:ANTHROPIC_BASE_URL = "https://<your-worker>.workers.dev"
$env:ANTHROPIC_AUTH_TOKEN = "<key>"
$env:ANTHROPIC_API_KEY = "<key>"
$env:ANTHROPIC_MODEL = "claude-opus-4-7-20260101"
claude
```
## 功能映射
- Chat 映射到上游 `POST /api/chat`。
- Web Search 在调用 `/v1/search`、传入 `web_search_options`、传入 `query`，或包含 web search tool 时映射到 `POST /api/search`。
- Merge AI 在调用 `/v1/merge`、传入 `merge: true`，或传入 2 个以上 `models` 时映射到 `POST /api/merge`。
- Models 映射到上游 `GET /api/models`，如果上游不可用会返回内置 fallback 模型列表。
- Files 映射到上游 `POST /api/attachments/extract`。如果需要持久化文件，需要额外接入 Cloudflare KV 或 R2。
- Codex、Agent Setup、MCP 是配置说明入口；MCP 工具执行仍然发生在本地 agent/IDE 里。
- Embeddings、audio、images 会返回 `501`，因为当前提供的 unlimited.surf 文档中没有这些原生接口。
## 原始上游代理
任何 `/api/*` 请求都会被转发到 unlimited.surf，并自动带上配置好的 key，因此你仍然可以通过 Worker 使用原始接口。
---
## English
This is a Cloudflare Worker adapter for `https://unlimited.surf`. It exposes OpenAI-compatible `/v1/*` routes and Anthropic/Claude Code-compatible `/v1/messages` plus `/anthropic/*` aliases.
## Features
- OpenAI-compatible routes: `/v1/chat/completions`, `/v1/responses`, `/v1/models`, `/v1/files`.
- Anthropic-compatible routes: `/v1/messages`, `/v1/models`, `/anthropic/v1/messages`, `/anthropic/v1/models`.
- Raw upstream proxy: `/api/*` forwards directly to unlimited.surf.
- Web Search maps to upstream `POST /api/search`.
- Merge AI maps to upstream `POST /api/merge`.
- Files extraction maps to upstream `POST /api/attachments/extract`.
- Agent Setup, Codex, and MCP info endpoints are available at `/v1/setup`, `/v1/codex`, and `/v1/mcp`.
MCP servers still run inside your local agent, IDE, Claude Code, or Codex environment. This Worker only provides the model API endpoint and does not read or modify local files from Cloudflare.
## Deploy from GitHub with Cloudflare
Push this project to a GitHub repository, then let Cloudflare deploy it automatically on each commit.
### 1. Push to GitHub
Create a GitHub repository and push this project. Do not commit your unlimited.surf API key.
### 2. Connect the repository in Cloudflare
1. Open the Cloudflare Dashboard.
2. Go to `Workers & Pages`.
3. Click `Create`.
4. Choose `Import a repository` or `Connect to Git`.
5. Authorize Cloudflare to access GitHub if prompted.
6. Select the repository containing this project.
7. Set Root directory to `/` unless the project is in a subdirectory.
### 3. Build and deploy settings
Use these values:
```text
Framework preset: None
Build command: npm install
Deploy command: npx wrangler deploy
Root directory: /
Wrangler config: wrangler.toml
```
If Cloudflare shows only one command field, use:
```bash
npm install && npx wrangler deploy
```
### 4. Add the Cloudflare Secret
Add this secret in the Worker settings:
```text
UNLIMITED_SURF_API_KEY=<your unlimited.surf key>
```
The usual location is:
```text
Workers & Pages -> your Worker -> Settings -> Variables -> Secrets
```
Keep the key in Secrets only. Do not put it in `wrangler.toml`, `README.md`, or GitHub files.
### 5. Verify the deployment
Open:
```text
https://<your-worker>.workers.dev/health
```
You should see JSON with `"ok": true`.
Test OpenAI-compatible models:
```bash
curl https://<your-worker>.workers.dev/v1/models
```
Test Anthropic/agent setup docs:
```bash
curl https://<your-worker>.workers.dev/v1/setup
```
## Manual deploy with Wrangler
You can also deploy from your local machine:
```powershell
npm install -g wrangler
wrangler login
wrangler secret put UNLIMITED_SURF_API_KEY
wrangler deploy
```
Enter your unlimited.surf key when `wrangler secret put` prompts for it. You can also skip the secret and pass a key per request with `Authorization: Bearer <key>` or `x-api-key: <key>`.
## OpenAI-compatible routes ## OpenAI-compatible routes
@@ -118,7 +306,7 @@ curl https://<your-worker>.workers.dev/v1/chat/completions \
-d '{"model":"gateway-gpt-5","messages":[{"role":"user","content":"Hello"}],"stream":true}' -d '{"model":"gateway-gpt-5","messages":[{"role":"user","content":"Hello"}],"stream":true}'
``` ```
## Anthropic-compatible routes ## Anthropic / Claude Code-compatible routes
Base URL: Base URL:
@@ -150,10 +338,10 @@ claude
- Web Search maps to upstream `POST /api/search` when you call `/v1/search`, pass `web_search_options`, pass `query`, or include a web search tool. - Web Search maps to upstream `POST /api/search` when you call `/v1/search`, pass `web_search_options`, pass `query`, or include a web search tool.
- Merge AI maps to upstream `POST /api/merge` when you call `/v1/merge`, pass `merge: true`, or pass `models` with 2+ model IDs. - Merge AI maps to upstream `POST /api/merge` when you call `/v1/merge`, pass `merge: true`, or pass `models` with 2+ model IDs.
- Models maps to upstream `GET /api/models` with a fallback catalog if the upstream call fails. - Models maps to upstream `GET /api/models` with a fallback catalog if the upstream call fails.
- Files maps upload/extract requests to upstream `POST /api/attachments/extract`; persistent file storage is not implemented unless you add KV/R2. - Files maps upload/extract requests to upstream `POST /api/attachments/extract`; persistent file storage requires adding KV or R2.
- Codex, Agent Setup, and MCP are exposed as setup/info endpoints. MCP servers still run in the client or IDE; this Worker only provides the model endpoint. - Codex, Agent Setup, and MCP are setup/info endpoints. MCP tool execution remains local to the client agent or IDE.
- Embeddings, audio, and images return `501` because unlimited.surf does not expose those APIs in the provided docs. - Embeddings, audio, and images return `501` because the provided unlimited.surf docs do not expose those native APIs.
## Upstream raw proxy ## Raw upstream proxy
Any `/api/*` request is forwarded to unlimited.surf with the configured key, so the original API remains available through the Worker. Any `/api/*` request is forwarded to unlimited.surf with the configured key, so the original API remains available through the Worker.