REST API

和 MCP 同一套能力的 HTTP 版本:JSON,Bearer 认证。本页讲通用约定;每个端点的参数、结构、错误与示例都在接口参考里。

接口参考

  • 可视化接口参考:浏览全部端点,填上自己的 Key 直接发测试请求(Key 只存在你的浏览器里)。
  • OpenAPI 3.1:可以导入 Postman、Insomnia,或者生成客户端代码(如 openapi-generator、Apple 的 swift-openapi-generator、openapi-typescript)。每个操作都有固定的 operationId,共用的结构都有名字,生成的方法名和类型名不会乱变。
  • Markdown 版:总览加端点目录,每个端点一页 Markdown。给 AI Agent 看这个,或者 llms.txt。

接口参考的说明文字是英文的。

站点管理、文档发布与取消发布、永久删除自己创建的跟踪目前只供登录后的应用和 Waper 的第一方 Agent 使用,不接受 API Key,也不通过 MCP 直接开放。参数与调用者范围以接口参考为准。

基础

Base URL: https://waper.ai/api/v1 OpenAPI: https://waper.ai/api/v1/openapi.json Auth: Authorization: Bearer <API Key>

在 Waper 的「设置 → API 与 MCP」创建 Key(见 API Key)。OpenAPI 文件本身不需要 Key。

有几类操作需要你本人来做,不接受 API Key:批准、撤销 Agent 的动作或把被拦下的改为批准并重试、看或改「始终允许」的规则与可信收件人、看最近自动放行与拦下的动作、读或改记忆、登记或改名电脑、断开设备、新建或改动例行任务(列表、执行记录这些读取不受限)、加 Agent、起草 Agent、改或删 Agent、给主 Agent 换收信地址(POST /mail-address/rotate)、建群、往群里加人或移人、断开连接的应用或开关它带来的配方(/apps)、看、加或删你自己的模型 API Key(/model-keys)与你加的 OpenAI 兼容服务(/model-services)、永久删除回收站里的东西(DELETE /trash/{id})、删除账号。用 Key 调用会返回 403 SESSION_REQUIRED,这样即使 Key 泄露,也没法给自己加权限。这些请在 Waper 的 App 里操作。

