# NamiFusion — Agent Integration Guide

NamiFusion exposes AI generation, face swap, an API model marketplace, and canvas workflow orchestration to CLI/coding agents over **remote MCP** (preferred) or a plain **REST API** (fallback).

## Endpoints

| Server | URL | Capability |
|---|---|---|
| Generation MCP | `https://www.namifusion.com/api/v1/task/mcp/` | AI generation (image/video/audio), face swap, task management, file uploads |
| Marketplace MCP | `https://www.namifusion.com/api/v1/marketplace/mcp/` | Discover and run third-party API models |
| Workflow MCP | `https://www.namifusion.com/api/v1/workflow/mcp` | Read/mutate canvas workflows and execute nodes |

All three use the [MCP Streamable HTTP transport](https://modelcontextprotocol.io/) (JSON responses).

## Authentication

Every request (MCP or REST) must carry one of:

1. `Authorization: Bearer sk-...` — API key
2. `Authorization: Bearer <jwt>` — session token (same JWT the web app uses; not recommended for agents)
3. `X-API-Key: sk-...` — API key via dedicated header

Create an API key on the [API Keys page](https://www.namifusion.com/api-keys) (sign-in required). Treat `sk-...` like a password — do not commit it or log it.

## Tool reference (21 tools)

Arguments marked `?` are optional. `ctx` (the MCP request context) is implicit and not user-supplied.

### Workflow MCP — 7 tools

| Tool | Arguments | Behavior |
|---|---|---|
| `workflow_list` | — | List workflows accessible to the current authenticated user. |
| `workflow_get_canvas` | `workflow_id` | Get the current saved workflow canvas and its revision token. |
| `workflow_upsert_node` | `workflow_id`, `revision`, `data`, `node_id?`, `node_type?` (`text`\|`image`\|`video`\|`asset`), `position?`, `parent_ids?` | Create or update a single workflow node. |
| `workflow_patch_topology` | `workflow_id`, `revision`, `add_edges?`, `remove_edges?`, `delete_node_ids?` | Apply explicit edge-add/remove and node-delete operations to a workflow's topology. |
| `workflow_execute` | `workflow_id`, `target_node_ids`, `rerun_node_ids?` | Create or append a node-session execution for the given nodes. |
| `workflow_get_run` | `run_id` | Get a workflow run's status and all currently completed node outputs. |
| `workflow_wait_run` | `run_id`, `timeout_seconds?=30`, `poll_interval_seconds?=2` | Poll a workflow run until it reaches a terminal state or the timeout elapses. |

All node references are by workflow `node_id`. `revision` is a concurrency token returned by `workflow_get_canvas`; mutating calls fail if it is stale.

### Generation MCP — 8 tools

| Tool | Arguments | Behavior |
|---|---|---|
| `generation_list_models` | `media_type` (`image`\|`video`\|`audio`) | List available generation models for a media type. Call first to discover valid `model_id` values. |
| `generation_create_task` | `model_id`, `task_type`, `input_params`, `title?`, `webhook_url?` | Create and enqueue a generation task (image/video/audio), consuming credits up front. JWT calls are rate limited to **20 requests/minute** per user; API key calls use the account-wide API key RPM bucket and optionally an explicit per-key `rate_limit_per_minute`. Use `upload_asset` first if `input_params` needs a locally-held file. |
| `faceswap_create_task` | `model_id`, `task_type` (`video_single_face_swap`\|`video_multi_face_swap`\|`picture_single_face_swap`\|`picture_multi_face_swap`), `source_url`, `target_url`, `single_face_mode?=true`, `face_enhance?=false`, `model_style?` (`realistic`\|`beautify`\|`lossless`\|`high_similarity`, default `realistic`), `face_mapping?`, `time_range?`, `title?` | Create and enqueue a face-swap task, consuming credits up front. JWT calls are rate limited to **30 requests/minute** per user; API key calls use the account-wide API key RPM bucket and optionally an explicit per-key `rate_limit_per_minute`. `source_url`/`target_url` must be reachable URLs — upload local files with `upload_asset` first. |
| `task_get` | `task_uuid` | Get a single task by uuid. Only the owning user's tasks are visible. |
| `task_list` | `skip?=0`, `limit?=20`, `status?`, `media_type?` | List the authenticated user's tasks, optionally filtered by status or media type. |
| `task_wait` | `task_uuid`, `timeout_seconds?=300`, `poll_interval_seconds?=5` | Poll a task until it reaches a terminal state (completed/failed/cancelled) or the timeout elapses; returns `timed_out: true` if the deadline is hit first. |
| `task_cancel` | `task_uuid` | Cancel a pending/queued task owned by the caller and refund any consumed credits. Fails if the task is not cancellable. |
| `upload_asset` | `filename`, `content_type`, `size` | Step 1 of the two-step upload flow: request a presigned COS upload URL for a local file. `size` is the file size in bytes. See [Uploading local files](#uploading-local-files-upload_asset). |

### Marketplace MCP — 6 tools

| Tool | Arguments | Behavior |
|---|---|---|
| `marketplace_list_models` | `search?`, `task_type?`, `skip?=0`, `limit?=20` | List active marketplace models, optionally filtered by task type or search keyword. Call first to discover valid `model_id` values. |
| `marketplace_get_model` | `model_id` | Get full details for a single marketplace model, including its input `parameters` schema — read this before calling `marketplace_run_model`. |
| `marketplace_run_model` | `model_id`, `input_params`, `webhook_url?` | Run a marketplace model, consuming credits up front. JWT calls use the default **20 requests/minute** bucket; API key calls use the account-wide API key RPM bucket and optionally an explicit per-key `rate_limit_per_minute`. Returns `task_uuid`/`status`; poll with `marketplace_get_task` or `marketplace_wait_task`. |
| `marketplace_get_task` | `task_uuid` | Get a single marketplace task by uuid. Only the owning user's tasks are visible. |
| `marketplace_wait_task` | `task_uuid`, `timeout_seconds?=300`, `poll_interval_seconds?=5` | Poll a marketplace task until it reaches a terminal state (completed/failed/cancelled) or the timeout elapses; returns `timed_out: true` if the deadline is hit first. |
| `marketplace_list_tasks` | `skip?=0`, `limit?=20`, `status?`, `model_id?` | List the authenticated user's marketplace tasks, optionally filtered by status or model_id. |

## Client configuration

Replace `sk-YOUR_API_KEY` with a real key from the API Keys page.

### Claude Code

```bash
claude mcp add --transport http namifusion-gen https://www.namifusion.com/api/v1/task/mcp/ --header "Authorization: Bearer sk-YOUR_API_KEY"
claude mcp add --transport http namifusion-market https://www.namifusion.com/api/v1/marketplace/mcp/ --header "Authorization: Bearer sk-YOUR_API_KEY"
claude mcp add --transport http namifusion-workflow https://www.namifusion.com/api/v1/workflow/mcp --header "Authorization: Bearer sk-YOUR_API_KEY"
```

### Codex CLI (`~/.codex/config.toml`)

```toml
[mcp_servers.namifusion_gen]
url = "https://www.namifusion.com/api/v1/task/mcp/"
http_headers = { "Authorization" = "Bearer sk-YOUR_API_KEY" }
```

Add `namifusion_market` / `namifusion_workflow` blocks the same way, pointing at the Marketplace / Workflow URLs.

### Gemini CLI (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "namifusion-gen": {
      "httpUrl": "https://www.namifusion.com/api/v1/task/mcp/",
      "headers": {
        "Authorization": "Bearer sk-YOUR_API_KEY"
      }
    }
  }
}
```

### Any stdio-only MCP client, via `mcp-remote`

```bash
npx -y mcp-remote https://www.namifusion.com/api/v1/task/mcp/ --header "Authorization: Bearer sk-YOUR_API_KEY"
```

## REST fallback

Without MCP, the marketplace surface is also reachable directly over REST (same API key, via `X-API-Key` or `Authorization: Bearer`):

| REST | Equivalent MCP tool |
|---|---|
| `GET /api/v1/marketplace/models` | `marketplace_list_models` |
| `GET /api/v1/marketplace/models/detail?model_id={model_id}` | `marketplace_get_model` |
| `POST /api/v1/marketplace/run/{model_id}` | `marketplace_run_model` |
| `GET /api/v1/marketplace/run/tasks/{task_uuid}` | `marketplace_get_task` |
| `GET /api/v1/marketplace/run/tasks` | `marketplace_list_tasks` |

Example:

```bash
curl -X POST https://www.namifusion.com/api/v1/marketplace/run/MODEL_ID \
  -H "X-API-Key: sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {...}}'
