Skip to content
Masko logomasko
Docs
QuickstartAPI reference
Documentation

Logos, scenes and stickers

Use the same mascot to generate assets for your product. These requests spend generation credits. Logo and scene generation return asynchronous jobs; sticker generation can return an already completed result.

A logo generation costs 5 credits. Choose the description and style for this request:

Use logo_description for composition and identifying features, such as a face portrait with asymmetrical ears or a compact silhouette with a distinctive tail. Use logo_style_instruction for the visual treatment, such as flat colors, monochrome negative space, or bold outlines. The mascot's reference images supply the character identity. Keep these two choices separate so you can try a new treatment without changing the composition.

The mascot supplies recognizable cues, while your composition and style control how freely they are reinterpreted. You can request a flat symbol, detailed emblem, outline or soft icon, including a deliberate crop or background. For a filled icon, name the background color and ask it to fill the canvas; the master retains that background. A separate transparent version reuses valid native alpha or removes the background when needed. Resized PNGs and the favicon use this validated transparent version. Background removal can also remove colored backing shapes; use the master when you want to retain a filled icon or badge. Review the result for likeness and readability at small sizes. Output is raster artwork, not editable vector paths.

curl https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "logo",
    "name": "App icon",
    "logo_description": "A face-only icon of the character",
    "logo_style_name": "Flat",
    "logo_style_instruction": "Solid colors, simple silhouette, no gradients"
  }'

Scene

A scene costs 3 credits. Describe the environment and the character’s action separately:

curl https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "scene",
    "name": "Reading corner",
    "scene": "A cozy library in warm afternoon light",
    "action": "Reading a book in an armchair",
    "aspect_ratio": "4:3",
    "position": "center"
  }'

Supported aspect ratios are 4:3, 1:1, 21:9, 4:5, 3:4, and 9:16. To create a new scene using a particular character image, add source_asset_id alongside scene and action. To edit an existing scene, use type: "scene" with source_image_asset_id and edit_instructions. The two source fields are mutually exclusive.

Set variant_id to generate a logo or scene for a named variant. A scene's explicit reference image supplies its saved character context when no variant is selected. A conflicting named variant returns 409 before charging, unless that image is intentionally included in the selected variant's references. Reusing a reference does not change its original generation history.

Sticker

POST /v1/assets/:id/sticker turns an existing image asset into a transparent PNG sticker with a white border. Transparency is generated directly, with no separate background-removal step. It costs 1 credit and requires a completed image attached to a mascot. A completed response uses HTTP 201; inspect data.status and the returned asset. The same creation endpoint accepts a completed animation with background removal: it creates one animated sticker and prepares all four chat platform versions for zero generation credits. Poll the returned sticker asset through GET /v1/assets/{sticker_id}/sticker. See animated sticker creation for platform downloads and public hosting. Read the endpoint reference for accepted source requirements.

Collect the result

Save data.job_id, check job progress, and retrieve the completed assets. Prefer returned URLs over constructing paths. See hosting and formats for published URLs and signed links.

Follow cursor interactions

Create nine transparent gaze directions from a completed image for 9 credits. The source must be a transparent image or have a completed transparent derivative in the same mascot. Its mascot variant is preserved automatically. Optional name labels the interaction without renaming the image. It accepts up to 60 characters after trimming; omitted or blank names use the source image name. This is separate from Canvas state machines.

curl https://api.masko.ai/v1/mascots/MASCOT_ID/interactive \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"source_asset_id":"SOURCE_IMAGE_UUID","kind":"cursor-follower","name":"Website cursor follower"}'

The 202 response contains data.job_id, data.asset_id, data.asset_ids.interactive, data.variant_id, data.estimated_cost, and data.poll_url. Send the POST once and poll GET /v1/jobs/JOB_ID; repeated POST requests create new charged sets. Failed generation is refunded.

Once complete, GET /v1/mascots/MASCOT_ID/cdn-export includes the interaction's manifest_url and all nine named WebP URLs under frames when hosting is enabled. All links use https://assets.masko.ai. Originals and WebPs remain 1024 × 1024. Check the exported interaction by its id because a pose can have several interactions. The web app's interaction detail page provides the downloadable React/HTML package.

Logo presets and ideas

Use GET /v1/logo-styles to retrieve the same nine visual treatments as the dashboard, including preview images and full style instructions. These are separate from mascot styles at /v1/styles.

GET /v1/mascots/{id}/logos/suggestions returns five logo directions and three style suggestions. Directions include accessible options such as a face portrait and full body, alongside more abstract ideas. Each direction may have its own optional style. Custom styles include name and instruction; an exact built-in match also includes preset_id. Optional variant_id targets an approved character variant. refresh=true requests fresh ideas. Suggestions use no image credits.

Generate one logo for 5 credits:

{
  "type": "logo",
  "name": "Playful portrait",
  "logo_description": "An oversized face portrait with a natural tilt",
  "logo_style_id": "graphic-app-icon"
}

Send this to POST /v1/mascots/{id}/generate. The preset ID resolves to its full instructions, not just a label. Optional logo_style_name and logo_style_instruction override the corresponding preset fields. Existing custom-style requests remain supported. To generate several directions, use /generate-batch with one request per logo, each with its own style and cost.

For safe logo retries, create the item first and send its item_id with a UUID request_id. Reuse that ID and the unchanged body after a timeout or uncertain server response. The existing job is returned without another charge. A new ID means a new paid attempt; use one only after choosing to generate again.

After selecting a completed logo master image, call POST /v1/assets/{id}/svg with a UUID request_id. This costs 30 credits and creates a vector derivative of that exact source, attached to the same item. It also accepts completed images, transparent images, and stickers.

curl -X POST 'https://api.masko.ai/v1/assets/ASSET_ID/svg' \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"request_id":"bba386b8-c756-4f7c-89a2-132862188bf4"}'

The 202 response contains data.job_id, data.asset_ids.svg, data.estimated_cost, and data.poll_url. Poll the job until it completes; high-quality vector generation can take several minutes. Reuse the same request ID if submission is interrupted. A new ID starts another paid generation. A brief 409 while the first request is being prepared can be retried with that same ID. Failed generation refunds any charged credits.

Retrieve the result with GET /v1/assets/{svg_asset_id} using its signed file_url or published cdn_url. For hosted logo items, GET /v1/mascots/{id}/cdn-export includes the latest completed version as logos.svg. Image items expose svg directly. The original PNG and its exports remain unchanged.

SVG paths are editable in vector software and scale without pixelation. Fine details, texture, or facial features can vary from the source; review the result before using it as your final brand asset.