Skip to content
maskostudioDocs

All pages

  • Overview/docs/use-cases
  • Mobile app/docs/use-cases#mobile
  • Website/docs/use-cases#website
  • Desktop/docs/use-cases#desktop
  • AI agents/docs/use-cases#agents
  • Videos/docs/use-cases#videos
  • Brand/docs/use-cases#brand
  • Start building/docs/ai-agents
  • Set up once/docs/ai-agents#set-up-once
  • Ask in plain words/docs/ai-agents#ask-in-plain-words
  • What your agent does/docs/ai-agents#what-your-agent-does
  • MCP server/docs/mcp
  • Masko for Cursor/docs/ai-tools/cursor
  • Masko in ChatGPT/docs/ai-tools/chatgpt
  • Masko in Lovable/docs/ai-tools/lovable
  • Masko in Devin/docs/ai-tools/devin
  • Masko in n8n/docs/ai-tools/n8n
  • Masko in Hermes Agent/docs/ai-tools/hermes
  • Masko in OpenClaw/docs/ai-tools/openclaw
  • Start here/docs/tutorials#start-here
  • All tutorials/docs/tutorials
  • Create your first mascot/docs/tutorials/first-mascot
  • Create an animated character/docs/tutorials/first-animation
  • Make a character talk/docs/tutorials/make-it-talk
  • Put your mascot on your website/docs/tutorials/mascot-on-your-website
  • Guide onboarding with a talking mascot/docs/tutorials/web-onboarding-mascot
  • Add a mascot that celebrates progress and welcomes users back/docs/tutorials/web-progress-companion
  • Add a talking support mascot in the bottom right/docs/tutorials/web-support-mascot
  • Show a mascot while your AI thinks/docs/tutorials/ai-loading-mascot
  • Give your AI agent a face/docs/tutorials/ai-agent-face
  • Animate the mascot you already have/docs/tutorials/animate-your-mascot
  • How to make Telegram stickers/docs/tutorials/telegram-stickers
  • How to make Discord stickers/docs/tutorials/discord-stickers
  • Quickstart: your first animation/docs/quickstart
  • Terminal quickstart/docs/terminal
  • API keys and workspaces/docs/authentication
  • CLI browser login/docs/authentication/cli
  • How mascots work/docs/how-mascots-work
  • Credits and costs/docs/credits
  • From text/docs/create/from-text
  • From an image/docs/create/from-image
  • From a website/docs/create/from-website
  • From a brand book/docs/create/from-brand-book
  • Reference images/docs/manage/references
  • Props/docs/manage/props
  • What you can generate/docs/generation
  • Pose-to-animation walkthrough/docs/generate/workflow
  • Images and poses/docs/generate/images
  • Animations/docs/generate/animations
  • Talking animations/docs/generate/talking
  • Sounds/docs/generate/sounds
  • Animation presets/docs/generate/presets
  • Write good requests/docs/generate/requests
  • Logos, backgrounds and stickers/docs/generate/design-assets
  • Cursor follower/docs/generate/cursor-follower
  • Batch generation/docs/generate/batch
  • Image and video exports/docs/manage/media-exports
  • Canvases and releases/docs/canvas
  • Build a canvas/docs/canvas/build
  • Canvas templates/docs/canvas/templates
  • Generate canvas assets/docs/canvas/generate-all
  • Export a canvas/docs/canvas/export
  • Overview and demo/docs/player
  • Play one animation/docs/player/one-animation
  • Play a canvas/docs/player/canvas
  • Ship in an app with an app key/docs/player/app-keys
  • Play on an ESP32 board/docs/player/esp32
  • Hosting and file formats/docs/generate/cdn
  • File sizes/docs/generate/file-sizes
  • Float a mascot on your Mac/docs/integrations/desktop
  • Jobs and polling/docs/manage/jobs
  • Webhooks/docs/manage/webhooks
  • Manage mascots and assets/docs/manage/collections
  • All endpoints/docs/reference
  • Requests and responses/docs/reference/conventions
  • Errors and recovery/docs/reference/errors
  • Command line reference/docs/terminal/commands
  • TypeScript SDK/docs/sdk/typescript
  • Changelog/docs/reference/changelog
  • Migrate to mascots and canvases/docs/manage/studio-migration
Get an API key
Documentation

Jobs and polling

Every generation creates a job. Poll it, long-poll until it finishes, or get notified with webhooks.

generation_context, input_data and output_data are receipts saved when the job ran, and keep their original field names. The context the job ran with is the top-level generation_context; input_data holds the other inputs.

Job lifecycle

A job is pending when accepted and processing once a worker picks it up, then ends completed with asset URLs or failed with an error.

pending  -->  processing  -->  completed
                           \-->  failed

List jobs

# List all jobs
curl https://api.masko.ai/v1/jobs \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Filter by status and mascot
curl "https://api.masko.ai/v1/jobs?status=completed&mascot_id=MASCOT_ID" \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Filter by type
curl "https://api.masko.ai/v1/jobs?type=animation" \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

Filters: status (pending, processing, completed or failed; any other value answers 400), mascot_id, and type (item_generation, image_generation, logo, animation, reverse, size_variant, size_variant_batch, export_animation, background_generation). Variant filters are in trace the variant used.