约定

  • 错误是 JSON:{ "error": { "code": "WATCH_NOT_FOUND", "message": "…" } }。按 code 判断(它是稳定的),message 给人看。输入不合法返回 400 INVALID_INPUT,issues 里每个字段一条 { path, message }。每个端点可能返回哪些错误,接口参考里都列了。例行任务没通过校验时返回 422 INVALID_ROUTINE,fields 里每处一条 { field, code }(field 是路径,如 triggers.0.rule)。
  • 分页:会增长的列表(关注的跟踪、资料库、文档、音视频、对话、任务、例行任务的执行记录、一个 Agent 做过的事)返回 { items, nextCursor },可以传 ?limit=;把 nextCursor 作为 ?cursor= 取下一页,为 null 表示没有了。每条执行记录带着做那次执行的 Agent(agentId,内置配方的是主 Agent;之后例行任务改归别的 Agent 也不变),列表可以加 ?agentId= 只看一个 Agent 的,翻页照常。小而固定的列表(知识库、搜索结果)只返回 { items }。
  • 命名:接口里的 space 就是界面上的知识库,按知识库筛选用 spaceId;跟踪的撰写语言叫 language;其他地方的 lang 是摘要、回答用的内容语言。
  • 幂等:创建类调用支持 Idempotency-Key 头。请求已经完成时,24 小时内用同一个 Key 重试会返回第一次的结果(带 idempotent-replayed: true),不会重复执行。上一次请求还在处理、或者结果不明(连接断了、服务端出了说不清的错)时,同一个 Key 在 5 分钟内会得到 409 IDEMPOTENCY_IN_PROGRESS:稍后用同一个 Key 再试,不要换一个新的 Key(那样可能做两遍)。超过 5 分钟可重试执行,但同一 Key 在保留期内不能换成不同请求(422 IDEMPOTENCY_MISMATCH;换一把 API 密钥发同样的请求也算不同请求)。请求被明确拒绝时会释放 Key,例如例行任务返回 422 INVALID_ROUTINE 后可以修改字段、沿用该 Key 再提交。创建跟踪在结果丢失后重试,会返回已有任务;如果跟踪已因失败或取消撤回,不会重新创建。用返回的 taskId 查询原任务的状态,需要重做失败的任务时使用任务重试入口。
  • 耗时的工作立即返回 202:新建跟踪给你 taskId(用 GET /tasks/{id} 看进度);转写音视频给你 mediaId(轮询 GET /media/{id});给 Agent 发消息给你对话 ID 和回复的消息 ID(轮询 GET /conversations/{id}/messages,直到 answering 为 false;更早的消息用 ?before=<最早一条的消息 ID> 往上翻,hasMore 为 false 表示到头了);上传的文件在后台读取,读完之前 GET /library/{id}/text 返回 400 TEXT_NOT_READY(轮询 GET /library/{id},等 status 变成 ready;NO_TEXT 表示没有可读的全文:只有上传的文件才存全文,或者文件里没有可读的文字,例如扫描件)。失败的任务如果 retryable 为 true,可以用 POST /tasks/{id}/retry 按同样的要求再开始一次。发消息时可以传 skill(GET /skills 里的标识),让 Agent 按这个技能来做。
  • 上传文件分三步,文件的字节直接发到存储,不经过 Waper 的服务器:
    1. POST /library/uploads,给出文件名、确切的字节数和整份文件的 SHA-256(小写十六进制),拿到 id、grant 和 put;
    2. 把文件本身作为请求体 PUT 到 put.url,原样带上 put.headers 里的请求头(不要带 Authorization)。大小、类型或内容和申请时的不一致,存储会直接拒绝;
    3. POST /library/uploads/{id}/complete,带上 grant(可以同时给 spaceId、note),文件就进了资料库,返回和收藏网页一样的 clipId。 同一份内容已经传过时 put 是 null:跳过第 2 步直接确认。地址 15 分钟内要开始上传,grant 1 小时内有效。
  • 语言:内容只有一种语言。会生成内容的调用可以传 lang(zh 或 en),不传时用账号设置里的内容语言。跟踪带 language(撰写语言),GET /watches/{slug} 与跟踪列表里的每一项另有 contentLanguage(这次返回的内容实际用的语言:别人的外语跟踪已有你的内容语言的译文时给译文,列表里简介与最新一期导语都有译文才换)。
  • 暂停的跟踪:GET /watches/{slug} 的 pause 写明简报为什么停着(主人暂停、积分不够、方案不再包含它)。主人用 PUT /watches/{slug}/paused 暂停或恢复自己建的跟踪(能不能看 canPause)。有没有人看不会让跟踪暂停。
  • 时间:date-time 字段是 ISO 8601 字符串;写明是 Unix 时间的字段是毫秒数。
  • 清空一个值:请求里不用 null,用空字符串或明确的取值(例如知识库图标传 "" 恢复默认、条目反馈传 "none" 取消);不想改的字段不传。
  • 兼容:响应里随时可能出现新字段,不认识的字段忽略即可。

Agent、对话与后台的事

