# OdinxD — Autonomous AI Video Studio (Official MCP & REST API v1 Guide)

> OdinxD (https://odinxd.com) is an autonomous 9:16 short-form AI video production platform. It exposes an official hosted Model Context Protocol (MCP) server over Streamable HTTP (`https://odinxd.com/api/mcp`) and an authenticated REST API v1 (`https://odinxd.com/api/v1/*`), plus lightweight zero-dependency local bridges (`odinxd-mcp.mjs` for Node.js and `odinxd_mcp_client.py` for Python) for uploading local PC files.

- Official GitHub Repository (OdinMCP v2.2 — Atomic AI Image/Video Studio, Local Assembler & 4 Skills): https://github.com/odinxd-ai/OdinMCP
- Interactive Human & Developer Docs: https://odinxd.com/docs
- Generate Personal API Keys (`odx_live_...` — requires active Starter or Pro plan): https://odinxd.com/dashboard?section=mcp
- Hosted MCP Endpoint (Streamable HTTP JSON-RPC 2.0): https://odinxd.com/api/mcp
- Local PC Bridge + Pre-Production & Assembly Studio via npx (Node.js >= 18, zero npm deps): `npx --allow-git=all -y github:odinxd-ai/OdinMCP`
- Install All 4 Official Creative Skills (`odin-ugc-factory`, `odin-cinematic-faceless`, `odin-microdrama-director`, `odin-video-preproduction`): `npx skills add odinxd-ai/OdinMCP` (or in Claude Code: `/plugin marketplace add odinxd-ai/OdinMCP` -> `/plugin install odinmcp@odinxd`)
- Local PC File Upload Bridge direct file (Node.js >= 18): https://odinxd.com/mcp/odinxd-mcp.mjs
- Local Pre-Production & Timeline Assembler direct file (Python 3): https://odinxd.com/mcp/odin_preprod.py
- Local PC File Upload Bridge (Python + uv): https://odinxd.com/mcp/odinxd_mcp_client.py
- Public Catalog Endpoint (no auth required, supports `?section=omni_voices`): https://odinxd.com/api/v1/catalog

## CRITICAL PRE-PRODUCTION RULES FOR AI AGENTS (CLEAN SINGLE A-ROLL ONLY)

Before calling ANY A-Roll editing tool (`render_hybrid_reel`, `render_viral_beat`, `render_motion_stock`, `render_maxy_overlay`, `render_fitness_talking_head`), you **MUST** know and enforce these three rules:

1. **CLEAN VIDEO ONLY (NO SILENCES OR SPOKEN MISTAKES):**
   - OdinxD **ONLY works with clean, already-trimmed A-Roll videos**.
   - OdinxD **DOES NOT** cut out dead silences, long pauses, stutters, retakes, false starts, or spoken bloopers/errors. Whatever audio and timing exists in `video_url` becomes the exact spoken timeline of the final reel.
2. **STRICTLY ONE SINGLE BASE VIDEO (`video_url`) PER RENDER:**
   - OdinxD **CANNOT** take multiple base A-Roll videos (e.g., `take1.mp4`, `take2.mp4`, `take3.mp4`) and stitch/concatenate them into a single composition.
   - `video_url` accepts **strictly ONE continuous base video file**. Never pass multiple A-Roll clips in `custom_stock` hoping OdinxD will concatenate spoken parts (`custom_stock` is strictly for short muted visual B-Roll overlays).
3. **MANDATORY PROACTIVE AGENT BEHAVIOR — OFFER TO CLEAN & MERGE LOCALLY FIRST:**
   - Whenever a user provides raw unedited footage, mentions silences/mistakes, or provides multiple video takes:
     - **DO NOT** send raw/unmerged files directly to OdinxD (that would waste the user's render quota and AI credits).
     - **PROACTIVELY OFFER TO USE YOUR OWN AGENT TOOLS FIRST** (e.g., local `ffmpeg` `silencedetect` / `aselect`, `auto-editor`, Whisper word-level transcription timestamps, and `ffmpeg -f concat`) to:
       1. Cut out dead silences and awkward pauses,
       2. Trim out spoken errors, stutters, or repeated sentences,
       3. Concatenate multiple takes into **one single, clean, continuous `.mp4` master file**,
     - And **only after** producing (or confirming the user already has) that single clean `.mp4`, send it to OdinxD to generate AI B-Roll, Motion Graphics, split-screens, SFX, and dynamic subtitles!
   - *(Note: `create_faceless_ad` generates the voiceover and scenes 100% from text/script, so it does not require any A-Roll video).*

## MASTER CREATIVE DIRECTOR RULES FOR AI AGENTS (AVATAR SAFETY & ART DIRECTION)

1. **STRICT ANTI-CELEBRITY / PUBLIC FIGURE RULE (`PROMINENT_PERSON_BLOCKED`):**
   - Face-cloning styles (`avatar_stock`, `ugc_stock`, `inmo_avatar_stock`) **ONLY accept reference photos of private creators, agents, or clients**.
   - **NEVER** pass photos of celebrities, famous podcasters, politicians, athletes, or public figures in `avatar_image` — the AI video engine blocks public-figure likeness (`prominent individuals`) and OdinxD will automatically abort the render with `0` render/credit charge to protect the user's balance.
   - Whenever the video features a **public figure, celebrity, or third-party podcast**, you **MUST** select faceless cinematic/editorial styles: `["stock_hyperreal", "cinematic_macro"]`, `["scrapbook_polaroid", "vox_editorial"]`, or `["parallax_3d", "mannequin_3d"]`.
2. **MANDATORY REFERENCE ASSETS PER STYLE (PRE-FLIGHT VALIDATED):**
   - `avatar_stock` → requires `avatar_image` (clear JPG/PNG/WEBP of a private individual).
   - `inmo_avatar_stock` → requires `avatar_image` + `inmo_photos` (≥1 room labeled).
   - `inmo_tour` → requires `inmo_photos` (≥1 room labeled; person-free POV).
   - `inmo_tour_transition` → requires `inmo_photos` (≥2 distinct rooms for continuous POV transition).
   - `ugc_stock` → requires `product_images` (1–3 real product photos) + optional `avatar_image`.
   - All other 15 styles (`stock_hyperreal`, `scrapbook_polaroid`, `cinematic_macro`, `parallax_3d`, etc.) require `0` reference images.
3. **MASTER ART DIRECTION MATRIX BY NICHE (SUBTITLES & TYPOGRAPHY):**
   - **Default Subtitle Rule:** Use `subtitle_style: "kinetic_dinamic"` (OdinxD Web Editor default) or `"kinetic_blur"`. Reserve `"dynamic"` and `"boxed_highlighter"` strictly for pure Fitness / high-impact talking-head reels (`"dynamic"` renders Fitness-style popup subtitles).
   - **Podcast / Business / Authority:** `render_hybrid_reel` or `render_viral_beat` + `ai_styles: ["stock_hyperreal", "scrapbook_polaroid"]` + `typography: "Montserrat"` + `subtitle_style: "kinetic_dinamic"` or `"kinetic_blur"`.
   - **Real Estate / Luxury Property:** `render_hybrid_reel` + `ai_styles: ["inmo_avatar_stock", "inmo_tour_transition"]` (or `["inmo_tour", "inmo_tour_transition"]`) + `typography: "Playfair Display"` + `subtitle_style: "kinetic_blur"`.
   - **E-Commerce / UGC Product:** `render_hybrid_reel` (`ai_styles: ["ugc_stock", "cinematic_macro"]`) or `create_faceless_ad` + `typography: "Poppins"` + `subtitle_style: "kinetic_dinamic"`.
   - **Tech / AI / SaaS:** `render_viral_beat` or `render_hybrid_reel` + `ai_styles: ["ui_interface_dark", "cyber_blueprint"]` + `typography: "Space Grotesk"` + `subtitle_style: "kinetic_dinamic"` or `"glow_neon_cyber"`.
   - **Fitness / Coaching Talking Head (0 AI Credits):** `render_fitness_talking_head` + `typography: "Bebas Neue"` + `subtitle_style: "boxed_highlighter"`.

## IMPORTANT CONNECTION RULES FOR AI AGENTS (CLAUDE, CURSOR, WINDSURF, ANTIGRAVITY)

1. **DO NOT run `npx @odinxd/mcp-server` unless configured locally** — OdinxD's primary MCP server is hosted directly over HTTPS at `https://odinxd.com/api/mcp` using MCP Streamable HTTP (`2025-03-26` / `2024-11-05`).
2. **Authentication & Plan Requirement**: Every MCP and REST v1 request (except `GET /api/v1/catalog`) requires an active **Starter** or **Pro** subscription and a personal API key starting with `odx_live_` generated at `https://odinxd.com/dashboard?section=mcp`, sent via header:
   `Authorization: Bearer odx_live_YOUR_API_KEY`

## How to Connect OdinxD MCP

### 1. Claude Code (CLI / Terminal)
```bash
claude mcp add --transport http odinxd https://odinxd.com/api/mcp --header "Authorization: Bearer odx_live_YOUR_API_KEY"
```

### 2. Claude Desktop (`claude_desktop_config.json`) — Remote Mode (URLs & Faceless Ads)
```json
{
  "mcpServers": {
    "odinxd": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://odinxd.com/api/mcp",
        "--header",
        "Authorization: Bearer odx_live_YOUR_API_KEY"
      ]
    }
  }
}
```

### 3. Cursor / Antigravity / Windsurf (`mcp.json`) — Native Streamable HTTP
```json
{
  "mcpServers": {
    "odinxd": {
      "url": "https://odinxd.com/api/mcp",
      "headers": {
        "Authorization": "Bearer odx_live_YOUR_API_KEY"
      }
    }
  }
}
```

### 4. Local PC File Upload Bridge (Upload `.mp4`, `.mov`, `.jpg`, `.png`, `.webp` from Local Disk)
Run directly from our official GitHub repository (`https://github.com/odinxd-ai/OdinMCP`) with zero manual file downloads:

**Claude Code CLI (Local Bridge):**
```bash
claude mcp add odinxd -e ODINXD_API_KEY=odx_live_YOUR_API_KEY -- npx --allow-git=all -y github:odinxd-ai/OdinMCP
```

**Claude Desktop / Cursor / Antigravity / Windsurf (`mcp.json` via GitHub `npx`):**
```json
{
  "mcpServers": {
    "odinxd": {
      "command": "npx",
      "args": ["--allow-git=all", "-y", "github:odinxd-ai/OdinMCP"],
      "env": {
        "ODINXD_API_KEY": "odx_live_YOUR_API_KEY"
      }
    }
  }
}
```

**Alternative (`git clone https://github.com/odinxd-ai/OdinMCP.git` or direct `https://odinxd.com/mcp/odinxd-mcp.mjs`):**
```json
{
  "mcpServers": {
    "odinxd": {
      "command": "node",
      "args": ["/absolute/path/to/OdinMCP/bin/odinxd-mcp.mjs"],
      "env": {
        "ODINXD_API_KEY": "odx_live_YOUR_API_KEY"
      }
    }
  }
}
```

## Available MCP Tools (20 Total: 12 Cloud + 1 Local Downloader + 7 Local Studio Tools)

1. `get_account_quota`: Returns user's plan (`starter`, `pro`, or pay-as-you-go), `rendersRemaining`, `aiCreditsRemaining`, and unlocked component packs.
2. `get_odinxd_catalog`: Returns Omni 1.2 Flash voices (`omni_voices`), the 20 AI B-Roll styles, 13 real estate room types, 15 curated fonts, 12 subtitle styles, Motion Graphics components, 24 neural TTS voices, and 20 BPM music tracks.
3. `generate_ai_image` (`1` AI credit/image • **`0` renders deducted**): Generates or composites `1..4` images via `gemini-2.5-flash-image` (`ugc_avatar_with_product` across all 4 avatar/product combinations, `character_casting` for microdramas, or `cinematic_keyframe`). Zero OdinxD text LLM usage—the agent writes all prompts.
4. `generate_ai_video_clip` (`1` AI credit/s without refs • `2` AI credits/s with refs • **`0` renders deducted**): Generates a `3s–15s` native `gemini-omni-1.2-flash` video clip with Lip-Sync speech (`Aoede`, `Zephyr`, `Kore`, `Leda`, `Vindemiatrix`, `Puck`, `Fenrir`, `Charon`, `Orus`, `Achird` in EN; `es_mx_*`, `es_es_*`, `es_co_*`, `es_ar_*` in ES) or cinema foley.
5. `generate_ai_video_batch` (`1` AI credit/s without refs • `2` AI credits/s with refs • **`0` renders deducted**): Generates `1..10` clips in parallel in one job (e.g., 10×15s UGC ad hooks, 3–4 multi-take clips for a 45s UGC ad, or a full Microdrama/Faceless episode) with automatic per-item credit refund on failure.
6. `create_faceless_ad`: End-to-end 9:16 Faceless AI Ad from text (`commercial_narrated`, `asmr`, `dynamic_beat`, `historical_doc`), 15–60s, ES/EN script generation, neural TTS voiceover, AI visual storyboard, and cloud render.
7. `render_hybrid_reel`: Edits **ONE single clean talking-head A-Roll video (`video_url`)** with 0–6 AI B-Roll clips across 20 AI styles (including Real Estate & UGC).
8. `render_viral_beat`: ViralBeat 2.0 fast-paced rhythmic edit over **ONE single clean A-Roll video (`video_url`)** with zoom punches, dynamic split-screens, SFX, and optional AI B-Roll.
9. `render_motion_stock`: Pure Remotion Motion Graphics over **ONE single clean A-Roll video** (`0` AI credits consumed; uses 1 render).
10. `render_maxy_overlay`: 3D stacked typography + animated overlays over **ONE single clean A-Roll video** (`0` AI credits consumed; uses 1 render).
11. `render_fitness_talking_head`: High-retention talking-head cut over **ONE single clean A-Roll video** with bold kinetic subtitles (`0` AI credits consumed; uses 1 render).
12. `get_render_status`: Polls job progress (`pending`, `rendering`, `done`, `failed`), percentage, multi-item `assetRef`/`downloadUrl`, and recovery hints.
13. `wait_for_render` (Local Bridge): Waits until job completion and downloads finished HD MP4/PNG outputs directly to disk.
14. `local_preprod_doctor` (Local Bridge • 0 credits): Verifies FFmpeg & Python and auto-provisions `~/.odinxd/preprod_env` (`faster-whisper`, `yt-dlp`, OpenCV, `PySceneDetect`, `edge-tts`).
15. `transcribe_local_media` (Local Bridge • 0 credits): Word-timestamped local Whisper transcription + acoustic silence map across 1..N raw takes.
16. `clean_and_merge_aroll` (Local Bridge • 0 credits): Cuts dead silences and spoken mistakes across 1..N raw takes and exports **ONE clean 1080x1920 MP4**.
17. `extract_podcast_clips` (Local Bridge • 0 credits): Analyzes long podcasts (`yt-dlp` + Whisper) and extracts `9:16` viral clips with stabilized OpenCV face-centering.
18. `manage_local_stock_bank` (Local Bridge • 0 credits): Slices personal user footage into reusable `3–5s` `9:16` B-Roll clips in `~/.odinxd/stock_bank`.
19. `generate_local_voiceover` (Local Bridge • 0 credits): Synthesizes free neural `.mp3` voiceovers + synchronized `.srt` captions locally via `edge-tts`.
20. `assemble_local_timeline` (Local Bridge • 0 credits): Stitches multi-take AI UGC ads (`30s–60s+`), Cinematic Faceless commercials, or Microdrama episodes locally at `1080x1920` / `1920x1080 @ 30fps` (`-16 LUFS` + optional local Whisper/SRT captions).

## REST API v1 Endpoints (`https://odinxd.com/api/v1`)

- `GET /api/v1/me` — Authenticated quota & plan summary.
- `GET /api/v1/catalog?section=all` — Complete Omni voices, styles, rooms, TTS voices, fonts, subtitles, and music catalog.
- `POST /api/v1/upload` — `multipart/form-data` media uploader (up to 500 MB; returns `files[].path` for job payloads).
- `POST /api/v1/ai/image` — Atomic AI Image / UGC Avatar+Product / Casting generation (`1` AI credit/image, `0` renders deducted).
- `POST /api/v1/ai/video` — Atomic single or parallel batch (`1..10` clips, `3s..15s`) Omni 1.2 Flash AI Video + Lip-Sync generation (`1` credit/s no refs, `2` credits/s with refs, `0` renders deducted).
- `GET /api/v1/ai/jobs/{jobId}` — Real-time status, `items[].assetRef` & `items[].downloadUrl` for generative AI media jobs.
- `POST /api/v1/jobs` — JSON body `{ "tool": "<tool_name>", "arguments": { ... } }` -> returns `201 Created` with `jobId`.
- `GET /api/v1/jobs/{jobId}` — Real-time job progress and HD MP4 `downloadUrl`.