```

Generation, face swap, and workflow are MCP-first: prefer `generation_create_task` / `faceswap_create_task` / `workflow_execute` over REST for those.

## Uploading local files (`upload_asset`)

`generation_create_task`, `faceswap_create_task`, and workflow node inputs all take **URLs**, not raw bytes. To use a local file, upload it first:

1. Call `upload_asset(filename, content_type, size)` → returns `{ upload_url, file_url, cos_key, content_type, expires_in }`.
2. `HTTP PUT` the raw file bytes to `upload_url` with the **same** `Content-Type` header used in step 1.
3. Use `file_url` wherever the task/node expects an input URL (e.g. `source_url`, `target_url`, an image/video field in `input_params`).

`upload_url` expires in `expires_in` seconds (3600). Supported `content_type` values cover common image (`image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`), video (`video/mp4`, `video/quicktime`, `video/x-msvideo`, `video/x-ms-wmv`, `video/webm`, `video/mpeg`), and audio (`audio/mpeg`, `audio/wav`, `audio/ogg`, `audio/aac`, `audio/flac`, `audio/mp4`) MIME types. Size limits match user uploads: images 50MB, videos 5GB, audio 100MB.

## Rate limits

| Surface | Limit |
|---|---|
| `generation_create_task` | JWT: 20 requests/minute per user. API key: account-wide API key RPM, plus the key's `rate_limit_per_minute` only when explicitly configured |
| `faceswap_create_task` | JWT: 30 requests/minute per user. API key: account-wide API key RPM, plus the key's `rate_limit_per_minute` only when explicitly configured |
| `marketplace_run_model` | JWT: 20 requests/minute per user. API key: account-wide API key RPM, plus the key's `rate_limit_per_minute` only when explicitly configured |

Exceeding a limit raises an error naming the number of seconds to wait before retrying.

## See also

- Interactive setup page (same content, in-browser): https://www.namifusion.com/for-agents
- Site overview for LLMs: https://www.namifusion.com/llms.txt