Seisoai

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

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:

{"prompt":"..."}

Image edit:

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

Text->video:

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

DreamActor motion transfer:

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

Voice clone TTS:

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

3D image->mesh:

{"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.