AutoTeam API接口参考:RESTful接口与后台任务调用完全指南

原创2026-10-14 07:34:131,879 阅读
文章标签:后端前端工作流自动化RPA

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 查看运行日志,可快速定位任务失败原因。

📚 参考文档

掌握以上接口后,你可以用任意语言(Python、Node、Shell)编排出「定时巡检额度 → 自动轮转 → 同步到 CPA」的自动化流水线。建议优先从 GET /api/status 与 POST /api/tasks/rotate 这两个最高频接口入手,再按需扩展其他能力。

登录后查看全文
AutoTeam