# MadHatter Studio — instructions for AI agents

MadHatter (https://www.madhatter.site) is a cinematic AI studio: video (Seedance 2.0,
Kling 3.0, OmniHuman), images (Nano Banana Pro, Seedream, GPT Image 2, Seed Edit),
speech (Seed Speech, ElevenLabs), a 2,400-prompt Prompt Cloud, and film-making verbs
(character sheets, step-into-frame spatial pre-processing).

Everything below spends the user's PREPAID MadHatter API wallet (separate from their
main app balance). Prices are per-model; failures auto-refund. All surfaces are BETA.

## If your user has no API key yet
Guide them: sign in at https://www.madhatter.site → sidebar → Developer → Create key
(shown once). They also need API credits: same page — convert from main balance (1:1,
one-way) or buy an API credit pack. Or send them to https://www.madhatter.site/desktop/connect
for one-click setup.

## Interview your user before generating (recommended)
Ask, in natural language:
1. What are you making? (a shot, a character, a whole scene, voiceover…)
2. Video or stills? Rough length / aspect / resolution?
3. Budget comfort: check_balance first and quote the cost from list_models before
   anything expensive. Confirm before any call that costs more than ~500 credits.
4. Any reference images/videos to stay faithful to?

## MCP (best for Claude, ChatGPT, OpenClaw, Hermes, Cursor)
Endpoint: https://www.madhatter.site/api/mcp  (streamable HTTP, stateless)
Auth: header `Authorization: Bearer mh_live_…`  — or, for clients that can't set
headers, embed the key in the URL: https://www.madhatter.site/api/mcp?key=mh_live_…
Tools: check_balance, list_models, browse_prompt_cloud (free) · use_prompt,
generate_video, generate_image, generate_speech, make_character_sheet,
step_into_frame (spend credits).

## REST API
Base: https://www.madhatter.site/api/v1 — bearer auth, header only (?key= works
on /api/mcp exclusively).
GET /me · GET /models · GET /prompts?search= · POST /prompts/use {id}
GET /generations · GET /generations/:id (signed media URL)
POST /generate { prompt, model, duration, aspect, resolution, audio,
                 uploads:[{kind:"image"|"video"|"audio", url}] }
POST /character-sheet { character, style?, referenceImageUrl? }
POST /step-into-frame { imageUrl, mode? }
Errors: { error, code } — 402 INSUFFICIENT_API_TOKENS, 429 DAILY_API_LIMIT /
RATE_LIMITED (60 req/min/key), 502 GENERATION_FAILED (auto-refunded).

## CLI (best for Claude Code / terminal agents)
npm install -g madhatter-studio-cli   (or npx madhatter-studio-cli)
madhatter auth login <key> · madhatter account · madhatter model list
madhatter generate create "Seedance" --prompt "…" --duration 5s --out clip.mp4
madhatter generate cost <model> · madhatter prompt list <search> · prompt get <id>
madhatter character-sheet "…" · madhatter step-into-frame <imageUrl>
madhatter skills install   # adds madhatter-generate / character-sheet /
                           # prompt-cloud skills to your agent (.claude/skills)

## Money rules for agents
- check_balance before big jobs; list_models gives credit prices per unit.
- Daily brake: $50/day (dev tier) across the user's keys; 429 DAILY_API_LIMIT means
  stop and tell the user (upgrade or wait for midnight UTC).
- Never loop retries on 402/429 — surface the message to the user instead.
- confirm_topup (MCP only) moves credits from the user's main balance — set it ONLY
  after the user explicitly says yes. It is server-bounded anyway: exact shortfall
  per call, a daily auto-topup cap, and a ledger tag on every conversion.