AI 生成 API

Agent OpenAPI

Agent OpenAPI 让接入方能够启动或继续 Meoo Agent、订阅实时事件、处理交互 Action，并读取公开会话历史。基础地址：https://meoo.com/open/v1

文档导航

目标	文档
从项目到完成一次 Agent Run	Agent 接入总览
启动、查询和取消 Run	Run 生命周期
消费 SSE、回复问答或确认	事件流与 Action
使用文件、图片和自定义 Skill	附件与 Skills
继续会话、读取消息和断线恢复	会话与恢复
上传私有 Skill ZIP	Skills API

权限

Scope	能力
`agent.run`	查询模型与性能档位、启动或取消 Run、签发附件上传票据、回复 Action
`agent.read`	查询当前 Run、订阅默认包含 Write/Edit 正文的 SSE、读取会话和公开消息
`skill.write`	上传或更新私有 Skill；运行已上传 Skill 不需要该 Scope

OAuth Access Token 和用户 API Key 使用相同的业务接口，统一放在 Bearer Header 中：

Authorization: Bearer <access_token_or_meoo_ak>

核心对象

对象	说明
Project	Agent 操作所在的项目；路径中的 `project_id` 使用项目 `url_id`
Conversation	用户与 Agent 的持续会话；后续 Run 可传 `conversation_id` 继续
Run	Agent 对一条用户消息的处理任务；由 `run_id` 标识
Event Stream	指定 Run 的 SSE 实时事件流
Action	Agent 暂停并等待用户问答或确认时返回的短期交互凭据

所有标识都应按不透明字符串保存和原样传递，不要解析其格式。

接口一览

方法	路径	Scope	用途
`GET`	`/projects/{project_id}/agent/capabilities`	`agent.run`	查询当前可选模型、性能档位和默认值
`POST`	`/projects/{project_id}/agent/runs`	`agent.run`	启动新会话或继续已有会话
`GET`	`/projects/{project_id}/agent/runs/current`	`agent.read`	查询项目当前或最近一次 Run
`GET`	`/projects/{project_id}/agent/runs/{run_id}/events`	`agent.read`	订阅指定 Run 的 SSE
`POST`	`/projects/{project_id}/agent/runs/{run_id}/cancellations`	`agent.run`	取消 Run
`POST`	`/projects/{project_id}/agent/action-responses`	`agent.run`	回复当前可交互 Action
`POST`	`/projects/{project_id}/agent/uploads`	`agent.run`	签发附件直传票据
`POST`	`/projects/{project_id}/agent/preview-links`	`agent.read`	获取或重新签发短时预览壳 URL
`GET`	`/projects/{project_id}/agent/conversations`	`agent.read`	分页查询会话
`GET`	`/projects/{project_id}/agent/conversations/{conversation_id}/messages`	`agent.read`	分页查询公开消息

最小调用流程

启动前调用 GET /projects/{project_id}/agent/capabilities（agent.run）获取实时模型目录、性能档位及默认值。model 必须精确使用 models[].id，内部别名和下线 ID 会返回 400 invalid_request；模型目录不可用返回 503 service_unavailable。以下模型 ID 仅作示例，实际以接口返回为准。 speed_tier 支持 fast（低延迟优先）、standard（均衡默认）、deep（更多推理能力，可能增加延迟和消耗）。内部 mode 仍不支持通过 OpenAPI 选择。启动 Run：

curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: message_20260818_001" \
  --data '{"message":"创建一个活动报名网站","model":"qwen3.7-plus","speed_tier":"deep"}'

需要 Agent 按服务端预置自动决策处理可自动确认的步骤时，在请求中传 yolo: true：

{
  "message": "创建一个活动报名网站",
  "yolo": true
}

yolo 为 true 时会开启本次 Run 的 YOLO，状态会写入现有 Agent 状态快照，并供同项目后续 Run 继承。false 或不传不会主动开启，也不能清除已经持久化的 true。YOLO 仅应用预置自动决策；需要真人完成的 OAuth、Secret 或 Input 场景仍可能按现有策略取消或关闭。该字段不会改变 HTTP 响应或 SSE 事件 Schema。

