Introduction
# Seisoai
Base URL: `https://seisoai.com` Primary endpoint: `POST /api/gateway/invoke/{toolId}` or `POST /api/gateway/invoke` with `toolId` in body. Auth: `X-API-Key` or x402 payment (USDC on Base).
## Agent-First Workflow (Do This Every Session)
1. Discover live tools: - `GET /api/gateway/tools` 2. For selected tools, fetch exact schema: - `GET /api/gateway/tools/{toolId}` 3. Optionally pre-price inputs: - `GET /api/gateway/price/{toolId}` 4. Invoke with API key or x402. 5. If queue tool, poll job status/result URLs from response.
Do not rely on static tool lists when a live registry is available.
## Auth Strategy
Use this decision order:
1. If you have a project API key, use `X-API-Key`. 2. If you do not have a key, use x402 pay-per-request. 3. Do not send browser CSRF tokens for machine clients.
### API Key Example
```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 Example (2-step)
1. Call without payment header. 2. Receive `402` with payment requirements. 3. Sign/pay on Base. 4. Retry same request with one of: - `payment-signature` - `x-payment` - `payment`
## High-Value Endpoints
- Discovery: - `GET /api/gateway/tools` - `GET /api/gateway/tools/{toolId}` - `GET /api/gateway/price/{toolId}` - `GET /api/gateway/mcp-manifest` - Invoke: - `POST /api/gateway/invoke/{toolId}` - `POST /api/gateway/invoke` - Jobs: - `GET /api/gateway/jobs/{jobId}?model=...` - `GET /api/gateway/jobs/{jobId}/result?model=...` - Agent-scoped: - `GET /api/gateway/agents` - `GET /api/gateway/agent/{agentId}` - `POST /api/gateway/agent/{agentId}/invoke/{toolId?}` - `POST /api/gateway/agent/{agentId}/orchestrate`
## Agent-Scoped Safety Controls (Mandatory)
For normal media generation (images, video, audio, 3D), use **`/api/gateway/invoke`** and the discovery endpoints above; no extra checks. The rules below apply only when the user explicitly asks to run or orchestrate a **specific agent** (e.g. a named bot or workflow).
Default posture: **deny by default** for agent-scoped routes (`/api/gateway/agent/*`). Use agent-scoped endpoints only when all checks pass:
1. **Explicit task requirement** - Do not call `/agent/*` routes unless the current task explicitly requires operating a specific agent. 2. **Exact agent binding** - Resolve `agentId` from a trusted source (`GET /api/gateway/agents` or user-provided exact ID). - Never infer or guess agent IDs from names/prompts. 3. **Authorization boundary** - Use only the current caller credentials. - Never attempt to reuse, escalate, or proxy credentials to access other tenants/owners. 4. **Single-agent scope** - For one task, operate on one approved `agentId` unless the user explicitly requests multi-agent execution. 5. **Tool allowlist enforcement** - Before invoke/orchestrate, fetch `GET /api/gateway/agent/{agentId}` and only use tool IDs declared for that agent. - Reject tool IDs not listed in that agent definition. 6. **No recursive orchestration** - Do not create self-referential orchestrations, orchestration loops, or fan-out patterns across unknown agents. 7. **No broad discovery exfiltration** - Do not enumerate all agents unless needed for user task; prefer direct lookup when `agentId` is known. 8. **Audit trail requirement** - Log `agentId`, route, tool ID, and reason for each agent-scoped call in agent run notes. 9. **On mismatch or ambiguity: stop** - If ownership/scope/tool authorization is ambiguous, do not call `/agent/*`; fall back to `/api/gateway/invoke`.
## Tool Selection Cheatsheet (Verified IDs)
### Images - Fast text->image: `image.generate.flux-2` - Premium cinematic: `image.generate.kling-image-v3` - Premium consistency: `image.generate.kling-image-o3` - 360/panorama: `image.generate.nano-banana-pro` - Prompted edit: `image.generate.flux-pro-kontext-edit` - Face swap: `image.face-swap` - Inpaint/outpaint: `image.inpaint`, `image.outpaint` - Background removal/layer: `image.extract-layer` - Upscale: `image.upscale`
### Video - Text->video (Veo): `video.generate.veo3` - Image->video (Veo): `video.generate.veo3-image-to-video` - First/last frame: `video.generate.veo3-first-last-frame` - Kling text: `video.generate.kling-3-pro-text`, `video.generate.kling-3-std-text` - Kling image: `video.generate.kling-3-pro-image`, `video.generate.kling-3-std-image` - Motion transfer: `video.generate.dreamactor-v2`
### Audio / Speech / Music - Voice clone TTS: `audio.tts` - TTS quality tiers: `audio.tts.minimax-hd`, `audio.tts.minimax-turbo` - Lip sync: `audio.lip-sync` - Transcription: `audio.transcribe` - Music: `music.generate` - Sound FX: `audio.sfx` - Stem separation: `audio.stem-separation`
### 3D - Image->3D standard: `3d.image-to-3d` - Image->3D pro: `3d.image-to-3d.hunyuan-pro` - Text->3D pro: `3d.text-to-3d.hunyuan-pro` - Fast image->3D: `3d.image-to-3d.hunyuan-rapid` - Mesh post-processing: `3d.smart-topology`, `3d.part-splitter`
## Minimal Payload Patterns
Text->image: ```json {"prompt":"..."} ```
Image edit: ```json {"prompt":"...","image_url":"https://..."} ```
Text->video: ```json {"prompt":"...","duration":"6s"} ```
DreamActor motion transfer: ```json {"source_image_url":"https://...","driving_video_url":"https://..."} ```
Voice clone TTS: ```json {"text":"...","audio_url":"https://..."} ```
3D image->mesh: ```json {"image_url":"https://...","output_format":"glb"} ```
## Queue Handling Contract
If `executionMode` is `queue`, response includes job metadata. Use:
1. `statusUrl` until completed/failed. 2. `resultUrl` when completed.
Treat queue submit success as billable success (x402 settlement/API-key credit deduction already handled server-side).
## Error Policy
- `400`: Schema/input mismatch. Re-fetch tool schema and correct fields. - `402`: Missing/invalid payment or insufficient API key credits. - `404`: Tool/agent not found. Refresh registry. - `503`: Tool disabled. Select fallback in same category. - `500`: Retry with backoff; then switch model/tool.
## Reliability Rules for Agents
1. Always discover live tools before planning multi-step flows. 2. Use exact schema from `GET /tools/{toolId}` for required fields. 3. Keep one tool call per request; chain in your agent. 4. Prefer explicit model/tool IDs over natural-language routing assumptions. 5. For retries, do not reuse stale x402 signatures. 6. Treat `/api/gateway/agent/*` as privileged routes and apply the mandatory safety controls above.
## Self-Maintenance
When this file is updated: - Keep IDs aligned with `backend/services/toolRegistry.ts`. - Update `last_synced` and `version`. - Keep examples minimal and executable.
## Changelog
- [2026-02-09] v1.1.1 - Added mandatory safety controls for agent-scoped endpoints (deny-by-default, agent/tool scoping, anti-recursion, and audit requirements). - [2026-02-09] v1.1.0 - Rewrote for agent discovery-first flow, corrected stale tool IDs/params, tightened auth/x402 guidance, and added queue/error reliability policy. - [2026-02-08] v1.0.0 - Initial self-improvement protocol added.