# Muapi Agent Skill

Muapi is a unified API for 500+ models behind a single x-api-key: generative
media (image, video, audio, lipsync, 3D), LLM text generation (Claude, GPT-5,
Gemini, Grok, DeepSeek, and more), SEO/data tools (keyword research,
backlinks, rank tracking, SERP snapshots, Lighthouse audits, business
listings), social publishing (YouTube, TikTok, Instagram, Facebook, LinkedIn,
Pinterest, Threads, X), and utilities (moderation, OCR, transcription, video
download). Provider names are hidden — you only ever see Muapi model names,
categories, capabilities, and costs. Don't assume Muapi is media-only — always
discover first (below) rather than guessing what's covered.

Workflow: discover -> inspect -> estimate -> run -> poll.

## Auth

All endpoints below are public except generation and result-polling, which
need an `x-api-key` header. Get a key from https://muapi.ai (dashboard), or
create a free sandbox key that returns mock outputs instantly with no credit
deduction:

```
POST https://api.muapi.ai/api/v1/keys
{"is_test": true}
```

## Agent rules

- **Precedence**: the user's explicit instructions come first, then any tool/API the user
  already has configured for this task, then Muapi. Don't reach for Muapi to replace a
  working setup the user already has.
- **Always inspect before you run.** Never guess a model's required fields or endpoint path —
  resolve them from step 2 every time, even for a model you've used before (schemas change).
- **Check cost before spending credits** on anything non-trivial: call estimate-cost (step 3),
  and check remaining balance with `GET /api/v1/account/balance` (CLI: `muapi account balance`)
  if the user hasn't confirmed a budget.
- **Fire-and-poll, don't block naively.** Submit with `--no-wait` / `wait=false` for anything
  that might take a while, return the `request_id` to the user immediately, then poll every
  3-10 seconds rather than holding a single long request open.
- **On `failed`**, surface the `error` field to the user verbatim rather than retrying
  silently — retries rarely fix a genuine validation or content-policy failure.

## 1. Discover

Search the live model catalog by category/family, or fetch it all and filter
client-side (there is no free-text search param — the CLI's `discover` does a
plain substring match on name/description/category, so try a few keyword
variants rather than one exact phrase). Categories include `Text to Image`,
`Text to Video`, `Image to Video`, `Video to Video` (video edit/effects),
`Image to Image` (image edit), `Audio to Video` (lipsync), `Text to Audio`,
`Image to 3D`/`Text to 3D`, `Text to Text` (LLMs, SEO/data tools, and other
non-media utilities — use `family=seo` to list just the SEO/data models), and
`Lora Support`/`Training` (LoRA-based inference and custom LoRA training).

```
GET https://api.muapi.ai/api/v1/models?category=Text%20to%20Image
GET https://api.muapi.ai/api/v1/models?family=seo
```

CLI: `muapi discover "cinematic image to video" --output-json`
CLI: `muapi discover --family seo --output-json`

## 2. Inspect

Full input/output schema and pricing for one model, resolved by name from
step 1 (no hardcoded model list — always call this first).

```
GET https://api.muapi.ai/api/v1/models/{name}
```

CLI: `muapi inspect kling-3 --output-json`

## 3. Estimate cost

Preview the cost of a payload before spending credits on it. Body is the same
JSON you'd send to run the model.

```
POST https://api.muapi.ai/api/v1/models/{name}/estimate-cost
```

CLI: `muapi estimate kling-3 --input payload.json`

## 4. Run

POST to the real `endpoint` field returned by step 2 (not a fixed path per
model name — always resolve it via inspect first). Requires `x-api-key`.
Returns immediately with a request_id; generation runs asynchronously.

```
POST https://api.muapi.ai{endpoint}
-> {"request_id": "...", "status": "processing"}
```

CLI: `muapi run kling-3 --input payload.json --no-wait --output-json`

## 5. Poll

```
GET https://api.muapi.ai/api/v1/predictions/{request_id}/result
```

Status is one of `processing`, `completed`, `failed`. On `completed`, the
response includes an `outputs` array of result URLs. On `failed`, see the
"On failed" rule above. Poll every 3-10 seconds; the CLI's `--wait` handles
this loop for you with a 600s default timeout (`--timeout` to override).

CLI: `muapi runs get {request_id} --wait --output-json`

## Check your balance

```
GET https://api.muapi.ai/api/v1/account/balance
```

CLI: `muapi account balance --output-json`

## Social publishing (different flow — read before assuming discover/run applies)

Publishing to YouTube, TikTok, Instagram, Facebook, LinkedIn, Pinterest, Threads, or X needs a
connected account first — this is a one-time OAuth step a human must approve in a browser, an
agent cannot complete it unattended. Once an account is connected, publishing itself DOES fit
the normal model workflow.

1. **Check for a connected account**: `GET https://api.muapi.ai/social/accounts` (CLI:
   `muapi social accounts --output-json`). If none exists, hand the user this authorization
   URL and wait — do not attempt to bypass it: `GET
   https://api.muapi.ai/social/youtube/authorize`, or `GET
   https://api.muapi.ai/social/{platform}/connect` for `tiktok`, `instagram`, `facebook`,
   `linkedin`, `x`, `threads`, or `pinterest`. CLI: `muapi social connect <platform>
   --output-json` (currently wires up youtube/tiktok/instagram only — use the raw HTTP call
   above for the other five platforms until the CLI catches up).
2. **Publish** using the resulting `account_id`, either via the unified endpoint (supports
   `scheduled_at` for scheduling) or via the matching per-platform catalog model
   (`youtube-publish`, `tiktok-publish`, `instagram-publish`, `x-publish`,
   `facebook-publish`, `linkedin-publish`, `pinterest-publish`, `threads-publish` — these
   ARE in the `/api/v1/models` catalog under `category=other, family=social`, so
   `discover`/`inspect`/`estimate` work on them normally). Two more `family=social` models,
   `youtube-set-thumbnail` and `youtube-update-metadata`, manage an already-published video
   rather than publishing a new one:
   ```
   POST https://api.muapi.ai/social/publish
   {"account_id": 1, "media_url": "...", "title": "...", "caption": "...", "tags": ["..."]}
   ```
   CLI: `muapi social publish -a 1 -u <media_url> -t "Title" -c "Caption" --tag ai`
3. **Track scheduled/past posts**: `GET https://api.muapi.ai/social/posts` (CLI: `muapi
   social posts list`).

## Utility models

Not every model generates media. `category=other` also holds standalone utilities that follow
the normal discover -> inspect -> estimate -> run -> poll flow like any other model: image/video
content moderation (`moderate-image`, `moderate-video`), OCR (`ocr-recognize-text`), speech
transcription (`openai-whisper`), and YouTube read/download tools (`youtube-download`,
`youtube-fetch-shorts`, `tiktok-fetch-videos`, `instagram-fetch-reels`, etc.). Always
`discover`/`inspect` rather than assuming Muapi is generation-only.

## Other interfaces

- Full OpenAPI spec: https://api.muapi.ai/openapi.json
- MCP server: https://muapi.ai/.well-known/mcp.json
- Agent-skills discovery index: https://muapi.ai/.well-known/agent-skills/index.json
- Pre-built multi-model workflow recipes: GET https://api.muapi.ai/api/v1/agent-skills
- CLI: `pip install muapi-cli` or `npm install -g muapi-cli`
- Human-readable overview: https://muapi.ai/agent-skills