单次运行禁用 Meoo Cloud

启动时可传 disable_cloud: true，默认 false，仅本次 Run 生效。它禁用全部 meoo-cli cloud 能力（包括帮助、读取、开启、绑定、数据库、鉴权、存储和云函数），已有云服务也适用；不会产生云能力确认卡，YOLO 不能绕过。

{
  "message": "构建一个不依赖 Meoo Cloud 的前端 demo",
  "disable_cloud": true
}

同一 Run 的工具恢复、进程恢复、上下文压缩及子 Agent 保留禁云策略；下一次 Run（包括同会话继续）不传则恢复 false。此参数不关闭或删除已有云资源，不限制外部 API；缺少可用后端时使用 mock 数据和模拟交互，并在交付时说明模拟部分。响应会包含后续需要保存的三个标识：

{
  "project_id": "event-signup-demo",
  "run_id": "run_01JEXAMPLE",
  "conversation_id": "conv_01JEXAMPLE",
  "status": "submitted",
  "model": "qwen3.7-plus",
  "speed_tier": "deep"
}

启动响应的 model、speed_tier 是已校验并交给 Runtime 的本次选择；runs/current 返回最后持久化值，刚启动时不构成与 start 相同的原子确认。两字段每次启动独立选择：省略使用 capabilities 当前默认值，继续会话也不继承上次选择；需要保持配置时再次显式传入。解析后的选择参与幂等摘要，重试应保持相同配置。disable_cloud 的 true 也参与摘要，false 与省略等价。订阅事件：

curl --no-buffer \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs/${RUN_ID}/events" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Accept: text/event-stream"

SSE 只需 agent.read，默认包含 tool.input.delta、tool.input.snapshot。Write 公开 content；Edit 公开 old_string、new_string 及最终 replace_all。delta 按 tool_call_id 和字段追加，snapshot 整体替换该工具公开输入。complete: true 仅代表参数生成完成；truncated: true 表示公开内容受限，内部仍按完整参数执行。 Read 的 tool.call 可带安全 basename file_name；Skill 可带 skill.skill_name 和可选 display_name。tool.call.status: completed 仅表示调用结束，实际结果看 outcome（succeeded、failed、canceled）。不公开目录路径、Read 正文、Skill 原始参数或原始工具结果。 Bash 的 tool.call 可携带 sub_type：shell、image_generate、video_generate、speech_generate 或 music_generate。tool_name 仍为 Bash。参数生成完成后首次发送 started，完成事件保留同一分类；缺省或未知分类按通用进度处理。素材生成成功且有可公开产物时，完成事件可带 result：图片为 {type: "image", images: [HTTPS URL]}，视频为 {type: "video", video: HTTPS URL}，语音或音乐为 {type: "audio", audio: HTTPS URL}。失败、取消或无可公开产物时可能省略，不公开提示词和原始命令输出。持久化 message.snapshot 的可选 tool_calls 恢复当前轮 Read/Write/Edit/Skill 及图片、视频、语音、音乐素材 Bash 状态，素材调用包含可选的 sub_type 与 result；普通 Shell 命令不进入工具快照。字段存在时整体替换工具列表和素材结果卡，缺省时保留已有工具列表；content 继续采用全文替换。 Agent 主循环与 Run 内图片、视频、语音、音乐可分别结算；素材积分可能在 Run 仍执行时通过 run.usage 到达。事件包含稳定的 usage_id 与非负整数字符串 credits_used。每条是单笔结算值，一个 Run 可有多条；重连可能重放，必须按 usage_id 去重后累加。run.usage 当前不含 tool_call_id 或 sub_type，不要按事件顺序关联某次工具调用。最终文本/工具快照及最终结算事件（若有）在正常终态前发送，终态是最后一个业务帧。结算不可用时不会伪造事件；未收到不代表零消耗。收到 run.completed、run.failed、run.canceled、run.interrupted 或 run.superseded 后结束本次 Run 的展示。收到 run.input_required 时，按事件中的 action.input_schema 收集用户输入并调用 Action 回复接口。收到 preview.ready 时，使用事件中的短时 opaque url 打开预览。 #工具分类、素材事件示例、积分累计与重连规则详见事件流与 Action。接入方应按 Run 保存积分累计与已处理的 usage_id；缓存重放不保证补齐全部历史积分，历史消息接口也不返回积分账单。