一开始你有一个主 Agent,还可以再加最多 10 个(GET /agents:每个带着 kind、preset、name 和它的单聊 conversationId;kind 是 main、template 或 custom)。每个 Agent 都能把要花时间的事放到后台去做,一件就是一个 Work,对话里是一张进度卡;你点名另一个 Agent、或者事情明确归它管时,也能请那个 Agent 做:你正在说话的 Agent 把一段转述交给另一个,两个 Agent 之间的往来每一对一条线程。

  • 用 API Key 时,你在一个属于这次调用的对话里和主 Agent 说话(POST /conversations/messages):它可以把事放到后台自己做,但不会去找别的 Agent。这句话引出的事都有了结论、它在对话里说完,才算答完:在那之前 answering 一直是 true,再发一句返回 409 CONVERSATION_BUSY;返回的结构不变。事停在等你批准、或缺你的东西时,它说明在等什么,这次就算答完;你处理之后它接着做,结论在这个对话里另起一条。你和各个 Agent 的对话、里面的事,用 Key 都读不到。
  • 登录的账号(各端 App):PATCH /conversations/{id} 置顶、隐藏或把一个对话标为未读(pinned、hidden、unread: true;主 Agent 的对话不能取消置顶、不能隐藏,409 MAIN_CHAT_FIXED);GET /agents/{id}/ongoing 是 Agent 详情里「需要你处理」「在做」「例行任务」几段的数据:waiting(等你回答、批准或缺你东西的事)、working(进行中、排队或在等别的事的)、routines(它的例行任务与它跑的应用配方,不含提议的;上一次执行在等你的排前面)、proposed(它提议的例行任务)、done(最近结束的几件事,更早的用下一个端点翻),跟踪不在这里;GET /agents/{id}/works 列出一个 Agent 做过的每件事(它给自己开的,和别的 Agent 请它做的),最新的在前;GET /works/{id} 返回一件事的全部(goal 要的是什么、result 交回了什么、unfinished 没做完的、steps 每一步、changes 做出了什么、messageId 是从哪条回答里开的),不存在时 404 WORK_NOT_FOUND;POST /works/{id}/stop 停下一件(应用里没有这个按钮,用户停一件是跟 Agent 说;等它结果的事一起停,这个对话里别的照常;已经结束的原样返回;停掉的之后在对话里说一声就能接着做);GET /peer-threads/{id} 只读两个 Agent 之间的线程(?fromSeq= 从回答里 peer 卡的 seq 读起,那张卡就是「已发消息给……」「消息来自……」「帮……做了」那一行;nextCursor 往前翻,nextFromSeq 往后读)。线程里的一条可以作为 peer_message 引用带回对话。这六个用 API Key 调用一律 404。Work 里 agentId 是做事的 Agent,frontAgentId 是开它的那个对话的 Agent,两者相同就是它给自己开的(这时 threadId 为 null);status 是 submitted、working、带 waitingOn 的 input-required、completed、failed 或 canceled;进行中时 line 是最新一步的那句大白话;outcome 为 dropped 表示它发现这件不用做了(result 里写着为什么);attempt 每重新打开一次加一。
  • 回收站:删除文档、知识库与资料(DELETE /docs/{id}、DELETE /spaces/{id}、DELETE /library/{id})是移到回收站,留 30 天后自动永久删除。GET /trash?area=knowledge 列出删掉的文档与知识库(跟着知识库一起删的文档不单独列,知识库带 docCount),area=library 列出删掉的资料,每条带 deletedAt 与 purgeAt;POST /trash/{id}/restore 恢复(文档原来的知识库也在回收站里时放到默认知识库,返回的 spaceId 是它现在所在的知识库;unpublishedPages 是恢复的文档里有几篇发布过的页面没有重新公开:它们在回收站里时地址被同一站点的别的页面用了),回收站里没有返回 404 TRASH_ITEM_NOT_FOUND;DELETE /trash/{id} 立刻永久删除(只给登录的账号)。回收站里的东西在别的端点里一律当作不存在。
  • Agent 市场:GET /agent-templates 列出 Waper 做好的现成 Agent(每个带 id、name、样子 look、分类 category、卡片上的一句 pitch、blurb、duty、开场示例 examples 与配合使用的应用 apps)。这个端点不带 Key 也能调;带着 Key 时 added 与 agentId 告诉你哪些已经加过。文字按 lang,不传时用你的界面语言(不带 Key 时按 Accept-Language)。
  • 加、改、删 Agent(只给登录的账号):POST /agents 带 { "kind": "guided", "name"?, "avatar"? }(各端的「创建新 Agent」就是它:带了 name 就用这个名字,不带先用占位的名字、之后自己起名;settingUp: true,在自己的对话里问你要它管什么,再写下职责),或 { "kind": "template", "template": "<GET /agent-templates 里的 id>" },或 { "kind": "custom", "name", "blurb", "duty", "avatar"? },返回 201 与这个 Agent。avatar 是 { "shape", "face", "color" },三项都要给(取值见接口参考里的 AgentAvatar);不给时配一个你还没用过的样子;和主 Agent 的默认样子一模一样时 400 INVALID_AVATAR。到了上限 409 AGENT_LIMIT,同一个模板加过了 409 TEMPLATE_EXISTS(带已有的那个的 agentId),重名 409 NAME_TAKEN。POST /agents/draft 带 { "text" }(一句话,1 到 500 个字符)起草 { name, blurb, duty },不花积分,太频繁 429 RATE_LIMITED,模型暂时不可用 503 MODEL_UNAVAILABLE。PATCH /agents/{id} 改 name、blurb、duty、avatar 与 notify(它对你说的话推不推送;应用里的「免打扰」就是把它关掉);只改 duty、不带 blurb 时,blurb 随后按新的职责重写(写好后经 agent 帧推给各端);每个 Agent 都能改 name、avatar 与 notify,主 Agent 的 blurb 与 duty 改不了(409 AGENT_FIXED);你加的 Agent 换成主 Agent 的默认样子时 400 INVALID_AVATAR。DELETE /agents/{id} 返回 204,它的对话与例行任务一起删掉;主 Agent 409 AGENT_PERMANENT。
  • 群(只给登录的账号):POST /conversations/messages 不带 conversationId、带 newGroup: { "agentIds": [...] }(1 到 6 个,按你选的先后)开一个群并说第一句,返回的 conversationId 就是这个群;用 API Key 带 newGroup 返回 400 INVALID_GROUP。群里 toAll: true 是 @所有人;@ 某个成员是在 refs 里放 { "kind": "agent", "id": "<Agent ID>" }。群的 Conversation 里有 memberAgentIds(按加入的先后)、agentId: null、title(空串时各端显示成员的名字)和 spaceId;单聊的 agentId 是它的 Agent,主 Agent 的单聊 main: true。群里没点名的一句用户的话带着 dispatch: { agentIds }:选出来回答的成员,按回答的先后(空表示谁都不答;还没定时为 null)。PATCH /conversations/{id} 对群还收 title、spaceId(空串是不关联知识库):用在不是群的对话上 409 NOT_A_GROUP。POST /conversations/{id}/members 带 { "agentId" } 加人(满了 409 GROUP_FULL),DELETE /conversations/{id}/members/{agentId} 移人(不是成员 409 NOT_A_MEMBER),两者都返回这个群。POST /conversations 带 { "agentIds": [...], "title"?, "spaceId"? } 建一个还没有消息的群(201 与这个群)。DELETE /conversations/{id} 删群,返回 204;和一个 Agent 的对话删不了(409 CONVERSATION_PERMANENT)。
  • 例行任务归一个 Agent:POST /routines 和 PATCH /routines/{id} 可以带 agentId(不带就是主 Agent)、deliverTo(这个 Agent 在的一个群的对话 ID,空串是它自己的对话)与 doneWhen(做到什么算完:某次执行判断满足了,例行任务就此停下,pausedReason 是 finished;空串是没有自己的终点)。state 为 proposed 的是 Agent 提议的,什么都不执行,直到你 POST /routines/{id}/start(只给登录的账号;开始就是你批准了它,已经开着的原样返回,暂停的 409 NOT_PROPOSED,要用 resume);不要就 DELETE。对提议的暂停、恢复或试运行返回 409 ROUTINE_PROPOSED。
  • 跟踪发到哪:PATCH /watches/{slug}/settings 的 deliverTo 是主 Agent 在的一个群的对话 ID,空串是主 Agent 的对话;每个关注者各设各的。主 Agent 不在那个对话里时返回 404 CONVERSATION_NOT_FOUND。
  • 改自己建的跟踪:PATCH /watches/{slug} 改 scope(一句话说范围怎么改)、title(slug 不变)、visibility 与 urls(add / remove,只给指定信源与网页变化型)。改范围或地址返回 taskId:后台重写范围、领域型重新找信源,马上写一期,进度看 GET /tasks/{taskId};按报价预留积分,做完按实际扣。只有主人能改(403 NOT_OWNER,官方跟踪不能改);转私有需要付费方案(403 PRIVATE_NOT_ALLOWED),会去掉别人的关注与邮件订阅;上一次改动还没做完 409 WATCH_UPDATING;改范围或地址算一次带报价的动作,同一把 Key 每分钟超过上限时 429 RATE_LIMITED;什么都没变 400 NOTHING_TO_CHANGE。
  • 审批(只给登录的账号):POST /actions/{id}/decide 带 approve,再带 alwaysAllow: true 就是「始终允许」(按动作的 alwaysAllowScope 记一条规则;发送卡上则是把收件人加进可信收件人;付款与读过外部内容之后发给没提过的人的动作没有它,这一项被忽略),批准发送卡时可以带 edits(键是动作 editable 里那一处的 key,值是改后的全文;收件人和发件账号改不了,键不对 400 ACTION_EDIT_INVALID),POST /actions/decide 一起决定合成一张卡的那几件(edits 按动作 ID 给);GET /rules、POST /rules(带一个动作的 actionId,按它的 alwaysAllowScope 记)、DELETE /rules/{id} 看、加、删「始终允许」的规则;GET、POST、DELETE /trusted-recipients 管可信收件人(邮箱、@域名 或 #频道,最多 200 个,满了 409 TRUSTED_RECIPIENT_LIMIT;每条带 confirmed,为 false 的是改成「直接发」之前加的,第一次直接发之前还会问一次);GET /actions/reviewed?verdict=allow 与 ?verdict=block 是最近自动放行与最近拦下的动作(每个带着 review:结论与给你看的理由);POST /actions/{id}/retry 把一个被拦下的动作改为批准并执行一次,不记规则(拦下超过 7 天 409 ACTION_NOT_BLOCKED)。
  • 模型目录:GET /models 的 models 先列平台的 Lite、Pro、Max(kind: "tier",ID 为 lite、pro、max,maker 为 null,不公开背后的模型),再列可以直接选的具体模型(kind: "model",带 maker);名字与一句说明按界面语言,thinkingLevels、keyProviders 为空。每一项带 relativeCost(一轮大约花 Max 的几倍,Max 为 1)与 available(你现在能不能选,不能的选了返回 402)。platformDefault 是没选过时的方案默认档位(免费 Lite、会员 Pro);选着的现在用不了时原选择仍记着,这段时间按 downgradeTo 用。keyModels 单独列自己的 Key 能用的真实模型,带 thinkingLevels 与 keyProviders;customModels 是自己添加的服务上的模型。响应还带连着的 Key;keysAvailable 为 false 时这个服务用不了自己的 Key(/model-keys 回 404)。
  • 给一个 Agent 选模型:PATCH /agents/{id} 带 model、thinking、modelKeyProvider(只给登录的账号),改的是这个 Agent 的,它的单聊、群里的发言与后台的事都用;现在的选择在 Agent 的 model 里。选平台的时传档位 ID(lite、pro、max)或具体模型的 ID,不传 modelKeyProvider;平台的 thinking 统一保存和返回为 null,即使请求带了思考值也不会成为平台配置。选自己的模型时传目录里的 model ID、对应的 modelKeyProvider,可再传它支持的 thinking。你的方案用不了的返回 402 MODEL_NOT_IN_PLAN;经自己的 Key 时这个模型不能经这家用、这家没连 Key 或 Key 已失效分别是 409 MODEL_NOT_VIA_KEY、MODEL_KEY_MISSING、MODEL_KEY_INVALID。
  • 自己的 Key(只给登录的账号):GET /model-keys 只返回提供商、后 4 位与状态,从不返回 Key 本身;PUT /model-keys/{provider} 先向提供商验证,没过返回 422 MODEL_KEY_REJECTED(reason 是 invalid、no_credit 或 unreachable),验证每小时最多 10 次;DELETE /model-keys/{provider} 立刻删掉;用它的 Agent 回到方案默认的 Waper 档位,清除旧思考选择。一轮因为你的 Key 用不了而停下时,turn.error 与对话里那一行的代码是 MODEL_KEY_INVALID(Key 不对)、MODEL_KEY_QUOTA(额度用完或限流)、MODEL_KEY_REFUSED(提供商拒绝了这一次请求,比如判定输入违规,Key 照旧可用)或 MODEL_KEY_UNREACHABLE(连不上),带着是哪一家 provider。GET /usage/history 是按天分组的积分记录(翻页用 cursor),经你的 Key 的行带 ownKey。
  • 你加的 OpenAI 兼容服务(只给登录的账号):GET /model-services 列出服务与上面的模型(Key 只给后 4 位);POST /model-services 加一个、PUT /model-services/{id} 整份替换(不带 key 沿用现在的,空字符串去掉),都先验证,没过返回 422 MODEL_KEY_REJECTED(reason 多两种:model_missing 是服务上没有这个模型,unsupported 是服务拒绝了带工具的请求、这个模型可能不支持工具调用,都带着是哪个 model),地址不合格 400 MODEL_SERVICE_URL_INVALID,满 10 个 409 MODEL_SERVICES_LIMIT;DELETE /model-services/{id} 立刻删掉;删服务或编辑时去掉某个模型,会让用它的 Agent 回到方案默认的 Waper 档位,清除旧思考选择。GET /models 的 customModels 列出这些服务上的模型(status 为 invalid 的是服务拒绝了 Key,现在选不了),选它用 model 填它的 id、modelKeyProvider 填 custom;这一轮停下时 turn.error 里不带 provider。规则见模型与你自己的 Key。

Agent 的回答消息里,每次模型调用想的是一张 thinking 卡(text 是全文,模型没给出可显示的内容时为空字符串、只有 durationMs;durationMs 是想了多久,量不到时为 null),排在那次调用说的话与做的步骤之前;只要最终回复的客户端可以跳过它。每一步是一张 tool 卡:label 是按工具与参数拼的一句进度,activity 是 Agent 自己写的那一句(正在做什么、为什么,用你的语言;没写时没有这个字段),有 activity 时显示它。实时通道里想的内容先以 thinking 帧流出来(和 delta 共用 cursor 与 step,带 reset 的 delta 同时作废这一步已收到的思考)。

各端 App 经实时通道跟着对话走。和后台的事有关的帧:work(开了一件事或它变了,带着整个 Work)、带 workId 的 turn.start(在做一件事的一轮:不留回答,结束时是 turn.closed,同样带 workId;重连时的 ready 快照里也是)、agent(一个 Agent 建出来了,或者改了名字、职责、一句话、形象、免打扰,或者结束了引导)。回答里的进度卡是一张 work 卡({ type: "work", work })。回复某张进度卡时,turn.send 带上它的 workId(REST 的 POST /conversations/messages 同样收 workId):还没结束的事直接收到这句话,已经结束的交给 Agent 并带上是哪件。App 发出的 turn.cancel 停下正在回答的一轮,连同这个对话里还没结束的事;独立的后台工作(/tasks)与例行任务不受影响。

忙时发送的消息会先排在当前轮之后:POST /conversations/messages 仍返回 202,turnStarted.messageId 为 null,并带 queueId。这条输入会出现在 GET /conversations/{id}/messages 的 queued 中,直到下一轮消费;消费后才生成真实消息的 seq。实时通道用 conversation.queue(全量)和 conversation.queue.item(added、removed、consumed)同步队列。撤回用客户端实时帧 conversation.queue.retract,成功会收到 removed;如果已经消费,则收到 consumed,客户端应提示消息已发出。队列项的 parts、context、replyTo 与 skill 在支持的版本中用于撤回后恢复完整输入,旧客户端只需读取 id、text、createdAt。

和加 Agent、群有关的帧:turn.send 可以带 newGroup 与 toAll(新群的 ID 从 turn.ack 的 conversationId 拿);agent.deleted(一个 Agent 被删了,各端从花名册与 @ 菜单里去掉它);conversation(成员、群名或关联的知识库变了);dispatch(没点名的一句话选出了谁来答);peer(两个 Agent 之间的线程里多了一条);App 发出的 conversation.delete 也能删群;conversation.deleted(群被删了,或者你加的 Agent 被删了时它的对话)。

和通知有关的帧(都是 App 发出的):presence(这个客户端在不在前台:变了就发,在前台时定时再发;账号的任何一个客户端在前台时,浏览器、手机和桌面端都不弹通知,只更新数字);conversation.seen(看到了一个对话里的哪一条:看到了的消息不再往设备上推;打开对话不算看到)。不认识的帧忽略即可。

图片生成与编辑

生图与改图可选 aspectRatio(1:1、3:2、2:3、16:9、9:16)与 quality(standard、high)。生成默认方图;改图默认取最接近原图的受支持比例。质量默认 standard,明确需要高质量时用 high;质量是偏好,回退服务可能用默认质量,每张价格不变。清晰度由服务默认决定。

示例

# 我关注的跟踪
curl -H "Authorization: Bearer wpr_xxx" \
  https://waper.ai/api/v1/watches

# 把网页收进资料库
curl -X POST https://waper.ai/api/v1/library \
  -H "Authorization: Bearer wpr_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

# 问自己的 Agent;这一轮结束后从对话里读回复
curl -X POST https://waper.ai/api/v1/conversations/messages \
  -H "Authorization: Bearer wpr_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"这周我的 AI 跟踪有什么变化?"}'

限流与计费

  • 每个账号每分钟 60 次(与 MCP 共用),超出返回 429 RATE_LIMITED,Retry-After 头给出要等的秒数。
  • 用 API Key 发起花积分的动作(转写新的音视频、深度研究):每把 Key 每分钟最多 10 个,超出同样返回 429 RATE_LIMITED 与 Retry-After,过了这一分钟再发即可。Waper 暂时查不了这把 Key 的用量时返回的也是这个 429(说明里写的是查不了,不是到了上限),稍后重试。没有每天的次数上限:有积分就能一直用。
  • 读取免费。给 Agent 发消息按实际模型用量与所选的模型计算积分,收藏网页与文件的摘要按实际用量结算;音视频按分钟计(先用 POST /media/quote 报价);生成与修改图片(POST /images/generations、POST /images/edits)按张计,出了图才扣,此刻的价用 GET /paid-capabilities 查,请求里给 maxCredits 时价格超过它就返回 402 PRICE_ABOVE_MAX、什么都不做,到了每天的张数上限返回 429 PAID_LIMIT。积分不够时返回 402 CREDITS_EXHAUSTED。发送消息会在开始新一轮前检查最低预留份额;被拒时响应顶层的 remaining 与 needed 给出剩余积分与最低所需积分(整数),不写入消息或安排轮次。自己的模型 Key、不扣积分的档位,以及排在正在进行的一轮后面的消息不受发送预检限制;排队消息在轮到时再检查。见方案与积分。