v1REST API

Developer API

Generate mascots, create animations, and manage your assets programmatically. Everything you can do in the dashboard, you can do via the API.

Get Your API Key View Pricing

Authentication

All API requests require an API key sent via the Authorization header. Create keys in your dashboard.

Authorization: Bearer mv_live_your_api_key_here

The base URL for all endpoints is https://mascotvibe.com/api/v1

Generate Mascots

POST/api/v1/generate

Generate a set of mascot variations using AI. Costs 5 credits per generation (produces 4 variations).

Request Body

{
  "description": "A friendly mascot for a developer tools company",
  "style": "cartoon",          // kawaii | cartoon | 3d | flat | pixel | hand-drawn
  "websiteUrl": "https://example.com"  // optional, for brand context
}

Response

{
  "mascots": [
    {
      "id": "uuid-here",
      "name": "Pixel",
      "imageUrl": "https://storage.example.com/mascot.png",
      "style": "cartoon"
    }
  ]
}

Example

curl -X POST https://mascotvibe.com/api/v1/generate \
  -H "Authorization: Bearer mv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A friendly robot for a dev tools startup",
    "style": "cartoon"
  }'

Generation can take 15-30 seconds. The response includes up to 4 mascot variations.

Animate

POST/api/v1/animate

Start an animation job for a mascot. Costs 20 credits for 5s, 40 credits for 10s.

Request Body

{
  "mascotId": "uuid-of-your-mascot",
  "animationType": "wave",     // wave | celebrate | idle | think | dance | etc.
  "duration": 5,               // 5 or 10 (seconds)
  "size": 512                  // 128 | 256 | 512 | 720
}

Response

{
  "animationId": "uuid-here",
  "status": "processing"
}

Example

curl -X POST https://mascotvibe.com/api/v1/animate \
  -H "Authorization: Bearer mv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mascotId": "your-mascot-id",
    "animationType": "wave",
    "duration": 5,
    "size": 512
  }'

Animation types: wave, celebrate, idle, think, sad, dance, sleep, angry, nod, jump, spin, peek, custom. Custom requires a customPrompt field.

Animation Status

GET/api/v1/animations/:id

Check the status of an animation job and get download URLs when complete.

Response

{
  "id": "uuid-here",
  "status": "done",            // queued | processing | done | failed
  "animationType": "wave",
  "duration": 5,
  "size": 512,
  "webmUrl": "https://...",    // null until done
  "mp4Url": "https://...",
  "apngUrl": "https://...",
  "movUrl": "https://...",
  "spritesheetUrl": "https://...",
  "createdAt": "2026-03-11T12:00:00Z",
  "completedAt": "2026-03-11T12:02:00Z"
}

Example

curl https://mascotvibe.com/api/v1/animations/your-animation-id \
  -H "Authorization: Bearer mv_live_your_key"

Poll this endpoint to check when your animation is ready. Typical processing time is 5–8 minutes.

List Mascots

GET/api/v1/mascots

List your mascots with pagination. Supports limit and offset query params.

Response

{
  "mascots": [
    {
      "id": "uuid-here",
      "name": "Pixel",
      "description": "A friendly robot mascot",
      "style": "cartoon",
      "imageUrl": "https://...",
      "sourceType": "generated",
      "createdAt": "2026-03-11T12:00:00Z"
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

Example

curl "https://mascotvibe.com/api/v1/mascots?limit=10&offset=0" \
  -H "Authorization: Bearer mv_live_your_key"

Check Credits

GET/api/v1/credits

Check your current credit balance.

Response

{
  "credits": 450
}

Example

curl https://mascotvibe.com/api/v1/credits \
  -H "Authorization: Bearer mv_live_your_key"

Rate Limits

requests / minute

API keys / account

100

max mascots / request

Rate limits are applied per API key. When you exceed the limit, the API returns a429status code. Wait and retry after a short delay.

Error Codes

Code	Meaning
`400`	Bad request. Check the request body for missing or invalid fields.
`401`	Unauthorized. API key is missing, invalid, or deactivated.
`402`	Insufficient credits. Purchase more at /pricing.
`404`	Resource not found. The mascot or animation ID does not exist.
`429`	Rate limit exceeded. Wait and retry.
`500`	Internal server error. Try again or contact support.
`503`	Service unavailable. The generation service is temporarily down.

All error responses return JSON with an error field:

{ "error": "Insufficient credits" }