开发者文档

OpenAI 兼容的 /v1 API、认证、Webhook 与机器可读文件

01/ 07

概览

parrot.amorist.cn 同时是账号、支付与中继服务

AI WORKSHOP（鹦鹉AI）面向鹦鹉AI 桌面应用与第三方客户端提供 OpenAI 兼容的中继 API：文本对话、图像生成、异步视频与 3D 生成、 Embedding 与模型目录，按积分计费。Base URL 为https://parrot.amorist.cn/v1。

所有 /v1 请求都需要认证：携带 Authorization: Bearer <token> 请求头，令牌来自 POST /api/auth/login（手机号 + 密码）； 浏览器环境也可用 Web 会话或 dsh_token Cookie。未认证返回 401。

计费按积分：每次调用按模型与用量从余额扣除，明细在账户中心可见。 余额不足时接口返回 402；触发限流时返回 429。

02/ 07

端点

/v1 接口一览

  • GET/v1/models

    可用模型目录（含积分价格预览与来源）

  • POST/v1/chat/completions

    文本对话，OpenAI 兼容，支持 stream

  • POST/v1/images/generations

    图像生成

  • POST/v1/videos/generations

    创建视频任务（异步）

  • GET/v1/videos/generations/{taskId}

    查询视频任务状态

  • POST/v1/videos/generations/{taskId}/cancel

    取消视频任务

  • POST/v1/embeddings

    Embedding 向量化

  • POST/v1/3d/generations

    创建 3D 生成任务（异步）

  • GET/v1/3d/generations/{taskId}

    查询 3D 任务状态

  • POST/v1/3d/generations/{taskId}/cancel

    取消 3D 任务

  • POST/v1/audio/tts

    语音合成（Fish Audio / 豆包语音）

  • POST/v1/audio/generations

    音频生成：音效 / 音乐 / 多角色语音编排

  • POST/v1/audio/transcriptions

    字幕生成：提交识别任务（异步）

  • GET/v1/audio/transcriptions/{taskId}

    查询字幕任务状态与分段

  • GET/v1/audio/voices

    音色目录：预置 + 自己的复刻音色

  • POST/v1/audio/clones

    声音复刻：上传参考音频训练音色

  • GET/v1/audio/clones/{voiceId}

    查询复刻音色状态

  • DELETE/v1/audio/clones/{voiceId}

    删除复刻音色

视频与 3D 生成为异步任务：创建后轮询 GET .../{taskId} 直到完成，必要时可取消。

03/ 07

认证与账号

手机号注册、登录与刷新

  • POST /api/auth/register手机号 + 密码

    注册后即可登录使用；可选邀请码。

  • POST /api/auth/login返回 Bearer JWT

    桌面端与第三方客户端用它换取 /v1 访问令牌。

  • POST /api/auth/refresh续期

    令牌过期后刷新，无需重新登录。

04/ 07

Webhook

支付宝异步通知

支付结果通过服务端到服务端的异步通知送达：POST https://parrot.amorist.cn/api/payment/alipay/notify。通知带支付宝签名，服务端验签后才会更新订单与到账积分；请勿信任任何 未经签名校验的支付回调。

05/ 07

限流与版本

RateLimit 头与弃用策略

每个 /v1 响应都带 RFC 9218 限流头：RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset（默认按用户 600 次/分、按 IP 240 次/分，可由部署环境变量调整）。 触发限流时返回 429，并带 Retry-After 秒数。

主版本在 URL 路径（当前 /v1）。发布新主版本时，旧版本继续服务至少 12 个月；被弃用的端点会带 Deprecation 响应头，并在 停用前至少 30 天通过 Sunset 头与本页公告。集成方应 监听这两个头，而不是在收到 404/410 时才被动迁移。

06/ 07

机器可读文件

给程序与 AI 代理的入口

OpenAPI 3.1 规范
/v1 接口的机器可读定义，可直接导入客户端生成工具
数据服务 OpenAPI 3.1
/api/data/* 的机器可读定义（请求体形状由代码真源生成，与路由不会漂移）
llms.txt
站点 AI 可读索引与「何时使用」指南
sitemap.xml
全部可索引 URL（含周刊期次）
robots.txt
爬虫协议，显式允许主流 AI 爬虫

限流：中继默认按用户 600 次/分、按 IP 240 次/分，可由部署环境变量调整。 更多问题见 联系。

07/ 07

数据服务

接入凭证、REST 与 MCP

数据能力（社交内容、点评口碑、电商商品、全网搜索、验证码识别、邮件、接码、 IP 代理、AI 接口）与 /v1 中继是两条线：那边是模型，这边是数据。 两条线各有各的额度，但数据服务只需要一把接入凭证，REST 与 MCP 共用它。

凭证在控制台「接入与凭证 → API Keys」签发（形如 parrot_…）， 可以限制成只能调某几族能力，也可以给这一把 Key 单独设额度（每天 / 每月 / 累计的积分与次数上限，用完这把 Key 的调用被拒，别的 Key 不受影响）， 还可以随时轮换或撤销。 所有请求都带同一个头：Authorization: Bearer parrot_…

  • GET/api/data/capabilities

    可用数据能力目录（含参数表、定价与可用状态）

  • POST/api/data/call

    调用一条数据能力，返回归一化结果信封

  • GET/api/data/jobs/{jobId}

    查询异步任务进度与结果

  • POST/api/data/jobs/{jobId}/cancel

    取消异步任务

  • GET/api/data/calls/{requestId}

    按 requestId 回看一次调用的审计与结算

  • GET/api/data/usage

    本账号的数据调用用量（今日 / 近 30 天 / 按能力）

  • GET/api/data/scenes

    场景包（一次调用跑多条能力的编排定义）

MCP 走标准协议（Streamable HTTP）：端点 POST https://parrot.amorist.cn/mcp， 握手、工具清单与调用都是标准 MCP，控制台那一页按客户端（Claude Code / Cursor / ChatGPT / 通用）给出可以直接粘的配置。 当前暴露 6 个工具：列能力、看能力参数表、调能力、查异步任务、等异步任务跑完、查用量。

响应走 SSE 流（text/event-stream）， 因此服务端可以主动推送进度： 请求里带上 _meta.progressToken 就能收到notifications/progress； 异步能力用 data_wait_job 让服务端在这一趟里等它跑完（进度由服务端推、 结果行随最终响应一起回），客户端不必自己一轮一轮地轮询。 轮询与等待都不计费。只接受单个 JSON 响应的客户端请把Accept 写成application/json, text/event-stream。

带 Key 调 GET /api/data/usage 或 MCP 的 data_get_usage会顺带回这把 Key 的额度读数（上限与本窗口已用），程序可以自己算"还能调几次"。

{
  "mcpServers": {
    "parrot-data": {
      "type": "http",
      "url": "https://parrot.amorist.cn/mcp",
      "headers": {
        "Authorization": "Bearer parrot_…"
      }
    }
  }
}
开发者文档 · AI WORKSHOP