Mascots

Create a mascot

This is the primary way to create a mascot. In the API the resource is called mascot - today one mascot 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 mascot 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.

post/v1/mascots

Request

  • Base URL: https://api.masko.ai
  • URL: https://api.masko.ai/v1/mascots
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Account-scoped key (1 to 255 characters, ideally a UUID). Retries must preserve the credential workspace, effective API version, URL, content type and exact body bytes, including multipart boundaries; different inputs return 409 idempotency_key_reused. Completed responses, including 500 errors, replay for 24 hours after completion with current resource access checked again. Running or unconfirmed executions return 409 idempotency_request_in_progress and do not expire automatically. A receipt persistence failure returns 503 idempotency_persistence_failed: retry only with the same key and inspect the operation outcome before starting a new request.

Request body

project_idstring uuid required

Project to create the mascot in. List projects via GET /v1/projects.

namestring

Display name. Defaults to a generated name if omitted.

promptstring

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.

contextstring

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.

typestring

Mascot type. Defaults to "mascot".

stylestring

Style ID or name. List styles via GET /v1/styles.

design_touchesstring[]

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_urlsstring[]

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_idsstring[]

Existing asset IDs (from POST /v1/upload or another mascot) 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.

Response

Created mascot

Changes

No recorded changes to this operation across all 1 revision of this API.