---
title: "Create a mascot (collection)"
method: POST
path: "/v1/collections"
tags: ["Collections"]
deprecated: true
---

# Create a mascot (collection)

`POST /v1/collections`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/collections`
- Auth: HTTP bearer

> **Deprecated.**

This is the primary way to create a mascot. In the API the resource is called `collection` - today one collection holds one mascot so the terms are interchangeable. Recommended input is reference images (`reference_image_urls` or `reference_asset_ids` from POST /v1/upload) - one or more images of the character. The references ARE the mascot; you do not need to describe it in `prompt`. Use `context` to add things the image cannot express: personality, consistency rules ("always wears red sneakers"), forbidden variants ("never without the hat"), brand tone. The collection is assigned to a project and gets a public CDN slug. Creation with existing references or name/context only is free. Providing prompt without references generates one reference for 1 credit. Failed generation, storage or persistence triggers a refund, with background retries if immediate repayment fails. Use Idempotency-Key to replay a request without generating or charging again. Future /generate calls use the style automatically extracted from the references.

## Headers

- `Idempotency-Key` string

## Request body

- CreateCollectionBody
  - `project_id` string, uuid, required: Project to create the collection in. List projects via GET /v1/projects.
  - `name` string: Display name. Defaults to a generated name if omitted.
  - `prompt` string: Optional - do not set this if your references already show the mascot clearly. The reference images ARE the character. Only use prompt when you cannot provide references (pure text-to-mascot). When references are present, a prompt is auto-extracted from them. Without references, prompt generates one reference for 1 credit; a failed creation is refunded.
  - `context` string: Extra hints the image alone cannot convey: personality and behavior ("curious, cautious, never aggressive"), consistency rules ("always has a small white star on left ear"), forbidden variants ("never show without the hat"), brand tone. Not a character description - the references cover that.
  - `type` string: Collection type. Defaults to "mascot".
  - `style` string: Style ID or name. List styles via GET /v1/styles.
  - `design_touches` string[]: Optional design ideas for text-to-mascot creation, the same touches as the Studio creator. Requires prompt and no references. Each touch is added to the generated reference and applied only where it fits the character; the prompt wins where they differ. Pick at most one eyes-* and one mood-* value. Shape: proportions, simple, asymmetry, grounded, few-colors. Face: no-mouth, looks-at-you, blush, eyes-big, eyes-dots. Character: signature, weird, twist, grown-up-flaw, magic-part, mood-cozy, mood-mischievous, mood-melancholy, mood-bold, mood-mysterious, mood-chaotic, mood-serene.
  - `reference_image_urls` string[]: Recommended entry point. Public image URLs of the mascot - at least one, up to 6. Each public HTTP(S) URL is downloaded with a 10 MB limit and a 15-second deadline; private addresses and unsafe redirects are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. Each is stored as an asset. The first reference acts as the canonical look; additional ones widen angle/pose coverage. If you also pass reference_asset_ids, totals combine up to 6.
  - `reference_asset_ids` string[]: Existing asset IDs (from POST /v1/upload or another collection) to link as references. Assets are not duplicated. Use this when you already uploaded the image via /v1/upload. Max 6 references combined with reference_image_urls.
  - `settings` object: Collection settings. cdn_enabled: whether new assets auto-publish to the CDN. animation_sizes: pixel sizes to auto-generate variants for, e.g. [480, 360]. Recommended values: 720, 480, 360, 240. Full supported range: 32 to 1920.
    - `cdn_enabled` boolean
    - `animation_sizes` number[]

## Response `201`

Created collection

- CollectionResponse
  - `data` Collection, required
    - `object` 'mascot': Resource type. Always "mascot".
    - `id` string, uuid, required
    - `name` string, required
    - `type` string, required
    - `project_id` string, uuid
    - `config` object
      - `prompt` string, required
      - `reference_asset_ids` string[], required
      - `style_card` object, nullable, required
      - `caution_list` string[], required
    - `is_published` boolean
    - `slug` string, nullable
    - `user_prefix` string, nullable
    - `cdn_status` object[]
      - `asset_id` string, uuid, required
      - `item_name` string, nullable, required
      - `type` string, required
      - `cdn_url` string, uri, required
      - `status` string, required
      - `file_size` number, nullable, required
    - `created_at` string, required
    - `updated_at` string, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict

---

[API](https://skmtc.dev/masko/apis/masko-api.md) · [All operations](https://skmtc.dev/masko/apis/masko-api/llms.txt) · [OpenAPI document](https://skmtc.dev/masko/apis/masko-api/revisions/91eb3006a92f?raw)