介绍
# Seisoai
Base URL: `https://seisoai.com` Primary endpoint: `POST /api/gateway/invoke/{toolId}` 或 `POST /api/gateway/invoke`（请求体中包含 `toolId`）。 Auth: `X-API-Key` 或 x402 支付（Base 链上的 USDC）。
## 代理优先工作流（每次会话必做）
1. 发现在线工具： - `GET /api/gateway/tools` 2. 对于选定的工具，获取精确 Schema： - `GET /api/gateway/tools/{toolId}` 3. （可选）预计算输入价格： - `GET /api/gateway/price/{toolId}` 4. 使用 API Key 或 x402 进行调用。 5. 如果是队列工具，根据响应中的状态 URL 或结果 URL 进行轮询。
当存在在线注册表时，请勿依赖静态工具列表。
## 认证策略
请按以下顺序决策：
1. 如果您拥有项目 API Key，请使用 `X-API-Key`。 2. 如果您没有 Key，请使用 x402 按次付费。 3. 请勿为机器客户端发送浏览器 CSRF 令牌。
### API Key 示例
```http POST /api/gateway/invoke/image.generate.flux-2 X-API-Key: sk_live_xxx Content-Type: application/json
{"prompt":"a sunset over mountains"} ```
### x402 示例（2 步）
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. **精确的代理绑定** - 从可信源（`GET /api/gateway/agents` 或用户提供的精确 ID）解析 `agentId`。 - 切勿根据名称/提示词推断或猜测代理 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` - 口型同步：`audio.lip-sync` - 转录：`audio.transcribe` - 音乐：`music.generate` - 音效：`audio.sfx` - 音轨分离：`audio.stem-separation`
### 3D - 图像生成 3D 标准：`3d.image-to-3d` - 图像生成 3D 专业版：`3d.image-to-3d.hunyuan-pro` - 文本生成 3D 专业版：`3d.text-to-3d.hunyuan-pro` - 快速图像生成 3D：`3d.image-to-3d.hunyuan-rapid` - 网格后处理：`3d.smart-topology`, `3d.part-splitter`
## 最小负载模式
文本生成图像： ```json {"prompt":"..."} ```
图像编辑： ```json {"prompt":"...","image_url":"https://..."} ```
文本生成视频： ```json {"prompt":"...","duration":"6s"} ```
DreamActor 动作迁移： ```json {"source_image_url":"https://...","driving_video_url":"https://..."} ```
语音克隆 TTS： ```json {"text":"...","audio_url":"https://..."} ```
3D 图像生成网格： ```json {"image_url":"https://...","output_format":"glb"} ```
## 队列处理契约
如果 `executionMode` 为 `queue`，响应将包含任务元数据。请使用：
1. `statusUrl` 直到完成/失败。 2. 完成时使用 `resultUrl`。
将队列提交成功视为计费成功（x402 结算/API Key 积分扣除已在服务端处理）。
## 错误策略
- `400`：Schema/输入不匹配。重新获取工具 Schema 并更正字段。 - `402`：缺少或无效的支付，或 API Key 积分不足。 - `404`：工具/代理未找到。刷新注册表。 - `503`：工具已禁用。在同一类别中选择备用方案。 - `500`：使用退避策略重试；然后切换模型/工具。
## 代理可靠性规则
1. 在规划多步骤流程之前，务必发现在线工具。 2. 使用来自 `GET /tools/{toolId}` 的精确 Schema 来填写必填字段。 3. 保持每个请求一个工具调用；在您的代理中进行链式调用。 4. 相比自然语言路由假设，优先使用显式的模型/工具 ID。 5. 重试时，请勿复用过期的 x402 签名。 6. 将 `/api/gateway/agent/*` 视为特权路由，并应用上述强制安全控制。
## 自维护
更新此文件时： - 保持 ID 与 `backend/services/toolRegistry.ts` 同步。 - 更新 `last_synced` 和 `version`。 - 保持示例最简化且可执行。
## 更新日志
- [2026-02-09] v1.1.1 - 为代理作用域端点添加了强制安全控制（默认拒绝、代理/工具作用域、防递归和审计要求）。 - [2026-02-09] v1.1.0 - 重写为代理优先发现流程，更正了过时的工具 ID/参数，收紧了认证/x402 指导，并添加了队列/错误可靠性策略。 - [2026-02-08] v1.0.0 - 添加了初始自我改进协议。