Create a mascot from an image

Upload your existing mascot design; the API detects the character's name and description from it.

Upload Your Image#

Upload multipart form data or a URL. Multipart needs a binary file field; let your HTTP client set the boundary, since a malformed body or missing file returns 400.

Multipart Upload#

curl -X POST https://api.masko.ai/v1/upload \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -F "file=@mascot.png"

URL Upload#

Public HTTP(S) PNG, JPEG, WebP, GIF or SVG (converted to PNG), up to 10 MB, downloaded within 15 seconds. Every redirect must stay public; private addresses and URLs with credentials are rejected. Reference image URLs follow the same rules.

curl -X POST https://api.masko.ai/v1/upload \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/my-mascot.png" }'

Create Mascot#

Pass the upload's asset_id as a reference. prompt and name are optional: both are detected from the image.

curl -X POST https://api.masko.ai/v1/mascots \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_ID",
    "reference_asset_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

How Auto-Analysis Works#

AI vision reads the reference and writes the character's name and a detailed prompt of its visual traits, for free.

Adding More References#

Up to 6 references; more give better consistency. Send an asset_id, or a url for a public image.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/references \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Changing references clears the style card, which is extracted again on the next generation.

Best Practices#

• 3 or 4 references from different angles.
• One art style; do not mix 3D and flat vector.
• 1024 × 1024 or larger.
• White or transparent backgrounds.

Animate the uploaded image directly#

For a new mascot, upload and animate creates it in the animation request. For an existing mascot, send the unattached upload to /generate:

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Idempotency-Key: animate-my-upload-001" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Gentle wave",
    "source_image_asset_id": "UPLOADED_IMAGE_ASSET_ID",
    "animation_prompt": "Wave gently, keeping the feet planted.",
    "animation_model": "standard",
    "duration": 5,
    "loop": true
  }'

It returns 202 with a job to poll at /v1/jobs/{job_id}?api_version=2026-09-26: 10 credits for 5 seconds of Standard, with no image charge.

• The upload is kept; non-square images are center-cropped to a separate 1024 × 1024 source, or use source_image_crop (image framing). The video model can still change details.
• It is imported as a source image, not a reference, and does not change the mascot's identity.
• An approved variant_id ties a fresh upload to that variant. Existing images keep their saved context, and a conflicting variant returns 409.
• Retry an uncertain response with the same idempotency key and request to avoid a second charge.