# Masko API

> AI mascot generation platform. Create animated characters, generate images and transparent videos, build interactive state machines, and publish to CDN - all via REST API.

## Quick Facts

- Base URL: https://api.masko.ai/v1
- Auth: Bearer token with `masko_` prefix
- 32 endpoints, 38 generation styles
- Image: 1 credit, Animation: 5 credits/sec, Logo: 5 credits
- OpenAPI spec: https://api.masko.ai/v1/openapi.json
- Full docs for LLMs: https://masko.ai/llms-full.txt
- MCP server: claude mcp add --transport http masko "https://masko.ai/api/mcp"
- CLI: npx @masko/cli

## Documentation

### Getting Started
- [Quickstart - Create a Mascot via API in 5 Minutes | Masko](https://masko.ai/docs/quickstart): Generate your first animated mascot with the Masko REST API. Create a collection, generate an animation, and get permanent CDN URLs in under 5 minutes. Free to start.
- [API Authentication - Keys, Rate Limits & Credits | Masko API](https://masko.ai/docs/authentication): Authenticate with Bearer tokens using masko_ API keys. Manage API key scopes, check credit balance, and handle authentication errors.
- [AI Agent Integration - MCP, CLI & Skills for AI Coding Tools](https://masko.ai/docs/ai-agents): Use Masko from any AI coding agent. MCP server for native tools, CLI for terminal, AI skills for built-in knowledge. Works with Claude Code, Cursor, VS Code, Windsurf, and more.
- [Masko MCP Server - Connect Claude Code, Cursor, VS Code, Windsurf & More](https://masko.ai/docs/ai-tools/mcp): Add the Masko MCP server to your AI coding tool in 30 seconds. Create mascots, generate animations, and get CDN URLs with native tool calls. Works with 11+ AI tools.
- [Masko CLI - Generate Mascots from the Command Line](https://masko.ai/docs/ai-tools/cli): Create mascots, generate animations, and get CDN URLs from the terminal. Works with any AI coding agent that runs bash commands. Install with npx.
- [Masko AI Skills - Custom Instructions for Claude Code, Cursor, Copilot, Gemini](https://masko.ai/docs/ai-tools/skills): Install Masko skills and rules for your AI coding tool. Gives your agent built-in knowledge of mascot generation workflows, commands, and best practices.

### Understanding Masko
- [How Mascots Work - Data Model & Asset Pipeline | Masko API](https://masko.ai/docs/how-mascots-work): Understand the Masko data model. Projects contain collections, collections contain items, items contain assets. Learn the generation graph and asset hierarchy.
- [API Credits & Pricing - Image, Animation & Logo Costs | Masko](https://masko.ai/docs/credits): Images cost 1 credit, animations 5 credits per second, logos 5 credits. Check your balance via API. 15 free credits on signup plus 11 from onboarding tasks.

### Create a Mascot
- [Create Mascot from Text Description - Style & Prompt API](https://masko.ai/docs/create/from-text): Describe your character in natural language, pick a style preset, and generate a mascot via API. 38 styles available including kawaii, pixel art, and cartoon.
- [Create Mascot from Image Upload - Reference Analysis API](https://masko.ai/docs/create/from-image): Upload your existing character design as a reference image. AI vision analyzes the image and extracts a prompt for consistent future generations. Up to 6 references.
- [Create Mascot from Website URL - Brand Analysis API | Masko](https://masko.ai/docs/create/from-website): Analyze any website URL to extract page metadata, brand context, and optional mascot suggestions that can seed a text-to-mascot flow.

### Generate Content
- [End-to-End Generation Flow | Masko API](https://masko.ai/docs/generate/workflow): Complete flow to animate a mascot via the Masko API. Create a collection, add reference images, generate a pose, animate it. REST and curl examples.
- [Generate Mascot Images & Transparent PNGs via API | Masko](https://masko.ai/docs/generate/images): Generate AI mascot images, edit existing poses, and get transparent PNGs via REST API. Style consistency across your collection. 1 credit per image.
- [Transparent Animation API - Generate WebM, HEVC & MP4 Video](https://masko.ai/docs/generate/animations): Generate transparent mascot animations via API. Get WebM, HEVC with alpha, and MP4 output. Auto-reverse transitions, size variants, and instant CDN URLs. 5 credits per second.
- [Batch Generate Mascot Assets - Multiple Items in One API Call](https://masko.ai/docs/generate/batch): Generate multiple mascot images and animations in a single request. AI-powered action suggestions for poses. Parallel processing with individual job tracking.
- [Instant CDN URLs for Generated Assets - Pre-Allocated Placeholders](https://masko.ai/docs/generate/cdn): Get permanent CDN URLs immediately when you trigger generation. Placeholder assets are served until the real file is ready. Supports size variants and custom slugs.

### Interactive Canvas
- [Masko Canvas - Build Interactive Mascot State Machines](https://masko.ai/docs/canvas/build): Create interactive canvases with nodes for poses, edges for transitions, conditions for logic, and resolved behavior inputs. Full graph replacement via PATCH endpoint.
- [Masko Canvas Templates - Prebuilt State Machine Presets](https://masko.ai/docs/canvas/templates): Apply built-in and compatibility templates to quickly scaffold a canvas. List, preview, and customize templates via API.
- [Masko Canvas Generate All - Batch Generate Canvas Assets](https://masko.ai/docs/canvas/generate-all): Generate pending node images and transition videos for a canvas with one API call. Includes explicit generated, skipped, reverse-free, and cost accounting.
- [Masko Canvas Export - MaskoAnimationConfig JSON Output](https://masko.ai/docs/canvas/export): Export a completed canvas as a MaskoAnimationConfig JSON object. Includes nodes, edges, asset URLs, and transition metadata for web and desktop rendering.

### Manage & Monitor
- [Masko Jobs & Polling - Track Generation Progress via API](https://masko.ai/docs/manage/jobs): Monitor generation jobs with polling or long-polling. List recent jobs, check individual status, and get asset URLs on completion. Supports webhooks as alternative.
- [Masko Webhooks - HMAC-Signed Job Notifications](https://masko.ai/docs/manage/webhooks): Receive real-time notifications when jobs complete or fail. HMAC-SHA256 signature verification, automatic retries with exponential backoff, and delivery management.
- [Masko API - List Projects, Collections, Items & Assets](https://masko.ai/docs/manage/collections): Browse and filter your mascot data via API. List projects, collections with pagination, items with assets, and CDN URLs. Supports search and status filtering.
- [Reference Images & Style Consistency | Masko API](https://masko.ai/docs/manage/references): Understand the three kinds of reference images in the Masko API. Collection references persist across generations. Preview hints are ephemeral. Source assets are what you animate.

### Reference
- [Unified Generation Endpoint - Images, Animations, Logos & Edits](https://masko.ai/docs/generation): One endpoint for all generation types. Create images, animations, transitions, edits, logos, and batch requests. Supports auto-reverse and CDN pre-allocation.
- [Masko Canvas API - Interactive Mascot State Machines](https://masko.ai/docs/canvas): Build interactive mascot experiences with the Canvas API. Define poses as nodes, transitions as edges, add resolved behavior conditions, then generate pending images and animations.
- [Masko API Error Codes - Troubleshooting & Recovery Guide](https://masko.ai/docs/reference/errors): Complete reference for API error codes. Covers 400, 401, 402, 403, 404, 409, 429, and 500 errors with explanations, common causes, and recovery strategies.
- [API Changelog - Version History and Updates](https://masko.ai/docs/reference/changelog): Every update to the Masko v1 API with release dates, breaking changes, new endpoints, and migration notes for each version.

## API Endpoint (for agents)

- [Query docs by topic](https://api.masko.ai/v1/docs): GET /api/v1/docs?q=animation - returns relevant doc section as plain text
- [OpenAPI spec](https://api.masko.ai/v1/openapi.json): Full OpenAPI 3.0 specification