预览链接与公开壳

POST /projects/{project_id}/agent/preview-links 是需要 OAuth Access Token 或用户 API Key 的受保护 JSON API，使用 agent.read。请求体省略或传 {}；调用方不能指定 Sandbox、目标 URL、端口或 TTL。本接口不读取也不使用 Idempotency-Key。就绪时返回短时 opaque URL 和 Unix 毫秒 expires_at：

{
  "object": "preview_link",
  "project_id": "event-signup-demo",
  "status": "ready",
  "url": "https://meoo.com/open/preview/opaque-preview-ticket",
  "expires_at": 1787652600000
}

Sandbox 恢复或 dev server 启动仍在后台进行时返回 202、Retry-After: 5 和 retry_after_ms: 5000。按响应等待后重试同一 POST；不要创建新的 Agent Run 代替重试。链接过期后也调用这个受保护接口重新签发。失败响应保持不枚举资源和不泄露上游细节：项目不存在或不可见返回 404 not_found；当前项目形态不可预览返回 409 preview_not_ready；签名配置错误、依赖或上游暂不可用返回 503 service_unavailable。返回 URL 指向 GET /open/preview/{preview_ticket}。这是无需 Authorization 的公开 HTML 浏览器导航路由，只验证 URL 自带的短时 Ticket，并返回带独立 CSP 的全屏 iframe 壳。第三方前端只应把整个 opaque URL 设为 iframe src；不要解析、拼接子路径、写入公开日志或长期存储。公开壳不会恢复 Sandbox，失效后由第三方后端重新签发。 Agent SSE 仅在内部 dev server 已经是 running 且短时链接签发成功时发送 preview.ready；starting 或失败不会产生该事件，也不会暴露 raw Sandbox URL。事件链接过期后，同样调用上述受保护 POST 重新签发。

稳定交互语义

runs/current 返回 input_required 时，使用该 run_id 重新订阅 events；只要阻塞工具仍有效，建连或重连会签发新的 action_id 和 expires_at。
Action Token 过期返回 409 action_expired，已回复返回 409 action_already_responded，Run generation 已变化返回 409 run_conflict。
Run 已经是 canceled 时，重复取消会幂等返回 200；其他不可取消终态返回 409 not_cancelable。
Agent SSE 当前使用 60 秒固定限频窗口。Retry-After: 60 是固定窗口的安全等待上界，不是剩余 TTL；等待后增加少量随机抖动再重连。
run.working 只表示 Run 正在处理；公开阶段和进度文案由 tool.call 的 phase 与 message 承载。
run.superseded.data.status 是旧 Run 的真实终态；current_run_id 仅标识接管的新 Run。

共同约定

启动 Run 的 Idempotency-Key 可选，但生产环境强烈建议每条用户消息都生成；相同逻辑消息重试时复用，不同消息必须更换。
相同 Idempotency-Key 的内部准入去重窗口为 24 小时。
同一项目的资源仍受项目权限、账号状态和额度约束；Scope 不会绕过业务权限。
无权访问的项目、会话、Run 或 Skill 通常与资源不存在一样返回 404。
请求对象是严格 Schema；未声明字段会返回 400 invalid_request。
调用方必须忽略未知响应字段、未知事件名和未知枚举值。
详细的错误、限频、缓存和 SSE 规则见通用协议与运行与安全。

​Agent OpenAPI

​文档导航

​权限

​核心对象

​接口一览

​最小调用流程

​单次运行禁用 Meoo Cloud

​预览链接与公开壳

​稳定交互语义

​共同约定