AutoTeam API接口参考:RESTful接口与后台任务调用完全指南
AutoTeam API接口参考:RESTful接口与后台任务调用完全指南
AutoTeam 是一个开源的 ChatGPT Team 账号自动轮转管理工具,内置 Codex 额度监控、自动换号、邮箱注册与 CPA/Sub2API 认证同步能力。它自带的 RESTful HTTP API(默认端口 8787)把全部 CLI 功能都暴露为可调用的接口。这篇 AutoTeam API 接口参考指南将带你快速掌握即时返回接口与后台任务调用的完整用法,10 分钟即可完成集成。
🚀 API 服务器快速启动:一条命令跑起来
AutoTeam 基于 FastAPI 构建,API 服务由 manager.py 中的 api 子命令启动,默认监听 0.0.0.0:8787:
# 本地运行(Python 虚拟环境)
uv run autoteam api --host 0.0.0.0 --port 8787
# Docker 部署
docker run -d -p 8787:8787 -v $(pwd)/data:/app/data autoteam
服务启动后,浏览器打开 http://localhost:8787/docs 即可获得 Swagger 交互式文档,所有接口的请求体和响应结构都能在线调试。🎉
💡 首次启动会强制要求配置
API_KEY,可通过 Web 配置向导或.env文件完成,详见 docs/getting-started.md 与 docs/configuration.md。
🔐 API Key 鉴权方式:Bearer Token 怎么配
所有 /api/* 端点都需要携带 API Key(鉴权逻辑见 api.py),支持两种方式:
# 方式一:请求头(推荐)
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:8787/api/status
# 方式二:查询参数
curl "http://localhost:8787/api/status?key=YOUR_KEY"
三个接口无需鉴权,方便首次初始化:
| 接口 | 说明 |
|---|---|
GET /api/auth/check |
验证 API Key 是否有效 |
GET /api/setup/status |
检查配置是否完整 |
POST /api/setup/save |
保存初始配置 |
未配置 API_KEY 时接口处于开放状态,建议生产环境务必设置。
📋 即时返回接口速查表:状态、账号与配置
这类接口直接返回结果,不创建后台任务,适合轮询和看板展示。完整清单见 docs/api.md。
状态与账号查询
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/status |
全部账号状态 + active 账号实时额度(含 summary 统计) |
| GET | /api/accounts |
所有本地账号列表 |
| GET | /api/accounts/active |
当前活跃账号 |
| GET | /api/accounts/standby |
待命账号 |
| GET | /api/accounts/{email}/codex-auth |
导出 Codex CLI 格式认证(~/.codex/auth.json) |
GET /api/status 返回结构示例(实现见 api.py):
{
"accounts": [ { "email": "a@x.com", "status": "active", "last_quota": {} } ],
"summary": { "active": 2, "standby": 3, "exhausted": 0, "total": 5 },
"quota_cache": { "a@x.com": { "remaining_percent": 68 } }
}
账号操作
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/accounts/{email}/enable / disable |
启用 / 禁用单个账号(禁用的账号会被轮转、巡检、同步跳过) |
| POST | /api/accounts/bulk/enable / disable |
批量启用 / 禁用,请求体 {"emails": ["a@x.com"]} |
| POST | /api/accounts/{email}/kick |
将 active 账号移出 Team |
| DELETE | /api/accounts/{email} |
删除本地管理账号及其远端资源 |
Team 成员、同步与日志
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/team/members |
Team 全部成员(含外部成员与邀请) |
| POST | /api/team/members/remove |
移出成员 / 取消邀请,type 取 member 或 invite |
| POST | /api/sync |
同步 active 认证文件到已启用远端(CPA / Sub2API) |
| POST | /api/sync/from-cpa |
从 CPA 反向同步认证文件到本地(自动去重) |
| POST | /api/sync/accounts |
从 Team / auths 对账到本地账号池 |
| GET | /api/cpa/files |
CPA 认证文件列表 |
| GET | /api/logs?limit=100&since=0 |
最近运行日志 |
配置管理
| 方法 | 路径 | 说明 |
|---|---|---|
| GET / PUT | /api/config/runtime |
读取 / 保存邮箱、远端同步、代理等运行配置 |
| GET / PUT | /api/config/source |
读取 / 保存 .env 源文件原文(保存时自动校验必填项) |
| GET / PUT | /api/config/auto-check |
读取 / 修改巡检配置,运行时即时生效并持久化到 .env |
巡检配置包含 6 个字段(见 api.py):interval(间隔秒数,≥60)、target_seats、threshold(额度阈值 %)、min_low、retry_add_phone、add_phone_max_retries:
curl -X PUT -H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"interval": 300, "target_seats": 5, "threshold": 10, "min_low": 2}' \
http://localhost:8787/api/config/auto-check
⚙️ 后台任务调用指南:202 响应与任务轮询
耗时操作(浏览器注册、轮转、额度检查等)走后台任务机制:接口立即返回 202 Accepted + task_id,实际工作在独立线程中执行。
可用的任务端点
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/tasks/check |
检查所有 active 账号额度 |
| POST | /api/tasks/rotate |
智能轮转,请求体 {"target": 5}(目标 seat 数) |
| POST | /api/tasks/add |
自动注册并添加新账号 |
| POST | /api/tasks/fill |
补满成员 {"target": 5} |
| POST | /api/tasks/cleanup |
清理多余成员 {"max_seats": null} |
| POST | /api/tasks/reset-quota |
清空额度恢复记录,恢复 exhausted 账号 |
| POST | /api/accounts/login |
触发单个账号的 Codex 登录 |
| GET | /api/tasks |
任务列表(最多保留 50 条历史) |
| GET | /api/tasks/{task_id} |
任务详情 |
| POST | /api/tasks/{task_id}/cancel |
请求终止任务 |
任务对象的关键字段(见 api.py):
task_id / command / params / status / created_at
started_at / finished_at / result / error / cancel_requested
任务状态流转:pending → running → completed / failed / cancelled;调用 cancel 后进入 cancelling 中间态。
标准调用模式:触发 → 轮询 → 取结果
# 1. 触发轮转,拿到 task_id
curl -X POST -H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" -d '{"target": 5}' \
http://localhost:8787/api/tasks/rotate
# => {"task_id": "a1b2c3d4e5f6", "status": "pending", "command": "rotate", ...}
# 2. 轮询任务状态(建议间隔 2~5 秒)
curl -H "Authorization: Bearer YOUR_KEY" \
http://localhost:8787/api/tasks/a1b2c3d4e5f6
# => status 变为 completed 后,result 字段包含执行结果
# 3. 需要中止时
curl -X POST -H "Authorization: Bearer YOUR_KEY" \
http://localhost:8787/api/tasks/a1b2c3d4e5f6/cancel
⚠️ 409 Conflict:同一时间只允许一个浏览器任务
AutoTeam 使用全局 Playwright 锁,任务执行期间发起新的浏览器类请求会返回 409 Conflict,响应体附带正在执行的任务信息(见 api.py):
{
"detail": {
"message": "有任务正在执行,请等待完成后再试",
"running_task": { "task_id": "a1b2c3d4e5f6", "command": "rotate", "started_at": 1728000000 }
}
}
正确做法是:收到 409 后先轮询 running_task.task_id 直至结束,再重试。
🧑💼 管理员登录与 OAuth 导入接口
管理员登录(Team 操作的门票)
Team 成员查询、移出成员等接口依赖管理员登录态(见 docs/configuration.md「管理员登录态」),登录流程为一组分步接口(api.py):
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/admin/status |
管理员登录状态 |
| POST | /api/admin/login/start |
开始登录 {"email": "admin@example.com"} |
| POST | /api/admin/login/password |
提交密码 |
| POST | /api/admin/login/code |
提交邮箱验证码 |
| POST | /api/admin/login/session |
手动导入 session_token |
| POST | /api/admin/login/workspace |
选择组织 {"option_id": "0"} |
| POST | /api/admin/login/cancel / /api/admin/logout |
取消 / 清除登录态 |
主号 Codex 同步与手动 OAuth 导入
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/main-codex/start |
主号登录并同步到已启用远端 |
| POST | /api/main-codex/password / code |
提交密码 / 验证码 |
| POST | /api/main-codex/cancel |
取消同步 |
| POST | /api/manual-account/start |
生成 Codex OAuth 链接(返回 auth_url),优先尝试 localhost:1455 自动接收回调 |
| POST | /api/manual-account/callback |
自动回调不可用时,手动提交回调 URL |
| GET | /api/manual-account/status |
状态:idle / pending_callback / completed / error |
/api/manual-account/status 的关键字段:auth_url、callback_received、auto_callback_available、account(完成后导入的账号信息)。
🐛 常见错误码与排查
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 401 | 未授权,请提供有效的 API Key |
检查 Authorization 头或 ?key= 参数 |
| 400 | 缺少参数 / 主号不允许该操作 / 请先完成管理员登录 | 按 detail 提示补全参数或先登录主号 |
| 404 | 账号不存在 / 任务不存在 |
核对邮箱(统一转小写)与 task_id |
| 409 | 有任务正在执行 | 按上文「409 处理模式」轮询后重试 |
| 502 | Team 成员查询等上游调用失败 | 检查管理员登录态是否过期 |
配合 GET /api/logs?limit=200 查看运行日志,可快速定位任务失败原因。
📚 参考文档
- 接口总表:docs/api.md
- 配置项说明:docs/configuration.md
- Docker 部署:docs/docker.md
- API 实现源码:src/autoteam/api.py
- 任务机制核心:
_start_task、_run_task
掌握以上接口后,你可以用任意语言(Python、Node、Shell)编排出「定时巡检额度 → 自动轮转 → 同步到 CPA」的自动化流水线。建议优先从 GET /api/status 与 POST /api/tasks/rotate 这两个最高频接口入手,再按需扩展其他能力。