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

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

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

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

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

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

Rate Limits

60

requests / minute

5

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

All error responses return JSON with an error field:

{ "error": "Insufficient credits" }