Add top_level=true to leave out jobs that another job started: the clips of a canvas generation and the files of a batch export. Standalone exports stay. Each row also has parent_job_id (the job that started it, or null), canvas_id, item_name (the pose or animation it made, or null), and credits_refunded when credits came back.

Get job detail

Completed jobs list their files in urls: the CDN link of each hosted file, and a signed link that expires within hours for the others. Under the same key as each link, file_sizes gives the file's size in bytes (null when the file cannot be read) and asset_ids gives its asset ID, to use with the asset endpoints such as media exports. A key is the file type, such as webm, or the type and width for a size variant, such as webm_360. A talking animation also lists its stacked_video and stacked_video_av1 files. A logo lists its master as image, its transparent copy as transparent_image, and each export under its own name, such as png_1024, ios_180 or favicon_ico.

A failed job gives error, a message to show, and error_code, a stable category: copyright_blocked, safety_blocked and image_empty need a different request or picture, while provider_busy, provider_unavailable, timeout, animation_failed, source_unavailable, authentication_error and unknown are failures on Masko's side, not in the request, so trying the same request again usually works. A failed job can still list files it finished, such as the picture of an animation whose video failed. A failed animation of an existing pose lists no picture: the pose is its input, not its work.

credits_refunded gives the credits that came back for work the job did not deliver; cost_credits stays what was charged. It is absent when nothing was refunded.

A canvas_orchestration job completes even when clips fail. Its progress gives total, failed and dispatched clip counts once the run ends (null before), and release tells whether the canvas was released, when the run was asked to release it.

curl https://api.masko.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Completed job response:
# {
#   "data": {
#     "id": "0818df65-d092-5901-a506-3b2e64fb88ef",
#     "status": "completed",
#     "type": "item_generation",
#     "mascot_id": "c244e7b1-5655-5540-89a8-516b09bd4985",
#     "cost_credits": 21,
#     "created_at": "2026-03-28T10:00:00Z",
#     "updated_at": "2026-03-28T10:01:32Z",
#     "item_id": "e1a868c7-82b1-5d17-947b-ab4eeebd6fc3",
#     "item_name": "Wave",
#     "urls": {
#       "image": "https://assets.masko.ai/c244e7b1-5655-5540-89a8-516b09bd4985/image.png",
#       "webm": "https://assets.masko.ai/c244e7b1-5655-5540-89a8-516b09bd4985/video.webm"
#     },
#     "file_sizes": {
#       "image": 412833,
#       "webm": 1370412
#     },
#     "asset_ids": {
#       "image": "3c8ce568-35ce-59c2-b3f8-9fb7e4a16e52",
#       "webm": "3db2d3be-a85a-5e9e-85fc-02100b19d8cb"
#     }
#   }
# }

# Failed job response:
# {
#   "data": {
#     "id": "5b1f0c2e-7d4a-4f8b-9c3e-2a6d8e1f4b70",
#     "status": "failed",
#     "type": "item_generation",
#     "mascot_id": "c244e7b1-5655-5540-89a8-516b09bd4985",
#     "cost_credits": 12,
#     "error": "AI service is temporarily unavailable. Please try again in a few minutes. Your credits were refunded.",
#     "error_code": "provider_unavailable",
#     "credits_refunded": 12
#   }
# }

Long polling

Add ?wait=true to hold the request open until the job finishes or timeout (default 120 seconds) passes. A timeout returns the current status and does not cancel the job.

# Wait up to 120 seconds for the job to complete
curl "https://api.masko.ai/v1/jobs/JOB_ID?wait=true&timeout=120" \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Returns immediately if already completed.
# Returns the job object when it completes.
# Returns with current status if timeout is reached.

When to poll and when to use webhooks

  • Long-polling: simplest, for scripts, CLI tools and prototypes.
  • Webhooks: for production. Your server is notified, with no open connections.
  • Both: webhooks for background work, long-polling where a user waits for the result.

Media readiness

A job and its derived formats can finish at different times, and a returned CDN URL may still serve a placeholder. Check the required asset type and size_variants before playback. For a canvas use status.media.preview.ready; for a developer run, wait for its runtime readiness and version reference.

Trace the variant used

GET /v1/jobs/{id} returns variant_id and, when recorded, generation_context: the frozen context the job used (variant ID and name, engine hash, mascot prompt and style, resolved reference asset IDs and asset inputs). It never reflects the currently active variant, and internal execution details are never returned. Original-context jobs, cross-variant transitions and older untagged jobs have a null variant_id.

  • GET /v1/jobs?mascot_id=MASCOT_UUID&variant_id=VARIANT_UUID lists work for one variant. Generated assets keep their job_id, so you can trace them back.
  • from_variant_id and to_variant_id filter transitions by role and accept named variant UUIDs. Original endpoints have null IDs, so find them by inspecting the mascot's jobs.
GET /v1/jobs?mascot_id=MASCOT_UUID&to_variant_id=VARIANT_UUID

For transitions, generation_context.transition.before and .after each record asset_id, collection_id, variant_id, variant_name, context_source and the saved generation context. A reverse job swaps the roles without a new writer receipt. Older jobs without a recorded transition are not backfilled.

A video edit creates a video_edit job. For a transition edit, it keeps transition.before and .after and adds generation_context.transition_edit with the source video ID and requested edit. Repeated edits keep the endpoint identities.

Cursor followers create interactive_generation jobs; get their nine image URLs from GET /v1/mascots/{id}/cdn-export.