# 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](/content/dashboard/api-keys/index.html) [View Pricing](/content/pricing/index.html)

## Authentication

All API requests require an API key sent via the `Authorization` header. Create keys in your [dashboard](/content/dashboard/api-keys/index.html).

```
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 a`429`status 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" }
```