Seisoai

基础URL：https://seisoai.com主要端点：POST /api/gateway/invoke/{toolId}或POST /api/gateway/invoke附带toolId在请求体中。 认证：X-API-Key或 x402 支付（Base链上的USDC）。

Agent-First 工作流程（每个会话都执行此流程）

1. 发现实时可用工具：
   • GET /api/gateway/tools
2. 对于选定的工具，获取其精确模式：
   • GET /api/gateway/tools/{toolId}
3. 可选地对输入进行预定价：
   • GET /api/gateway/price/{toolId}
4. 使用 API 密钥或 x402 进行调用。
5. 如果是队列工具，则根据响应轮询作业状态/结果URL。

当存在实时注册表时，请勿依赖静态工具列表。

认证策略

请按以下决策顺序执行：

1. 如果您拥有项目API密钥，请使用X-API-Key。
2. 如果没有密钥，请使用x402按次付费模式。
3. 请勿为机器客户端发送浏览器CSRF令牌。

API密钥示例

POST /api/gateway/invoke/image.generate.flux-2
X-API-Key: sk_live_xxx
Content-Type: application/json

{"prompt":"a sunset over mountains"}

x402示例（两步流程）

1. 首次调用时不携带支付请求头。
2. 接收包含支付要求的402状态码响应。
3. 在Base链上进行签名/支付。
4. 使用以下任一请求头重试相同请求：
   • payment-signature
   • x-payment
   • payment

高价值端点

• 发现接口：
  • GET /api/gateway/tools
  • GET /api/gateway/tools/{toolId}
  • GET /api/gateway/price/{toolId}
  • GET /api/gateway/mcp-manifest
• 调用：
  • POST /api/gateway/invoke/{toolId}
  • POST /api/gateway/invoke
• 作业：
  • GET /api/gateway/jobs/{jobId}?model=...
  • GET /api/gateway/jobs/{jobId}/result?model=...
• 代理作用域：
  • GET /api/gateway/agents
  • GET /api/gateway/agent/{agentId}
  • POST /api/gateway/agent/{agentId}/invoke/{toolId?}
  • POST /api/gateway/agent/{agentId}/orchestrate

代理作用域安全控制（强制）

对于常规媒体生成（图像、视频、音频、3D），请使用/api/gateway/invoke以及上述发现端点；无需额外检查。以下规则仅当用户明确要求运行或编排特定代理（例如，指定的机器人或工作流）时才适用。

默认策略：默认拒绝对于代理作用域的路由（/api/gateway/agent/*）。仅当所有检查都通过时，才使用代理作用域的端点：

1. 明确的任务要求
   • 除非当前任务明确要求操作特定代理，否则不要调用/agent/*路由。
2. 精确的代理绑定
   • 从可信来源解析agentId（GET /api/gateway/agents或用户提供的精确ID）。
   • 切勿从名称或提示中推断或猜测代理ID。
3. 授权边界
   • 仅使用当前调用者的凭据。
   • 切勿尝试重用、提升或代理凭据以访问其他租户或所有者。
4. 单代理作用域
   • 对于一个任务，仅在一个已批准的agentId上操作，除非用户明确请求多代理执行。
5. 工具白名单强制执行
   • 在调用/编排前，先获取GET /api/gateway/agent/{agentId}并仅使用为该代理声明的工具ID。
   • 拒绝未列在该代理定义中的工具ID。
6. 禁止递归编排
   • 不要创建自引用的编排、编排循环或在未知代理间进行扇出模式。
7. 禁止广泛发现式数据外泄
   • 除非用户任务需要，否则不要枚举所有代理；当agentId已知时，优先采用直接查找。
8. 审计追踪要求
   • 在代理运行记录中，为每个代理作用域内的调用记录agentId、路由、工具ID及原因。
9. 当出现不匹配或歧义时：停止
   • 如果所有权/作用域/工具授权存在歧义，不要调用/agent/*；应回退到/api/gateway/invoke.

工具选择速查表（已验证ID）

图像

• 快速文本转图像：image.generate.flux-2
• 高级电影质感：image.generate.kling-image-v3
• 高级一致性：image.generate.kling-image-o3
• 360度/全景：image.generate.nano-banana-pro
• 提示词编辑：image.generate.flux-pro-kontext-edit
• 换脸：image.face-swap
• 图像修复/扩展：image.inpaint,image.outpaint
• 背景移除/图层提取：image.extract-layer
• 图像放大：image.upscale

视频

• 文本生成视频 (Veo)：video.generate.veo3
• 图像生成视频 (Veo)：video.generate.veo3-image-to-video
• 首尾帧控制：video.generate.veo3-first-last-frame
• Kling 文本生成：video.generate.kling-3-pro-text,video.generate.kling-3-std-text
• Kling 图像生成：video.generate.kling-3-pro-image,video.generate.kling-3-std-image
• 动作迁移：video.generate.dreamactor-v2

音频 / 语音 / 音乐

• 语音克隆 TTS：audio.tts
• TTS 质量等级：audio.tts.minimax-hd,audio.tts.minimax-turbo
• 唇形同步：音频口型同步
• 转录：音频转录
• 音乐：音乐生成
• 音效：音频.音效
• 音轨分离：音频.音轨分离

3D

• 图像->3D 标准版：3d.图像转3d
• 图像->3D 专业版：3d.图像转3d.混元专业版
• 文本->3D 专业版：3d.文本转3d.混元专业版
• 快速图像->3D：3d.图像转3d.混元快速版
• 网格后处理：3d.智能拓扑,3d.部件分割器

最小负载模式

文本->图像：

{"prompt":"..."}

图像编辑：

{"prompt":"...","image_url":"https://..."}

文本转视频：

{"prompt":"...","duration":"6s"}

DreamActor动作迁移：

{"source_image_url":"https://...","driving_video_url":"https://..."}

语音克隆TTS：

{"text":"...","audio_url":"https://..."}

3D图像转网格：

{"image_url":"https://...","output_format":"glb"}

队列处理协议

若执行模式为队列模式，响应将包含任务元数据。请使用：

1. 状态查询链接轮询直至任务完成/失败。
2. 结果获取链接将在任务完成后提供。

队列提交成功即视为计费成功（x402结算/API密钥额度扣减已在服务端处理）。

错误处理策略

• 400：模式/输入不匹配。请重新获取工具模式并修正字段。
• 402：支付信息缺失/无效或API密钥额度不足。
• 404：未找到工具/智能体。请刷新注册表。
• 503工具已禁用。请选择同一类别中的备用方案。
• 500：使用退避机制重试；然后切换模型/工具。

智能体可靠性规则

1. 在规划多步骤流程前，务必先发现可用工具。
2. 对于必填字段，请使用来自GET /tools/{toolId}的精确模式。
3. 每个请求仅调用一个工具；在您的智能体中串联执行。
4. 优先使用明确的模型/工具ID，而非基于自然语言的路由假设。
5. 重试时，请勿复用过时的x402签名。
6. 将/api/gateway/agent/*视为特权路由，并应用上述强制性安全控制。

自我维护

当此文件更新时：

• 保持ID与backend/services/toolRegistry.ts中的一致。
• 更新last_synced和版本.
• 保持示例简洁且可执行。

更新日志

• [2026-02-09] v1.1.1 - 为代理范围端点增加了强制性安全控制（默认拒绝、代理/工具范围限定、防递归以及审计要求）。
• [2026-02-09] v1.1.0 - 为代理发现优先流程重写，修正了过时的工具ID/参数，强化了认证/x402指导，并增加了队列/错误可靠性策略。
• [2026-02-08] v1.0.0 - 新增初始自改进协议。