{"openapi":"3.0.3","info":{"title":"Masko API","version":"2026-09-26","description":"API for generating and managing AI mascots, animations, and logos. The current API version is the date in `info.version`; send it as the Masko-API-Version header, and every response echoes the version it used plus a Request-Id. JSON resource responses use {data, meta?} / {error: {code, message, param?, details?, doc_url, request_id}} envelopes. Standard authenticated resource POSTs accept Idempotency-Key for safe retries (auth and admin routes excluded), and lists return meta.pagination.next_cursor. Resources carry an object field naming their type; docs and OpenAPI are served directly and 204 responses have no body. Generation endpoints return 202 with endpoint-specific receipts: individual jobs use job_id and poll_url, developer orchestration uses run_id, and batch operations list their jobs. See each operation for its polling contract. Protected requests accept API keys or scoped CLI session access tokens."},"servers":[{"url":"https://api.masko.ai","description":"Production"},{"url":"http://localhost:3000/api","description":"Local development"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Items","description":"An item is a single pose or state of your mascot (e.g. \"waving\", \"sitting\"). Each item groups the assets generated for that pose: the image, its transparent variant, and any animations derived from it. Use these endpoints to list, rename, or archive poses. For raw file access (individual PNG/MP4/WebM), see Assets."},{"name":"Assets","description":"An asset is a single file: one PNG, one MP4, one WebM. Assets belong to an item (their pose) and a collection (their mascot). Use these endpoints when you need raw file metadata, signed URLs, or want to archive a specific file variant."},{"name":"Voice","description":"The voice a mascot speaks with in talking animations. Describe it, hear three samples for 1 credit, and keep one. A variant speaks with the Original's voice until it gets its own. Then pass speech to POST /v1/collections/{id}/generate."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key (masko_<key>) or short-lived CLI session access token (masko_at_<token>). Send as Bearer. Projects, mascots and their assets, independent canvases and jobs are scoped to the credential workspace. Cross-workspace resource IDs return 404; select another workspace with browser login or use a key issued for that workspace. Collection routes remain legacy aliases; the separate character registry is retired."},"ApplicationSecret":{"type":"http","scheme":"bearer","description":"Restricted masko_sk_ application secret. Backend only; reserved for authorized application integration."}},"schemas":{"CanvasGenerateAllResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanvasGenerateAllData"}},"required":["data"]},"CanvasGenerateAllData":{"type":"object","properties":{"plan_id":{"type":"string","description":"Stable identity of the exact graph, scope, prompts, and generation options. Return it as approved_plan_id when executing an approved dry-run plan."},"graph_content_hash":{"type":"string","description":"Canvas revision used by this plan. Return it as expected_graph_hash when executing an approved dry-run plan."},"dry_run":{"type":"boolean"},"can_dispatch":{"type":"boolean"},"targets":{"type":"string","enum":["all","images","stickers","animations"]},"duration":{"type":"number"},"include_stickers":{"type":"boolean"},"skip_completed":{"type":"boolean"},"selection":{"type":"object","properties":{"node_ids":{"type":"array","nullable":true,"items":{"type":"string"}},"edge_ids":{"type":"array","nullable":true,"items":{"type":"string"}}},"required":["node_ids","edge_ids"]},"jobs":{"type":"array","items":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"edge_id":{"type":"string"},"node_id":{"type":"string"},"type":{"type":"string","enum":["image","edit","sticker","loop","transition"]},"source":{"type":"string"},"target":{"type":"string"},"item_name":{"type":"string"},"cost":{"type":"number"},"urls":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"poll_url":{"type":"string","description":"Follow this link to poll the job. On /v1/canvases routes it selects the mascot contract, so the job reports mascot_id."}},"required":["job_id","type","cost"]}},"generated":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"planned_jobs":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"planned_job_count":{"type":"number"},"planned_nodes":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"planned_edges":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"planned_stickers":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"skipped":{"type":"number"},"skipped_items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["node","edge"]},"id":{"type":"string"},"reason":{"type":"string"},"asset_id":{"type":"string","nullable":true},"asset_status":{"type":"string"}},"required":["kind","id","reason"]}},"reverse_free":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["edge"]},"id":{"type":"string"},"reason":{"type":"string","enum":["reverse_edge_free"]},"reverse_of_edge_id":{"type":"string","nullable":true}},"required":["kind","id","reason","reverse_of_edge_id"]}},"already_complete":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["node","edge"]},"id":{"type":"string"},"asset_id":{"type":"string"}},"required":["kind","id","asset_id"]}},"estimated_cost":{"type":"number"},"actual_cost":{"type":"number"},"would_charge_credits":{"type":"number"},"refunded_credits":{"type":"number"},"total_jobs":{"type":"number"},"total_cost":{"type":"number"}},"required":["jobs","generated","skipped","skipped_items","reverse_free","already_complete","estimated_cost","actual_cost","total_jobs","total_cost"]},"MascotVariant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"approved_at":{"type":"string","nullable":true},"canvas_id":{"type":"string","nullable":true,"format":"uuid"},"reference_asset_id":{"type":"string","nullable":true,"format":"uuid"},"created_at":{"type":"string"}},"required":["id","name","description","approved_at","canvas_id","reference_asset_id","created_at"]},"CreateMascotVariantBody":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Client-generated UUID. Reuse it to safely retry creation."},"name":{"type":"string","minLength":1,"maxLength":80},"description":{"type":"string","minLength":1,"maxLength":3000,"description":"The desired change and generation guidance."},"source_variant_id":{"type":"string","format":"uuid","description":"Approved variant to start from. Omit for Original. Its references and context are frozen on creation."},"reference_asset_id":{"type":"string","format":"uuid","description":"Completed image in this collection, or your unassigned POST /v1/upload image. Creates an approved context immediately; no generation charge. Omit to create a draft for reference generation."}},"required":["id","name","description"],"additionalProperties":false},"MascotVariantDetail":{"type":"object","properties":{"variant":{"$ref":"#/components/schemas/MascotVariant"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/MascotVariantCandidate"}}},"required":["variant","candidates"]},"MascotVariantCandidate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","nullable":true,"format":"uuid"},"job_id":{"type":"string","nullable":true,"format":"uuid"},"created_at":{"type":"string"},"status":{"type":"string"},"error":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["id","asset_id","job_id","created_at","status","url"]},"GenerateVariantReferenceBody":{"type":"object","properties":{"operation_id":{"type":"string","format":"uuid","description":"Client-generated UUID. Reuse to retry the same candidate job without another charge."}},"required":["operation_id"],"additionalProperties":false},"ApproveMascotVariantBody":{"type":"object","properties":{"candidate_id":{"type":"string","format":"uuid","description":"Completed candidate from this variant to use as its reference."}},"required":["candidate_id"],"additionalProperties":false},"InteractionGenerationResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"asset_ids":{"type":"object","properties":{"interactive":{"type":"string","format":"uuid"}},"required":["interactive"]},"status":{"type":"string","enum":["pending"]},"estimated_cost":{"type":"number"},"variant_id":{"type":"string","nullable":true,"format":"uuid"},"poll_url":{"type":"string"}},"required":["job_id","asset_id","asset_ids","status","estimated_cost","variant_id","poll_url"]}},"required":["data"]},"CreateInteractionBody":{"type":"object","properties":{"source_asset_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["cursor-follower"]},"name":{"type":"string","maxLength":60,"description":"Interaction label. Omitted or blank names use the source image name without renaming the image."}},"required":["source_asset_id","kind"],"additionalProperties":false},"CreateAnimationResponse":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/GenerateAsyncData"},{"type":"object","properties":{"mascot_id":{"type":"string","format":"uuid"},"mascot_name":{"type":"string"},"mascot_created":{"type":"boolean"}},"required":["mascot_id","mascot_name","mascot_created"]}]}},"required":["data"]},"TalkingEstimate":{"type":"object","properties":{"speech_seconds":{"type":"number","description":"Estimated length of the spoken line."},"duration":{"type":"integer","description":"Most likely video length in seconds."},"max_duration":{"type":"integer","description":"The longest the video could need; the charge is based on it."},"credits":{"type":"integer","description":"Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded."},"too_long":{"type":"boolean"}},"required":["speech_seconds","duration","max_duration","credits","too_long"],"description":"Talking animations only."},"GenerateAsyncData":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"type":{"type":"string","enum":["image","animation","edit","logo","reverse"]},"item_id":{"type":"string","format":"uuid"},"item_name":{"type":"string"},"estimated_cost":{"type":"number"},"asset_ids":{"type":"object","additionalProperties":{"type":"string","format":"uuid"}},"urls":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"estimate":{"$ref":"#/components/schemas/TalkingEstimate"},"script":{"type":"string","description":"Talking animations only: the line with its movements, as performed."},"poll_url":{"type":"string"}},"required":["job_id","status","type","item_id","item_name","estimated_cost","poll_url"]},"CreateAnimationBody":{"type":"object","properties":{"source_image_asset_id":{"type":"string","format":"uuid","description":"Completed image to animate. For a new mascot, use an unattached image from POST /v1/upload."},"source_image_crop":{"type":"object","properties":{"x":{"type":"integer","minimum":0},"y":{"type":"integer","minimum":0},"width":{"type":"integer","minimum":0,"exclusiveMinimum":true},"height":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["x","y","width","height"],"description":"Square crop in pixels after EXIF orientation. Omit for a centered square crop. The original is preserved."},"mascot_id":{"type":"string","format":"uuid","description":"Save under this existing mascot. Reuse the ID returned by your first request."},"create_mascot":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":80,"description":"Optional mascot name. When omitted, AI chooses a short name from the image. No character description is generated."}},"required":["project_id"],"additionalProperties":false,"description":"Explicitly create a new mascot in this project. Send this or mascot_id, never both."},"variant_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":100,"default":"Animation","description":"Animation action name, separate from the mascot name."},"animation_prompt":{"type":"string","minLength":1,"maxLength":5000},"animation_model":{"type":"string","enum":["standard","premium"],"default":"standard","description":"Standard: 2 credits/sec, 5–15 seconds. Premium: 6 credits/sec, 4–30 seconds. Defaults to Standard."},"duration":{"type":"integer","minimum":4,"maximum":30,"default":5},"loop":{"type":"boolean","default":true}},"required":["source_image_asset_id","animation_prompt"],"additionalProperties":false},"Voice":{"type":"object","nullable":true,"properties":{"object":{"type":"string","enum":["voice"]},"name":{"type":"string"},"description":{"type":"string","description":"The words the voice was designed from."},"sample_url":{"type":"string","nullable":true,"format":"uri","description":"A short recording of the voice. Signed; fetch the voice again for a fresh link."},"source":{"type":"string","enum":["original","variant","creator"],"description":"Whose voice this is: the mascot's own (original), the variant's own (variant), or the marketplace creator's (creator)."},"created_at":{"type":"string"}},"required":["object","name","description","sample_url","source","created_at"]},"KeepVoiceBody":{"type":"object","properties":{"sample_id":{"type":"string","format":"uuid","description":"A sample from POST .../voice/samples."},"name":{"type":"string","minLength":1,"maxLength":80,"description":"Defaults to \"<name>'s voice\"."}},"required":["sample_id"]},"VoiceIdea":{"type":"object","properties":{"title":{"type":"string","description":"A few words, such as \"Cozy and warm\"."},"description":{"type":"string","description":"The full description, ready for POST .../voice/samples."}},"required":["title","description"]},"VoiceAdjustment":{"type":"object","properties":{"description":{"type":"string","description":"The rewritten description."},"changes":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"description":"Each replaced or added passage. from is empty for added text."},"directions":{"type":"array","items":{"type":"string"},"description":"Directions that fit the new description."}},"required":["description","changes","directions"]},"AdjustVoiceBody":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":1000,"description":"The current voice description."},"direction":{"type":"string","maxLength":80,"description":"A direction such as \"Older\" or \"A little grumpy\". Omit it to only get directions for this description."}},"required":["description"]},"VoiceSamples":{"type":"object","properties":{"samples":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Pass it to PUT .../voice to keep this voice."},"url":{"type":"string","format":"uri"},"duration":{"type":"number","nullable":true}},"required":["id","url","duration"]}},"sample_line":{"type":"string"},"cost_credits":{"type":"number"},"expires_at":{"type":"string","description":"Samples not kept by then can no longer be kept."}},"required":["samples","sample_line","cost_credits","expires_at"]},"VoiceSamplesBody":{"type":"object","properties":{"description":{"type":"string","minLength":20,"maxLength":1000,"description":"How the voice sounds: age, pitch, pace, energy, texture, mood and accent."},"sample_line":{"type":"string","maxLength":500,"description":"The line the samples read. Lines shorter than 100 characters are extended. Omit it for a line in the mascot's name."}},"required":["description"]},"ProjectListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"Project":{"type":"object","properties":{"object":{"type":"string","enum":["project"],"description":"Resource type. Always \"project\"."},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","organization_id","created_at","updated_at"]},"Meta":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true,"description":"Pass as the cursor query parameter to get the next page. Null on the last page."}},"required":["total","limit","offset","has_more"]},"ProjectResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"CreateProjectBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Project display name. 1 to 255 characters."}},"required":["name"]},"CollectionListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"Collection":{"type":"object","properties":{"object":{"type":"string","enum":["mascot"],"description":"Resource type. Always \"mascot\"."},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"config":{"type":"object","properties":{"prompt":{"type":"string"},"reference_asset_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"style_card":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"caution_list":{"type":"array","items":{"type":"string"}}},"required":["prompt","reference_asset_ids","style_card","caution_list"]},"is_published":{"type":"boolean"},"slug":{"type":"string","nullable":true},"user_prefix":{"type":"string","nullable":true},"cdn_status":{"type":"array","items":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid"},"item_name":{"type":"string","nullable":true},"type":{"type":"string"},"cdn_url":{"type":"string","format":"uri"},"status":{"type":"string"},"file_size":{"type":"number","nullable":true}},"required":["asset_id","item_name","type","cdn_url","status","file_size"]}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","type","created_at","updated_at"]},"CollectionResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]},"CreateCollectionBody":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid","description":"Project to create the collection in. List projects via GET /v1/projects."},"name":{"type":"string","description":"Display name. Defaults to a generated name if omitted."},"prompt":{"type":"string","description":"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":{"type":"string","description":"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":{"type":"string","default":"mascot","description":"Collection type. Defaults to \"mascot\"."},"style":{"type":"string","description":"Style ID or name. List styles via GET /v1/styles."},"design_touches":{"type":"array","items":{"type":"string","enum":["proportions","simple","asymmetry","grounded","few-colors","no-mouth","looks-at-you","blush","eyes-big","eyes-dots","signature","weird","twist","grown-up-flaw","magic-part","mood-cozy","mood-mischievous","mood-melancholy","mood-bold","mood-mysterious","mood-chaotic","mood-serene"]},"maxItems":22,"description":"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":{"type":"array","items":{"type":"string","format":"uri"},"description":"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":{"type":"array","items":{"type":"string","format":"uuid"},"description":"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":{"type":"object","properties":{"cdn_enabled":{"type":"boolean","default":true},"animation_sizes":{"type":"array","items":{"type":"number"}}},"description":"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."}},"required":["project_id"]},"UpdatedFlagResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UpdatedFlag"}},"required":["data"]},"UpdatedFlag":{"type":"object","properties":{"updated":{"type":"boolean"},"slug":{"type":"string"}},"required":["updated"]},"UpdateCollectionBody":{"type":"object","properties":{"name":{"type":"string","description":"New display name."},"context":{"type":"string","description":"Updated brand or product context."},"slug":{"type":"string","minLength":2,"maxLength":50,"description":"CDN slug for this collection. Used in the public URL path: https://assets.masko.ai/:user_prefix/:slug/... Globally unique across all collections. Normalized server-side: lowercased, non-alphanumeric stripped (hyphens kept), trimmed. After normalization must be 2 to 50 characters. Returns 409 if taken."},"config":{"type":"object","additionalProperties":{"nullable":true},"description":"Raw config object merged into existing config. Advanced use only: prefer dedicated endpoints /references and /settings; set slug with PATCH /v1/collections/:id."}}},"ItemListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"Item":{"type":"object","properties":{"object":{"type":"string","enum":["item"],"description":"Resource type. Always \"item\"."},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"prompt":{"type":"string"},"public_slug":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"created_at":{"type":"string"}},"required":["id","name","type","prompt","public_slug","created_at"]},"ItemResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ItemWithAssets"}},"required":["data"]},"ItemWithAssets":{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}},"required":["assets"]}]},"Asset":{"type":"object","properties":{"object":{"type":"string","enum":["asset"],"description":"Resource type. Always \"asset\"."},"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["interactive","interactive_frame","image","transparent_image","sticker_image","svg","video","webm","hevc","stacked_video","scene","logo","audio","transcript"]},"status":{"type":"string"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Media dimensions, format and public asset context. Internal generation execution details are omitted."},"item_id":{"type":"string","nullable":true,"format":"uuid"},"collection_id":{"type":"string","nullable":true,"format":"uuid"},"file_url":{"type":"string","nullable":true,"format":"uri"},"cdn_url":{"type":"string","nullable":true,"format":"uri"},"is_archived":{"type":"boolean"},"archived_at":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","type","status","item_id","file_url","cdn_url","created_at"]},"UpdateItemBody":{"type":"object","properties":{"name":{"type":"string","minLength":1},"prompt":{"type":"string"}}},"AssetListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"CdnExportResponse":{"type":"object","properties":{"collection":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CdnExportItem"}}},"required":["collection","items"]},"CdnExportItem":{"type":"object","properties":{"name":{"type":"string"},"svg":{"type":"string","format":"uri"},"image":{"type":"string","format":"uri"},"transparent_image":{"type":"string","format":"uri"},"animations":{"type":"array","items":{"$ref":"#/components/schemas/CdnExportAnimation"}},"logos":{"type":"object","additionalProperties":{"type":"string"}},"stickers":{"type":"array","items":{"type":"string","format":"uri"}},"animated_stickers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source_asset_id":{"type":"string","format":"uuid"},"formats":{"type":"object","properties":{"telegram":{"type":"string","format":"uri"},"whatsapp":{"type":"string","format":"uri"},"wechat":{"type":"string","format":"uri"},"discord":{"type":"string","format":"uri"}},"additionalProperties":false}},"required":["id","source_asset_id","formats"]}},"interactions":{"type":"array","items":{"$ref":"#/components/schemas/CdnInteraction"}}},"required":["name"]},"CdnExportAnimation":{"type":"object","additionalProperties":{"type":"string"}},"CdnInteraction":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["cursor-follower"]},"width":{"type":"number","enum":[1024]},"height":{"type":"number","enum":[1024]},"frames":{"type":"object","properties":{"up-left":{"type":"string","format":"uri"},"up":{"type":"string","format":"uri"},"up-right":{"type":"string","format":"uri"},"left":{"type":"string","format":"uri"},"center":{"type":"string","format":"uri"},"right":{"type":"string","format":"uri"},"down-left":{"type":"string","format":"uri"},"down":{"type":"string","format":"uri"},"down-right":{"type":"string","format":"uri"}},"required":["up-left","up","up-right","left","center","right","down-left","down","down-right"]},"manifest_url":{"type":"string","format":"uri"}},"required":["version","id","name","kind","width","height","frames","manifest_url"]},"AssetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Asset"}},"required":["data"]},"AnimatedStickerReceipt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["animated_sticker"]},"source_asset_id":{"type":"string","format":"uuid"},"asset_ids":{"type":"object","properties":{"sticker_animation":{"type":"string","format":"uuid"}},"required":["sticker_animation"]},"status":{"type":"string","enum":["processing","completed","partial_failure","failed"]},"estimated_cost":{"type":"number","enum":[0]},"asset_hosting":{"type":"boolean"},"preview_url":{"type":"string","nullable":true},"preview_type":{"type":"string"},"poll_url":{"type":"string"},"formats":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source_asset_id":{"type":"string","format":"uuid"},"format":{"type":"string"},"size":{"type":"number","nullable":true},"job_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"error":{"type":"string","nullable":true},"file_url":{"type":"string","nullable":true},"public_url":{"type":"string","nullable":true},"metadata":{"nullable":true},"sticker_profile":{"type":"string"},"poster_url":{"type":"string","nullable":true},"poll_url":{"type":"string"}},"required":["id","source_asset_id","format","size","job_id","asset_id","status","error","file_url","public_url","poll_url"]},"minItems":4,"maxItems":4}},"required":["id","object","source_asset_id","asset_ids","status","estimated_cost","asset_hosting","preview_url","preview_type","poll_url","formats"]},"StickerGenerateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StickerGenerateData"}},"required":["data"]},"StickerGenerateData":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["completed"]},"source_asset_id":{"type":"string","format":"uuid"},"asset_ids":{"type":"object","properties":{"sticker_image":{"type":"string","format":"uuid"}},"required":["sticker_image"]},"estimated_cost":{"type":"number"},"sticker_image":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["sticker_image"]},"status":{"type":"string","enum":["completed"]},"file_url":{"type":"string","format":"uri"},"width":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"height":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true}},"required":["id","type","status","file_url"]}},"required":["job_id","status","source_asset_id","asset_ids","estimated_cost","sticker_image"]},"AnimatedStickerCreateBody":{"type":"object","properties":{"force":{"type":"boolean","default":false}},"additionalProperties":false},"AssetMaskRefinementResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AssetMaskRefinementData"}},"required":["data"]},"AssetMaskRefinementData":{"type":"object","properties":{"target":{"type":"string","enum":["video_mask_refinement"]},"dry_run":{"type":"boolean"},"video_asset_id":{"type":"string","format":"uuid"},"bg_job_id":{"type":"string"},"prompt":{"type":"string"},"op":{"type":"string","enum":["add","subtract"]},"model":{"type":"string","enum":["original","pro"]},"edge_cleanup":{"type":"object","properties":{"enabled":{"type":"boolean"},"size":{"type":"number"}},"required":["enabled","size"]},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc","stacked_video","lottie","dotlottie"]}},"sizes":{"type":"array","items":{"type":"number"}},"export_count":{"type":"number"},"archive_old":{"type":"boolean"},"active_variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"size":{"type":"number"},"bgJobId":{"type":"string"}},"required":["id","type"]}},"canvas":{"type":"object","properties":{"collectionId":{"type":"string","format":"uuid"},"canvasId":{"type":"string","format":"uuid"},"edgeId":{"type":"string"}}},"in_flight":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"poll_url":{"type":"string"}},"required":["job_id","poll_url"]},"job_id":{"type":"string","format":"uuid"},"poll_url":{"type":"string"}},"required":["target","dry_run","video_asset_id","bg_job_id","prompt","op","model","formats","sizes","export_count","archive_old","active_variants"]},"RefineAssetMaskBody":{"type":"object","properties":{"op":{"type":"string","enum":["add","subtract"],"default":"add","description":"Mask operation. add unions the prompted subject into the active mask; subtract removes it from the active mask."},"prompt":{"type":"string","minLength":1,"description":"Text prompt for the mask region to refine, e.g. \"the soccer ball\"."},"model":{"type":"string","enum":["original","pro"],"default":"pro","description":"Background mask refinement quality. Defaults to pro."},"edge_cleanup":{"type":"object","properties":{"enabled":{"type":"boolean","default":true},"size":{"type":"integer","minimum":128,"maximum":1024,"default":512}},"default":{"enabled":true,"size":512},"description":"Optional edge cleanup pass applied to the refined mask."},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc","stacked_video","lottie","dotlottie"]},"minItems":1,"description":"Derived formats to regenerate. Omit to infer the active formats already linked to the video."},"sizes":{"type":"array","items":{"type":"integer","minimum":32,"maximum":1920},"description":"Size variants to regenerate. Omit to infer active linked sizes, so all currently used variants are refreshed."},"archive_old":{"type":"boolean","default":true,"description":"Archive and unlink old matching derived assets after replacement assets are successfully published."},"dry_run":{"type":"boolean","default":true,"description":"Return the exact refinement/export plan without starting the workflow."}},"required":["prompt"]},"ReferenceResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReferenceData"}},"required":["data"]},"ReferenceData":{"type":"object","properties":{"reference_asset_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["reference_asset_ids"]},"AddReferenceBody":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Asset ID of an existing uploaded or generated image. If the asset is not already scoped to this collection, the API creates a collection-scoped reference copy and stores that copied asset ID in reference_asset_ids."},"url":{"type":"string","format":"uri","description":"Public HTTP(S) image URL, up to 10 MB with a 15-second download deadline. Private addresses and unsafe redirects are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. Downloaded and stored as a collection-scoped reference asset."}}},"TalkingDryRunResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"dry_run":{"type":"boolean","enum":[true]},"script":{"type":"string"},"estimate":{"$ref":"#/components/schemas/TalkingEstimate"}},"required":["dry_run","script","estimate"]}},"required":["data"]},"GenerateAsyncResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GenerateAsyncData"}},"required":["data"]},"JsonResponse":{"type":"object","properties":{},"additionalProperties":{"nullable":true}},"GenerateBody":{"oneOf":[{"$ref":"#/components/schemas/GenerateImageBody"},{"$ref":"#/components/schemas/GenerateAnimationBody"},{"$ref":"#/components/schemas/GenerateEditBody"},{"$ref":"#/components/schemas/GenerateLogoBody"},{"$ref":"#/components/schemas/GenerateSceneBody"}],"discriminator":{"propertyName":"type","mapping":{"image":"#/components/schemas/GenerateImageBody","animation":"#/components/schemas/GenerateAnimationBody","edit":"#/components/schemas/GenerateEditBody","logo":"#/components/schemas/GenerateLogoBody","scene":"#/components/schemas/GenerateSceneBody"}}},"GenerateImageBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/collections/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this collection. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"visual_references":{"type":"array","items":{"$ref":"#/components/schemas/VisualReferenceBody"},"maxItems":4,"description":"One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become collection mascot references and do not update the collection style card."},"type":{"type":"string","enum":["image"]},"image_prompt":{"type":"string","description":"What the character is doing in the image, e.g. \"waving hello with a big smile\"."}},"required":["type"],"description":"Generate a static image (pose). Cost: 1 credit."},"VisualReferenceBody":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Existing image asset ID to use as a one-time visual reference."},"url":{"type":"string","format":"uri","description":"Public image URL to use as a one-time visual reference."},"role":{"type":"string","enum":["pose","expression","motion","prop","style","scene"],"description":"What the model should borrow from this image."},"note":{"type":"string","maxLength":300,"description":"Optional instruction for this reference, e.g. \"closed-mouth smile\"."}}},"GenerateAnimationBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/collections/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this collection. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"animation_model":{"type":"string","enum":["standard","premium"],"description":"Same choices as Studio: standard costs 2 credits/sec (5–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s)."},"duration":{"type":"integer","minimum":4,"maximum":30,"description":"Whole seconds. Standard: 5–15; Premium: 4–30; default 5 with either explicit model. Without animation_model: 4–10, default 4. An additional image costs 1 credit only when a source image must be generated."},"type":{"type":"string","enum":["animation"]},"animation_prompt":{"type":"string","description":"How the character moves, e.g. \"bouncing up and down energetically\". You can generate an animation directly from just this: when neither item_id nor source_image_asset_id is passed, the system generates a source image first (adds 1 credit), then animates it."},"image_prompt":{"type":"string","description":"Used only when no source image exists. The character description that gets passed to image generation before animation starts."},"source_image_asset_id":{"type":"string","format":"uuid","description":"Completed image asset to animate, including an unattached image from POST /v1/upload. Unattached uploads owned by the caller are imported into this mascot without changing references or generating a new image; only animation credits are charged. The original upload is preserved. Non-square inputs are center-cropped to square before animation. Square inputs are reused unchanged. Use source_image_crop for explicit framing. Optional variant_id freezes the selected context for this import. Existing mascot assets retain their saved context. Prefer item_id to reuse an existing item image."},"source_image_crop":{"type":"object","properties":{"x":{"type":"integer","minimum":0},"y":{"type":"integer","minimum":0},"width":{"type":"integer","minimum":0,"exclusiveMinimum":true},"height":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["x","y","width","height"],"description":"Optional square crop for the starting image: integer x, y, width, height in pixels after EXIF orientation. Defaults to a centered square for non-square images. Requires source_image_asset_id or an item_id with an existing image. Cropping is free and preserves the original file."},"end_image_crop":{"type":"object","properties":{"x":{"type":"integer","minimum":0},"y":{"type":"integer","minimum":0},"width":{"type":"integer","minimum":0,"exclusiveMinimum":true},"height":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["x","y","width","height"],"description":"Optional square crop for end_image_asset_id, in pixels after EXIF orientation. Defaults to a centered square for non-square end frames. Requires end_image_asset_id."},"end_image_asset_id":{"type":"string","format":"uuid","description":"Target pose image for a transition, including a pose from another variant. The prompt writer uses the starting and ending images plus their separate saved contexts to write the transition direction. The job records both endpoints and the exact prompt under generation_context.transition. Forces loop to false."},"loop":{"type":"boolean","description":"Whether the animation loops seamlessly. Defaults to true. Automatically set to false when end_image_asset_id is provided."},"reverse":{"type":"boolean","description":"Reverse an existing video. Used with reverse_of_video_asset_id. Costs 0 credits."},"reverse_of_video_asset_id":{"type":"string","format":"uuid","description":"Asset ID of the forward video to reverse. Required when reverse is true."},"auto_reverse":{"type":"boolean","description":"Transitions only: also generate the reverse transition (end to source) at 0 extra credits. Requires source_image_asset_id + end_image_asset_id. Response includes a reverse_job field."},"reverse_name":{"type":"string","description":"Name for the auto-generated reverse item. Defaults to \"<item name> (Reverse)\"."},"sizes":{"type":"array","items":{"type":"integer","minimum":64,"maximum":1080},"description":"Requested animation size variants in pixels, e.g. [480, 360]. Filtered against the collection settings. No extra credit cost."},"speech":{"$ref":"#/components/schemas/SpeechInput"},"dry_run":{"type":"boolean","description":"With speech: return the estimate (and the script, when Masko writes the movements) without charging or generating."}},"required":["type"]},"SpeechInput":{"type":"object","properties":{"script":{"type":"string","minLength":1,"maxLength":15000,"description":"What the mascot says, with movements in square brackets placed where each one starts, e.g. \"[waves hello, excited] Hi! I'm Gubby. [points to the right] The docs are right here!\". A feeling after a comma also steers the voice."},"text":{"type":"string","minLength":1,"maxLength":7500,"description":"The words alone, instead of script. Masko writes the movements, following direction when given, and returns the script it used."},"direction":{"type":"string","maxLength":500,"description":"With text: how the mascot should perform the line, e.g. \"excited about what he does, points at the docs at the end\"."},"language":{"type":"string","pattern":"^[a-z]{2}$","description":"ISO 639-1 code of the line. Omit it to detect the language from the words."}},"description":"Makes a talking animation: the mascot says this line in its voice (from its context, or its variant's), starting from item_id or source_image_asset_id and ending on end_image_asset_id (or the start image). The length comes from the speech: 5 seconds to 5 minutes at 2 credits per second. A talk longer than one take (15 seconds) is cut in its pauses into takes that start and end on the start image, then joined. The receipt adds audio and transcript assets and an estimate."},"GenerateEditBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/collections/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this collection. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"visual_references":{"type":"array","items":{"$ref":"#/components/schemas/VisualReferenceBody"},"maxItems":4,"description":"One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become collection mascot references and do not update the collection style card."},"type":{"type":"string","enum":["edit"]},"edit_instructions":{"type":"string","description":"What to change on the source asset, e.g. \"add a santa hat\". Required."},"source_image_asset_id":{"type":"string","format":"uuid","description":"Asset ID of the image to edit. Use `data.asset_ids.image` from a previous /generate response. If you pass `item_id`, the source is resolved from the item automatically."},"source_video_asset_id":{"type":"string","format":"uuid","description":"Completed 4–30 second video in this collection to edit at 720p. Duration and aspect ratio are preserved. Uses the source clip and its source item. For transition clips, edits preserve both saved endpoint identities and their order; variant_id does not restyle the whole clip. The edit prompt is recorded in generation_context.transition_edit."}},"required":["type","edit_instructions"],"description":"Edit an existing image or video with natural-language instructions. Cost: 1 credit for images, 5 credits per second for videos, rounded up to a whole credit."},"GenerateLogoBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/collections/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this collection. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"type":{"type":"string","enum":["logo"]},"request_id":{"type":"string","format":"uuid","description":"Stable retry key. Requires item_id; reuse unchanged after an uncertain response."},"logo_style_id":{"type":"string","enum":["graphic-app-icon","cut-paper","soft-depth","geometric","abstract-symbol","monoline-symbol","negative-space","retro-emblem","hand-drawn"],"description":"Preset from GET /v1/logo-styles. Explicit style name/instruction override preset fields."},"logo_description":{"type":"string","description":"What the logo should look like, e.g. \"iconic face-only, circular badge\". Defaults to \"Iconic representation of the character\"."},"logo_style_name":{"type":"string","description":"Short label for the logo style, e.g. \"Flat\", \"Retro\". Defaults to \"Flat\"."},"logo_style_instruction":{"type":"string","description":"Detailed style instructions, e.g. \"Flat design with solid colors, no gradients\"."}},"required":["type"],"description":"Generate a logo master plus a validated transparent version and resized exports. Native alpha is reused when valid; otherwise the transparent version removes the background. The master retains intentional backgrounds. Cost: 5 credits."},"GenerateSceneBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/collections/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this collection. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"type":{"type":"string","enum":["scene"]},"source_asset_id":{"type":"string","format":"uuid","description":"For a new scene: completed character image to use as its reference. Its saved variant context is retained unless an explicitly selected variant intentionally includes this reference. Use source_image_asset_id instead to edit an existing scene."},"scene":{"type":"string","description":"The environment, e.g. \"cozy reading nook with afternoon light\". Required unless editing (source_image_asset_id + edit_instructions)."},"action":{"type":"string","description":"What the mascot is doing in the scene, e.g. \"reading a book\". Required unless editing."},"aspect_ratio":{"type":"string","enum":["4:3","1:1","21:9","4:5","3:4","9:16"],"description":"Output aspect ratio. Use 4:3 for marketplace_card or marketplace_story, 1:1 for marketplace_square, 21:9 for hero_desktop, and 4:5 or 3:4 for hero_mobile."},"position":{"type":"string","enum":["left","center","right"],"description":"Where the mascot sits in the frame. Defaults: right for 21:9, center for others."},"source_image_asset_id":{"type":"string","format":"uuid","description":"For scene edits: existing scene asset to edit. Must be paired with edit_instructions."},"edit_instructions":{"type":"string","description":"For scene edits: what to change, e.g. \"warm up the lighting\". Paired with source_image_asset_id."}},"required":["type"],"description":"Generate a 4K scene image of the mascot in an environment, or edit an existing scene. Cost: 3 credits."},"ReferenceVideoAsyncResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"item_id":{"type":"string","format":"uuid"},"start_item_id":{"type":"string","format":"uuid"},"end_item_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"asset_ids":{"type":"object","properties":{"mascot_image":{"type":"string","format":"uuid"},"video":{"type":"string","format":"uuid"},"webm":{"type":"string","format":"uuid"},"hevc":{"type":"string","format":"uuid"},"start_image":{"type":"string","format":"uuid"},"start_transparent":{"type":"string","format":"uuid"},"end_image":{"type":"string","format":"uuid"},"end_transparent":{"type":"string","format":"uuid"}},"required":["mascot_image","video","webm","hevc","start_image","start_transparent","end_image","end_transparent"]},"estimated_cost":{"type":"integer"},"poll_url":{"type":"string"}},"required":["job_id","item_id","start_item_id","end_item_id","asset_id","asset_ids","estimated_cost","poll_url"]}},"required":["data"]},"ReferenceVideoBody":{"type":"object","properties":{"video_asset_id":{"type":"string","format":"uuid","description":"Owned, completed video asset containing the reference motion. Upload an MP4 or WebM with POST /v1/upload first."},"first_frame_asset_id":{"type":"string","format":"uuid","description":"Owned, completed image asset showing the first frame of the reference video. Upload it with POST /v1/upload."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Name for the animation. Start and end pose items are also created."},"prompt":{"type":"string","maxLength":10000,"description":"Optional instructions for the mascot pose and appearance."},"duration":{"type":"integer","minimum":4,"maximum":30,"default":5,"description":"Output duration in whole seconds, 4–30. Default 5. Premium costs 6 credits/sec plus 1 image credit."},"animation_model":{"type":"string","enum":["premium"],"default":"premium","description":"From Video always uses Premium. Standard is available for image-to-video animation through /generate."},"variant_id":{"type":"string","format":"uuid","description":"Optional approved mascot variant to animate."},"context_asset_id":{"type":"string","format":"uuid","description":"Optional asset in this collection whose saved mascot context is reused when variant_id is omitted."}},"required":["video_asset_id","first_frame_asset_id","name"],"additionalProperties":false},"BatchAsyncResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BatchAsyncData"}},"required":["data"]},"BatchAsyncData":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/GenerateAsyncData"}},"total_cost":{"type":"number"},"poll_url":{"type":"string"}},"required":["jobs","total_cost","poll_url"]},"GenerateBatchBody":{"type":"object","properties":{"requests":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/GenerateImageBody"},{"$ref":"#/components/schemas/GenerateAnimationBody"},{"$ref":"#/components/schemas/GenerateEditBody"},{"$ref":"#/components/schemas/GenerateLogoBody"},{"$ref":"#/components/schemas/GenerateSceneBody"}],"discriminator":{"propertyName":"type","mapping":{"image":"#/components/schemas/GenerateImageBody","animation":"#/components/schemas/GenerateAnimationBody","edit":"#/components/schemas/GenerateEditBody","logo":"#/components/schemas/GenerateLogoBody","scene":"#/components/schemas/GenerateSceneBody"}}},"minItems":1,"maxItems":10,"description":"Up to 10 generate requests run in parallel. Each request follows the same discriminated schema as /generate. Credits are deducted per request. Talking animations (speech) are sent one by one to /generate."}},"required":["requests"]},"SuggestionsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SuggestionsData"}},"required":["data"]},"SuggestionsData":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"string"}}},"required":["suggestions"]},"SceneSuggestionsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SceneSuggestionsData"}},"required":["data"]},"SceneSuggestionsData":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"emoji":{"type":"string"},"scene":{"type":"string"},"action":{"type":"string"},"position":{"type":"string"}},"required":["name","scene","action"]}}},"required":["suggestions"]},"UpdateSettingsBody":{"type":"object","properties":{"publish_params":{"type":"object","properties":{"image_exports":{"type":"object","properties":{"enabled":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string","enum":["original","transparent","sticker"]},"minItems":1,"maxItems":3},"formats":{"type":"array","items":{"type":"string","enum":["png","webp"]},"minItems":1,"maxItems":2},"sizes":{"type":"array","items":{"type":"integer","minimum":32,"maximum":2048},"minItems":1,"maxItems":5}},"required":["enabled","sources","formats","sizes"],"additionalProperties":false},"prores_exports":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false,"description":"Automatically create original-delivery-size ProRes 4444 MOV files with alpha after transparent animations finish. Disabled by default."},"animation_sizes":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether animation size variants are generated."},"sizes":{"type":"array","items":{"type":"number"},"description":"Pixel sizes to generate. Any integer from 32 to 1920. Common values: 720, 480, 360, 240."}},"required":["enabled","sizes"]}},"description":"Export settings. prores_exports enables original-size ProRes 4444 with alpha for future transparent animations. image_exports applies to future image completions. animation_sizes retains existing automatic video export behavior, including scheduling existing videos when settings change. Use POST /v1/mascots/:id/exports for explicit backfill."},"force_refresh":{"type":"boolean"}}},"SizeVariantsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SizeVariantsData"}},"required":["data"]},"SizeVariantsData":{"type":"object","properties":{"size_variant_jobs":{"type":"integer","minimum":0},"sizes":{"type":"array","items":{"type":"integer"}},"force":{"type":"boolean"}},"required":["size_variant_jobs","sizes","force"]},"GenerateSizeVariantsBody":{"type":"object","properties":{"sizes":{"type":"array","items":{"type":"integer","minimum":32,"maximum":1920},"description":"Sizes to generate. Defaults to the collection's configured animation_sizes, or [360]."},"force":{"type":"boolean","description":"Regenerate even sizes that already exist. Default false (idempotent: only missing sizes, never supersedes in-flight jobs)."}}},"CanvasListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CanvasListItem"}}},"required":["data"]},"CanvasListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","created_at","updated_at"]},"CanvasResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Canvas"}},"required":["data"]},"Canvas":{"type":"object","properties":{"object":{"type":"string","enum":["canvas"],"description":"Resource type. Always \"canvas\"."},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string","description":"Revision token for the full authored graph. Send this as expected_graph_hash when replacing the graph."},"status":{"type":"object","properties":{"nodes":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number","description":"Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset."},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]},"edges":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number"},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]},"ready":{"type":"boolean"},"generated_ready":{"type":"boolean"},"preview_ready":{"type":"boolean"},"media":{"type":"object","properties":{"generation":{"type":"object","properties":{"ready":{"type":"boolean"},"nodes":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number","description":"Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset."},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]},"edges":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number"},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]}},"required":["ready","nodes","edges"]},"preview":{"type":"object","properties":{"ready":{"type":"boolean"},"repairable":{"type":"boolean"},"repairable_edges":{"type":"number"},"waiting_edges":{"type":"number"},"missing_edges":{"type":"number"},"missing_formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["ready","repairable","repairable_edges","waiting_edges","missing_edges","missing_formats"]},"variants":{"type":"object","properties":{"sizes":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"object","properties":{"edge_id":{"type":"string"},"size":{"type":"string"},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["edge_id","size","formats"]}}},"required":["sizes","missing"]}},"required":["generation","preview","variants"]},"failed_nodes":{"type":"array","items":{"type":"object","properties":{"node_id":{"type":"string"},"job_id":{"type":"string","nullable":true,"format":"uuid"},"error":{"type":"string"}},"required":["node_id","job_id","error"]}},"failed_edges":{"type":"array","items":{"type":"object","properties":{"edge_id":{"type":"string"},"job_id":{"type":"string","nullable":true,"format":"uuid"},"error":{"type":"string"}},"required":["edge_id","job_id","error"]}},"edge_media":{"type":"array","items":{"type":"object","properties":{"edge_id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"video_asset_id":{"type":"string","nullable":true,"format":"uuid"},"reuses_edge_id":{"type":"string"},"base":{"type":"object","properties":{"video_ready":{"type":"boolean"},"webm_ready":{"type":"boolean"},"hevc_ready":{"type":"boolean"},"preview_ready":{"type":"boolean"},"derivatives_in_flight":{"type":"boolean"},"source_job_id":{"type":"string","format":"uuid"},"source_job_status":{"type":"string"},"missing":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["video_ready","webm_ready","hevc_ready","preview_ready","derivatives_in_flight","missing"]},"variants":{"type":"object","additionalProperties":{"type":"object","properties":{"webm_ready":{"type":"boolean"},"hevc_ready":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["webm_ready","hevc_ready","missing"]}}},"required":["edge_id","source","target","video_asset_id","base","variants"]}}},"required":["nodes","edges","ready","failed_nodes","failed_edges"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","graph","graph_content_hash"]},"CreateCanvasBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Display name for the canvas."},"graph":{"type":"object","additionalProperties":{"nullable":true},"description":"Canvas graph JSON with nodes, edges, and inputs. Omit to create an empty canvas. Mutually exclusive with template_id."},"template_id":{"type":"string","minLength":1,"description":"Optional template to apply at creation. Creates items, starts image generation for each node, and returns the populated graph plus job IDs. List templates via GET /v1/canvas-templates."},"node_overrides":{"type":"object","additionalProperties":{"nullable":true},"description":"Per-node overrides keyed by node key. Merged into template nodes before creation. Only used when template_id is provided."},"edge_overrides":{"type":"object","additionalProperties":{"nullable":true},"description":"Per-edge overrides keyed by \"source->target\" key. Merged into template edges before creation. Only used when template_id is provided."}},"required":["name"]},"CanvasRepairResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanvasRepairData"}},"required":["data"]},"CanvasRepairData":{"type":"object","properties":{"target":{"type":"string","enum":["video_derivatives"]},"dry_run":{"type":"boolean"},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}},"status":{"type":"object","properties":{"generated_ready":{"type":"boolean"},"preview_ready":{"type":"boolean"},"media":{"type":"object","properties":{"generation":{"type":"object","properties":{"ready":{"type":"boolean"},"nodes":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number","description":"Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset."},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]},"edges":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number"},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]}},"required":["ready","nodes","edges"]},"preview":{"type":"object","properties":{"ready":{"type":"boolean"},"repairable":{"type":"boolean"},"repairable_edges":{"type":"number"},"waiting_edges":{"type":"number"},"missing_edges":{"type":"number"},"missing_formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["ready","repairable","repairable_edges","waiting_edges","missing_edges","missing_formats"]},"variants":{"type":"object","properties":{"sizes":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"object","properties":{"edge_id":{"type":"string"},"size":{"type":"string"},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["edge_id","size","formats"]}}},"required":["sizes","missing"]}},"required":["generation","preview","variants"]}},"required":["generated_ready","preview_ready"]},"summary":{"type":"object","properties":{"edges_checked":{"type":"number"},"videos_checked":{"type":"number"},"videos_ready":{"type":"number"},"videos_to_repair":{"type":"number"},"videos_in_flight":{"type":"number"},"videos_skipped":{"type":"number"}},"required":["edges_checked","videos_checked","videos_ready","videos_to_repair","videos_in_flight","videos_skipped"]},"repairs":{"type":"array","items":{"type":"object","properties":{"video_asset_id":{"type":"string","format":"uuid"},"edge_ids":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}},"action":{"type":"string","enum":["create_derivatives","already_in_flight"]},"job_id":{"type":"string","format":"uuid"}},"required":["video_asset_id","edge_ids","missing","action"]}},"in_flight":{"type":"array","items":{"type":"object","properties":{"video_asset_id":{"type":"string","format":"uuid"},"edge_ids":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}},"action":{"type":"string","enum":["create_derivatives","already_in_flight"]},"job_id":{"type":"string","format":"uuid"}},"required":["video_asset_id","edge_ids","missing","action"]}},"skipped":{"type":"array","items":{"type":"object","properties":{"video_asset_id":{"type":"string","format":"uuid"},"edge_ids":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"}},"required":["video_asset_id","edge_ids","reason"]}},"jobs":{"type":"array","items":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"poll_url":{"type":"string"},"video_asset_id":{"type":"string","format":"uuid"},"edge_ids":{"type":"array","items":{"type":"string"}},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["job_id","poll_url","video_asset_id","edge_ids","formats"]}}},"required":["target","dry_run","formats","status","summary","repairs","in_flight","skipped"]},"RepairCanvasBody":{"type":"object","properties":{"target":{"type":"string","enum":["video_derivatives"],"default":"video_derivatives","description":"Repair target. Use video_derivatives when canvas status shows status.media.preview.repairable=true because completed edge videos are missing base WebM and/or HEVC child assets. If status.media.preview.waiting_edges > 0, wait and poll again instead of repairing. This target only repairs videos already assigned to the canvas graph."},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]},"minItems":1,"default":["webm","hevc"],"description":"Base derivative formats to repair. Defaults to both webm and hevc. This does not include size variants; optimized sizes must be generated through the size-variant flow."},"dry_run":{"type":"boolean","default":true,"description":"When true, returns the exact repair plan without creating jobs or assets. Defaults to true. Agents should call dry_run=true first, inspect repairs/skipped/in_flight, then call dry_run=false only if the plan touches the intended videos."}}},"CanvasFacingDetectionResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanvasFacingDetectionData"}},"required":["data"]},"CanvasFacingDetectionData":{"type":"object","properties":{"suggestedNaturalFacing":{"type":"string","enum":["left","neutral","right"]},"confidence":{"type":"number"},"warning":{"type":"string"},"analyzedNodeCount":{"type":"integer","minimum":0},"nodeResults":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"nodeName":{"type":"string"},"facing":{"type":"string","enum":["left","neutral","right"]},"confidence":{"type":"number"},"reason":{"type":"string"}},"required":["nodeId","nodeName","facing","confidence"]}}},"required":["suggestedNaturalFacing","confidence","analyzedNodeCount","nodeResults"]},"UpdateCanvasBody":{"type":"object","properties":{"graph":{"type":"object","additionalProperties":{"nullable":true},"description":"Full canvas graph to replace the current one. Nodes, edges, and inputs are overwritten."},"expected_graph_hash":{"type":"string","minLength":1,"description":"Graph content hash returned by the latest GET. When provided, the update is rejected with 409 if the canvas changed before this full-graph save."}},"required":["graph"]},"CanvasGraphExtendResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanvasGraphExtendData"}},"required":["data"]},"CanvasGraphExtendData":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","additionalProperties":{"nullable":true}},"updated_at":{"type":"string"},"added":{"type":"object","properties":{"nodes":{"type":"number"},"edges":{"type":"number"},"inputs":{"type":"number"}},"required":["nodes","edges","inputs"]},"updated":{"type":"object","properties":{"edges":{"type":"number"}},"required":["edges"]}},"required":["id","name","graph","updated_at","added","updated"]},"ExtendCanvasGraphBody":{"type":"object","properties":{"add_nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"generationVariantId":{"type":"string","format":"uuid","description":"Approved variant in the same collection used by generate-all for a new pose. Existing pose identity is preserved; completed assets are not regenerated."}},"required":["id"],"additionalProperties":{"nullable":true}},"default":[],"description":"Nodes to append. Fails if any node ID already exists."},"add_edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":{"nullable":true}},"default":[],"description":"Edges to append. Fails if any edge ID already exists."},"update_edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":{"nullable":true}},"default":[],"description":"Partial edge patches keyed by id. Existing edge fields are preserved unless explicitly overwritten."},"add_inputs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"],"additionalProperties":{"nullable":true}},"default":[],"description":"Inputs to append. Existing input names are left unchanged."}}},"CanvasEdgePatchResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanvasEdgePatchData"}},"required":["data"]},"CanvasEdgePatchData":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"edge":{"type":"object","additionalProperties":{"nullable":true}},"graph":{"type":"object","additionalProperties":{"nullable":true}},"updated_at":{"type":"string"}},"required":["id","name","edge","graph","updated_at"]},"PatchCanvasEdgeBody":{"type":"object","properties":{"speed":{"type":"number","minimum":0.1,"maximum":10,"description":"Playback speed multiplier for this edge. Normal transitions use 2, snappy interact transitions use 3-4, calm loops use 1."}}},"CanvasEdgeGenerateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanvasEdgeGenerateData"}},"required":["data"]},"CanvasEdgeGenerateData":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"edge_id":{"type":"string"},"type":{"type":"string","enum":["loop","transition"]},"source":{"type":"string"},"target":{"type":"string"},"cost":{"type":"number"},"urls":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"poll_url":{"type":"string"}},"required":["job_id","edge_id","type","source","target","cost","poll_url"]},"GenerateEdgeBody":{"type":"object","properties":{"animation_model":{"type":"string","enum":["standard","premium"],"description":"Same choices as Studio: standard costs 2 credits/sec (5–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s)."},"duration":{"type":"integer","minimum":4,"maximum":30,"description":"Whole seconds. Standard: 5–15; Premium: 4–30; default 5 with either explicit model. Without animation_model: 4–10, default 4. An additional image costs 1 credit only when a source image must be generated."}}},"RefineCanvasEdgeMaskBody":{"type":"object","properties":{"op":{"type":"string","enum":["add","subtract"],"default":"add","description":"Mask operation. add unions the prompted subject into the active mask; subtract removes it from the active mask."},"prompt":{"type":"string","minLength":1,"description":"Text prompt for the mask region to refine, e.g. \"the soccer ball\"."},"model":{"type":"string","enum":["original","pro"],"default":"pro","description":"Background mask refinement quality. Defaults to pro."},"edge_cleanup":{"type":"object","properties":{"enabled":{"type":"boolean","default":true},"size":{"type":"integer","minimum":128,"maximum":1024,"default":512}},"default":{"enabled":true,"size":512},"description":"Optional edge cleanup pass applied to the refined mask."},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc","stacked_video","lottie","dotlottie"]},"minItems":1,"description":"Derived formats to regenerate. Omit to infer the active formats already linked to the video."},"sizes":{"type":"array","items":{"type":"integer","minimum":32,"maximum":1920},"description":"Size variants to regenerate. Omit to infer active linked sizes, so all currently used variants are refreshed."},"archive_old":{"type":"boolean","default":true,"description":"Archive and unlink old matching derived assets after replacement assets are successfully published."},"dry_run":{"type":"boolean","default":true,"description":"Return the exact refinement/export plan without starting the workflow."}},"required":["prompt"]},"GenerateAllBody":{"type":"object","properties":{"animation_model":{"type":"string","enum":["standard","premium"],"description":"Same choices as Studio: standard costs 2 credits/sec (5–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s)."},"duration":{"type":"integer","minimum":4,"maximum":30,"description":"Whole seconds. Standard: 5–15; Premium: 4–30; default 5 with either explicit model. Without animation_model: 4–10, default 4. An additional image costs 1 credit only when a source image must be generated."},"max_credits":{"type":"number","minimum":0,"description":"Hard server-side credit ceiling. Execution fails before billing when the current work exceeds this limit."},"skip_completed":{"type":"boolean","default":true,"description":"Deprecated compatibility flag. Canvas generate-all only dispatches missing work and always skips edges that already have assigned generated assets."},"include_stickers":{"type":"boolean","default":false,"description":"When true, generate sticker_image derivatives for generated image nodes."},"dry_run":{"type":"boolean","default":false,"description":"When true, only returns the planned work, prompts, skipped items, and estimated credit cost. Does not deduct credits, create jobs/assets/items, mutate the canvas graph, or start workflows."},"targets":{"type":"string","enum":["all","images","stickers","animations"],"default":"all","description":"Which work to dispatch. \"images\" only generates skeleton node images. \"stickers\" backfills sticker_image derivatives for completed node images. \"animations\" only dispatches edge videos. \"all\" does both images and animations."},"node_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Optional exact node selection. When present, only these nodes are considered for image or sticker work. Omit to consider every node."},"edge_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":200,"description":"Optional exact edge selection. When present, only these edges are considered for animation work. Omit to consider every edge."},"expected_graph_hash":{"type":"string","minLength":1,"description":"Optional graph revision returned by the dry-run plan. Execution returns 409 if the canvas changed after approval."},"approved_plan_id":{"type":"string","minLength":1,"description":"Optional generation plan identity returned by dry_run. Execution returns 409 unless the current graph, scope, prompts, duration, and generation options still match that approved plan."}}},"ExportConfigResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExportConfigData"}},"required":["data"]},"ExportConfigData":{"type":"object","additionalProperties":{"nullable":true}},"CanvasTemplateListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CanvasTemplate"}}},"required":["data"]},"CanvasTemplate":{"type":"object","properties":{"object":{"type":"string","enum":["canvas_template"],"description":"Resource type. Always \"canvas_template\"."},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source":{"type":"string","enum":["builtin","user"]},"public":{"type":"boolean"},"nodes":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"edges":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"inputs":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"created_at":{"type":"string"}},"required":["id","name","description","source"]},"CanvasTemplateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanvasTemplate"}},"required":["data"]},"CreateTemplateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Template name."},"description":{"type":"string","description":"What the template does."},"canvas_id":{"type":"string","format":"uuid","description":"Existing canvas to snapshot. Required together with collection_id. Mutually exclusive with template."},"collection_id":{"type":"string","format":"uuid","description":"Source collection for the snapshot. Required together with canvas_id."},"template":{"type":"object","additionalProperties":{"nullable":true},"description":"Raw template JSON. Provide this OR (canvas_id + collection_id)."},"public":{"type":"boolean","description":"If true, template is visible to all users. Defaults to false."}},"required":["name"]},"UpdateTemplateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New template name."},"description":{"type":"string","description":"Updated description."},"template":{"type":"object","additionalProperties":{"nullable":true},"description":"Replacement template JSON."},"public":{"type":"boolean","description":"Toggle whether template is visible to all users."}}},"JobListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"Job":{"type":"object","properties":{"object":{"type":"string","enum":["job"],"description":"Resource type. Always \"job\"."},"variant_id":{"type":"string","nullable":true,"format":"uuid","description":"Selected mascot variant, or null for original-context and older untagged jobs."},"generation_context":{"type":"object","additionalProperties":{"nullable":true},"description":"Frozen generation context: variant id and name, engine hash, the mascot prompt and style you provided, reference asset IDs and asset inputs. Transitions include transition.before and transition.after with pose IDs and saved variant contexts; video edits add transition_edit with the source video and requested edit. Internal generation execution details are never included."},"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"type":{"type":"string","enum":["item_generation","image_generation","logo","animation","video_edit","reverse","size_variant","size_variant_batch","export_animation","scene_generation","sticker_generation","svg_generation","interactive_generation","re_export","canvas_orchestration"]},"collection_id":{"type":"string","nullable":true,"format":"uuid"},"cost_credits":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"item_id":{"type":"string","nullable":true,"format":"uuid"},"item_name":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"urls":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}},"required":["variant_id","id","status","type","collection_id","cost_credits","created_at","updated_at"]},"JobResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Job"}},"required":["data"]},"CreditsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreditsData"}},"required":["data"]},"CreditsData":{"type":"object","properties":{"subscription":{"type":"number"},"topup":{"type":"number"},"total":{"type":"number"}},"required":["subscription","topup","total"]},"StylesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StylePreset"}}},"required":["data"]},"StylePreset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail_url":{"type":"string","format":"uri"}},"required":["id","name"],"additionalProperties":{"nullable":true}},"UploadResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadData"}},"required":["data"]},"UploadData":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid"}},"required":["asset_id"]},"UploadUrlBody":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public HTTP(S) image URL without credentials. Downloaded server-side with a 15-second deadline, public-address checks on every redirect, and a streamed 10MB limit. Private addresses are rejected. Images only (image/png, image/jpeg, image/webp, image/svg+xml, image/gif). SVGs are auto-converted to PNG. For video uploads or binary files, POST the same endpoint as multipart/form-data with a \"file\" field (max 10MB for images, 50MB for videos)."}},"required":["url"]},"PreviewResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreviewData"}},"required":["data"]},"PreviewData":{"type":"object","properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expires_in":{"type":"number"}},"required":["url","expires_in"]}},"cost":{"type":"number"}},"required":["images","cost"]},"PreviewBody":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"description":"Text description of the mascot to preview. Preview exists for cheap idea iteration: tweak the prompt, regenerate, compare, then create the collection with the winning reference. Costs 1 credit per image generated."},"preset_id":{"type":"string","description":"Optional style preset ID. List presets via GET /v1/styles."},"count":{"type":"number","minimum":1,"maximum":6,"default":1,"description":"Number of preview variants to generate. 1 to 6. Defaults to 1."},"reference_image_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Optional \"check against\" images. Feed an image you want the mascot to resemble; the preview tries to match it. Useful for \"does this prompt produce something close to my sketch?\" iterations. Not stored - use POST /v1/collections/:id/references for persistent references."}},"required":["prompt"]},"AnalyzeImageResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyzeImageData"}},"required":["data"]},"AnalyzeImageData":{"type":"object","properties":{"suggested_name":{"type":"string"},"description":{"type":"string"},"style_hints":{"type":"array","items":{"type":"string"}},"suggested_prompt":{"type":"string"}},"required":["suggested_name","description","style_hints","suggested_prompt"]},"AnalyzeUrlResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyzeUrlData"}},"required":["data"]},"AnalyzeUrlData":{"type":"object","properties":{"screenshotPath":{"type":"string"},"markdown":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"description":{"type":"string"}},"additionalProperties":{"nullable":true}},"AnalyzeBody":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Analyze a mascot/character image."},"image_url":{"type":"string","format":"uri","description":"Public image URL to analyze. Returns a structured description suitable for seeding a collection prompt."}},"required":["type","image_url"]},{"type":"object","properties":{"type":{"type":"string","enum":["url"],"description":"Analyze a brand website."},"url":{"type":"string","format":"uri","description":"Website URL to analyze. Extracts brand colors, product description, and tone."}},"required":["type","url"]}],"description":"What to analyze. Use type=\"image\" with image_url to analyze a mascot picture, or type=\"url\" with url to analyze a brand website."},"WebhookListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"]},"Webhook":{"type":"object","properties":{"object":{"type":"string","enum":["webhook"],"description":"Resource type. Always \"webhook\"."},"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"consecutive_failures":{"type":"number"},"created_at":{"type":"string"}},"required":["id","url","events","active","consecutive_failures","created_at"]},"WebhookResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}},"required":["data"]},"CreateWebhookBody":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL that receives webhook POSTs as JSON. Each delivery includes Masko-Signature (t=<unix-seconds>,v1=<hmac-hex of \"<t>.<body>\">), X-Masko-Signature (sha256=<hmac-hex of body>), X-Masko-Timestamp, X-Masko-Event, and Masko-Event-Id headers. The body carries a stable event id that every retry reuses. A non-2xx response or network error is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, and 12 hours. Auto-disables after 100 consecutive failed attempts."},"events":{"type":"array","items":{"type":"string"},"description":"Event types to subscribe to. Omit for all events. Available events: job.completed, job.failed."}},"required":["url"]},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","doc_url","request_id"],"properties":{"code":{"type":"string","description":"Stable machine-readable code. Switch on this."},"message":{"type":"string","description":"Human-readable explanation."},"param":{"type":"string","description":"The request field that caused the error, when there is one."},"details":{"type":"object","additionalProperties":true,"description":"Extra context, for example issues for validation errors or required and balance for credits."},"doc_url":{"type":"string","format":"uri","description":"Documentation for this error code."},"request_id":{"type":"string","description":"Same value as the Request-Id header. Include it when contacting support."}}}}},"StudioAssetListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StudioAsset"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"StudioAsset":{"type":"object","properties":{"object":{"type":"string","enum":["asset"],"description":"Resource type. Always \"asset\"."},"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["interactive","interactive_frame","image","transparent_image","sticker_image","svg","video","webm","hevc","stacked_video","scene","logo","audio","transcript"]},"status":{"type":"string"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Media dimensions, format and public asset context. Internal generation execution details are omitted."},"item_id":{"type":"string","nullable":true,"format":"uuid"},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"file_url":{"type":"string","nullable":true,"format":"uri"},"cdn_url":{"type":"string","nullable":true,"format":"uri"},"is_archived":{"type":"boolean"},"archived_at":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","type","status","item_id","file_url","cdn_url","created_at"]},"StudioAssetResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StudioAsset"}},"required":["data"]},"StudioAssetMaskRefinementResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StudioAssetMaskRefinementData"}},"required":["data"]},"StudioAssetMaskRefinementData":{"type":"object","properties":{"target":{"type":"string","enum":["video_mask_refinement"]},"dry_run":{"type":"boolean"},"video_asset_id":{"type":"string","format":"uuid"},"bg_job_id":{"type":"string"},"prompt":{"type":"string"},"op":{"type":"string","enum":["add","subtract"]},"model":{"type":"string","enum":["original","pro"]},"edge_cleanup":{"type":"object","properties":{"enabled":{"type":"boolean"},"size":{"type":"number"}},"required":["enabled","size"]},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc","stacked_video","lottie","dotlottie"]}},"sizes":{"type":"array","items":{"type":"number"}},"export_count":{"type":"number"},"archive_old":{"type":"boolean"},"active_variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"size":{"type":"number"},"bgJobId":{"type":"string"}},"required":["id","type"]}},"canvas":{"type":"object","properties":{"mascot_id":{"type":"string","format":"uuid"},"canvasId":{"type":"string","format":"uuid"},"edgeId":{"type":"string"}}},"in_flight":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"poll_url":{"type":"string"}},"required":["job_id","poll_url"]},"job_id":{"type":"string","format":"uuid"},"poll_url":{"type":"string"}},"required":["target","dry_run","video_asset_id","bg_job_id","prompt","op","model","formats","sizes","export_count","archive_old","active_variants"]},"StudioCreateTemplateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Template name."},"description":{"type":"string","description":"What the template does."},"canvas_id":{"type":"string","format":"uuid","description":"Existing canvas to snapshot. Required together with mascot_id. Mutually exclusive with template."},"mascot_id":{"type":"string","format":"uuid","description":"Source mascot for the snapshot. Required together with canvas_id."},"template":{"type":"object","additionalProperties":{"nullable":true},"description":"Raw template JSON. Provide this OR (canvas_id + collection_id)."},"public":{"type":"boolean","description":"If true, template is visible to all users. Defaults to false."}},"required":["name"]},"StudioJobListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StudioJob"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"StudioJob":{"type":"object","properties":{"object":{"type":"string","enum":["job"],"description":"Resource type. Always \"job\"."},"variant_id":{"type":"string","nullable":true,"format":"uuid","description":"Selected mascot variant, or null for original-context and older untagged jobs."},"generation_context":{"type":"object","additionalProperties":{"nullable":true},"description":"Frozen generation context: variant id and name, engine hash, the mascot prompt and style you provided, reference asset IDs and asset inputs. Transitions include transition.before and transition.after with pose IDs and saved variant contexts; video edits add transition_edit with the source video and requested edit. Internal generation execution details are never included."},"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"type":{"type":"string","enum":["item_generation","image_generation","logo","animation","video_edit","reverse","size_variant","size_variant_batch","export_animation","scene_generation","sticker_generation","svg_generation","interactive_generation","re_export","canvas_orchestration"]},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"cost_credits":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"item_id":{"type":"string","nullable":true,"format":"uuid"},"item_name":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"urls":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}},"required":["variant_id","id","status","type","mascot_id","cost_credits","created_at","updated_at"]},"StudioJobResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StudioJob"}},"required":["data"]},"StudioAnalyzeBody":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["image"],"description":"Analyze a mascot/character image."},"image_url":{"type":"string","format":"uri","description":"Public image URL to analyze. Returns a structured description suitable for seeding a mascot prompt."}},"required":["type","image_url"]},{"type":"object","properties":{"type":{"type":"string","enum":["url"],"description":"Analyze a brand website."},"url":{"type":"string","format":"uri","description":"Website URL to analyze. Extracts brand colors, product description, and tone."}},"required":["type","url"]}],"description":"What to analyze. Use type=\"image\" with image_url to analyze a mascot picture, or type=\"url\" with url to analyze a brand website."},"StudioExtendCanvasGraphBody":{"type":"object","properties":{"add_nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"generationVariantId":{"type":"string","format":"uuid","description":"Approved variant in the same mascot used by generate-all for a new pose. Existing pose identity is preserved; completed assets are not regenerated."}},"required":["id"],"additionalProperties":{"nullable":true}},"default":[],"description":"Nodes to append. Fails if any node ID already exists."},"add_edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":{"nullable":true}},"default":[],"description":"Edges to append. Fails if any edge ID already exists."},"update_edges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":{"nullable":true}},"default":[],"description":"Partial edge patches keyed by id. Existing edge fields are preserved unless explicitly overwritten."},"add_inputs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1}},"required":["name"],"additionalProperties":{"nullable":true}},"default":[],"description":"Inputs to append. Existing input names are left unchanged."}}},"StudioCreateMascotVariantBody":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Client-generated UUID. Reuse it to safely retry creation."},"name":{"type":"string","minLength":1,"maxLength":80},"description":{"type":"string","minLength":1,"maxLength":3000,"description":"The desired change and generation guidance."},"source_variant_id":{"type":"string","format":"uuid","description":"Approved variant to start from. Omit for Original. Its references and context are frozen on creation."},"reference_asset_id":{"type":"string","format":"uuid","description":"Completed image in this mascot, or your unassigned POST /v1/upload image. Creates an approved context immediately; no generation charge. Omit to create a draft for reference generation."}},"required":["id","name","description"],"additionalProperties":false},"StudioCreateMascotBody":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid","description":"Project to create the mascot in. List projects via GET /v1/projects."},"name":{"type":"string","description":"Display name. Defaults to a generated name if omitted."},"prompt":{"type":"string","description":"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":{"type":"string","description":"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":{"type":"string","default":"mascot","description":"Mascot type. Defaults to \"mascot\"."},"style":{"type":"string","description":"Style ID or name. List styles via GET /v1/styles."},"design_touches":{"type":"array","items":{"type":"string","enum":["proportions","simple","asymmetry","grounded","few-colors","no-mouth","looks-at-you","blush","eyes-big","eyes-dots","signature","weird","twist","grown-up-flaw","magic-part","mood-cozy","mood-mischievous","mood-melancholy","mood-bold","mood-mysterious","mood-chaotic","mood-serene"]},"maxItems":22,"description":"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":{"type":"array","items":{"type":"string","format":"uri"},"description":"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":{"type":"array","items":{"type":"string","format":"uuid"},"description":"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."},"settings":{"type":"object","properties":{"cdn_enabled":{"type":"boolean","default":true},"animation_sizes":{"type":"array","items":{"type":"number"}}},"description":"Mascot 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."}},"required":["project_id"]},"StudioUpdateMascotBody":{"type":"object","properties":{"name":{"type":"string","description":"New display name."},"context":{"type":"string","description":"Updated brand or product context."},"slug":{"type":"string","minLength":2,"maxLength":50,"description":"CDN slug for this mascot. Used in the public URL path: https://assets.masko.ai/:user_prefix/:slug/... Globally unique across all mascots. Normalized server-side: lowercased, non-alphanumeric stripped (hyphens kept), trimmed. After normalization must be 2 to 50 characters. Returns 409 if taken."},"config":{"type":"object","additionalProperties":{"nullable":true},"description":"Raw config object merged into existing config. Advanced use only: prefer dedicated endpoints /references and /settings; set slug with PATCH /v1/collections/:id."}}},"StudioItemResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StudioItemWithAssets"}},"required":["data"]},"StudioItemWithAssets":{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/StudioAsset"}}},"required":["assets"]}]},"StudioCdnExportResponse":{"type":"object","properties":{"mascot":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CdnExportItem"}}},"required":["mascot","items"]},"StudioAddReferenceBody":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Asset ID of an existing uploaded or generated image. If the asset is not already scoped to this mascot, the API creates a mascot-scoped reference copy and stores that copied asset ID in reference_asset_ids."},"url":{"type":"string","format":"uri","description":"Public HTTP(S) image URL, up to 10 MB with a 15-second download deadline. Private addresses and unsafe redirects are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. Downloaded and stored as a mascot-scoped reference asset."}}},"StudioGenerateBody":{"oneOf":[{"$ref":"#/components/schemas/StudioGenerateImageBody"},{"$ref":"#/components/schemas/StudioGenerateAnimationBody"},{"$ref":"#/components/schemas/StudioGenerateEditBody"},{"$ref":"#/components/schemas/StudioGenerateLogoBody"},{"$ref":"#/components/schemas/StudioGenerateSceneBody"}],"discriminator":{"propertyName":"type","mapping":{"image":"#/components/schemas/GenerateImageBody","animation":"#/components/schemas/GenerateAnimationBody","edit":"#/components/schemas/GenerateEditBody","logo":"#/components/schemas/GenerateLogoBody","scene":"#/components/schemas/GenerateSceneBody"}}},"StudioGenerateImageBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"visual_references":{"type":"array","items":{"$ref":"#/components/schemas/VisualReferenceBody"},"maxItems":4,"description":"One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become mascot mascot references and do not update the mascot style card."},"type":{"type":"string","enum":["image"]},"image_prompt":{"type":"string","description":"What the character is doing in the image, e.g. \"waving hello with a big smile\"."}},"required":["type"],"description":"Generate a static image (pose). Cost: 1 credit."},"StudioGenerateAnimationBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"animation_model":{"type":"string","enum":["standard","premium"],"description":"Same choices as Studio: standard costs 2 credits/sec (5–15s); premium costs 6 credits/sec (4–30s). Both default to 5s. Omit to preserve legacy generation at 5 credits/sec (4–10s, default 4s)."},"duration":{"type":"integer","minimum":4,"maximum":30,"description":"Whole seconds. Standard: 5–15; Premium: 4–30; default 5 with either explicit model. Without animation_model: 4–10, default 4. An additional image costs 1 credit only when a source image must be generated."},"type":{"type":"string","enum":["animation"]},"animation_prompt":{"type":"string","description":"How the character moves, e.g. \"bouncing up and down energetically\". You can generate an animation directly from just this: when neither item_id nor source_image_asset_id is passed, the system generates a source image first (adds 1 credit), then animates it."},"image_prompt":{"type":"string","description":"Used only when no source image exists. The character description that gets passed to image generation before animation starts."},"source_image_asset_id":{"type":"string","format":"uuid","description":"Completed image asset to animate, including an unattached image from POST /v1/upload. Unattached uploads owned by the caller are imported into this mascot without changing references or generating a new image; only animation credits are charged. The original upload is preserved. Non-square inputs are center-cropped to square before animation. Square inputs are reused unchanged. Use source_image_crop for explicit framing. Optional variant_id freezes the selected context for this import. Existing mascot assets retain their saved context. Prefer item_id to reuse an existing item image."},"source_image_crop":{"type":"object","properties":{"x":{"type":"integer","minimum":0},"y":{"type":"integer","minimum":0},"width":{"type":"integer","minimum":0,"exclusiveMinimum":true},"height":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["x","y","width","height"],"description":"Optional square crop for the starting image: integer x, y, width, height in pixels after EXIF orientation. Defaults to a centered square for non-square images. Requires source_image_asset_id or an item_id with an existing image. Cropping is free and preserves the original file."},"end_image_crop":{"type":"object","properties":{"x":{"type":"integer","minimum":0},"y":{"type":"integer","minimum":0},"width":{"type":"integer","minimum":0,"exclusiveMinimum":true},"height":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["x","y","width","height"],"description":"Optional square crop for end_image_asset_id, in pixels after EXIF orientation. Defaults to a centered square for non-square end frames. Requires end_image_asset_id."},"end_image_asset_id":{"type":"string","format":"uuid","description":"Target pose image for a transition, including a pose from another variant. The prompt writer uses the starting and ending images plus their separate saved contexts to write the transition direction. The job records both endpoints and the exact prompt under generation_context.transition. Forces loop to false."},"loop":{"type":"boolean","description":"Whether the animation loops seamlessly. Defaults to true. Automatically set to false when end_image_asset_id is provided."},"reverse":{"type":"boolean","description":"Reverse an existing video. Used with reverse_of_video_asset_id. Costs 0 credits."},"reverse_of_video_asset_id":{"type":"string","format":"uuid","description":"Asset ID of the forward video to reverse. Required when reverse is true."},"auto_reverse":{"type":"boolean","description":"Transitions only: also generate the reverse transition (end to source) at 0 extra credits. Requires source_image_asset_id + end_image_asset_id. Response includes a reverse_job field."},"reverse_name":{"type":"string","description":"Name for the auto-generated reverse item. Defaults to \"<item name> (Reverse)\"."},"sizes":{"type":"array","items":{"type":"integer","minimum":64,"maximum":1080},"description":"Requested animation size variants in pixels, e.g. [480, 360]. Filtered against the mascot settings. No extra credit cost."},"speech":{"$ref":"#/components/schemas/SpeechInput"},"dry_run":{"type":"boolean","description":"With speech: return the estimate (and the script, when Masko writes the movements) without charging or generating."}},"required":["type"]},"StudioGenerateEditBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"visual_references":{"type":"array","items":{"$ref":"#/components/schemas/VisualReferenceBody"},"maxItems":4,"description":"One-time visual references for this generation only. Use for pose, expression, motion, props, style, or scene cues. These do not become mascot mascot references and do not update the mascot style card."},"type":{"type":"string","enum":["edit"]},"edit_instructions":{"type":"string","description":"What to change on the source asset, e.g. \"add a santa hat\". Required."},"source_image_asset_id":{"type":"string","format":"uuid","description":"Asset ID of the image to edit. Use `data.asset_ids.image` from a previous /generate response. If you pass `item_id`, the source is resolved from the item automatically."},"source_video_asset_id":{"type":"string","format":"uuid","description":"Completed 4–30 second video in this mascot to edit at 720p. Duration and aspect ratio are preserved. Uses the source clip and its source item. For transition clips, edits preserve both saved endpoint identities and their order; variant_id does not restyle the whole clip. The edit prompt is recorded in generation_context.transition_edit."}},"required":["type","edit_instructions"],"description":"Edit an existing image or video with natural-language instructions. Cost: 1 credit for images, 5 credits per second for videos, rounded up to a whole credit."},"StudioGenerateLogoBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"type":{"type":"string","enum":["logo"]},"request_id":{"type":"string","format":"uuid","description":"Stable retry key. Requires item_id; reuse unchanged after an uncertain response."},"logo_style_id":{"type":"string","enum":["graphic-app-icon","cut-paper","soft-depth","geometric","abstract-symbol","monoline-symbol","negative-space","retro-emblem","hand-drawn"],"description":"Preset from GET /v1/logo-styles. Explicit style name/instruction override preset fields."},"logo_description":{"type":"string","description":"What the logo should look like, e.g. \"iconic face-only, circular badge\". Defaults to \"Iconic representation of the character\"."},"logo_style_name":{"type":"string","description":"Short label for the logo style, e.g. \"Flat\", \"Retro\". Defaults to \"Flat\"."},"logo_style_instruction":{"type":"string","description":"Detailed style instructions, e.g. \"Flat design with solid colors, no gradients\"."}},"required":["type"],"description":"Generate a logo master plus a validated transparent version and resized exports. Native alpha is reused when valid; otherwise the transparent version removes the background. The master retains intentional backgrounds. Cost: 5 credits."},"StudioGenerateSceneBody":{"type":"object","properties":{"variant_id":{"type":"string","format":"uuid","description":"Approved mascot variant for new content. Omit for Original when creating a new pose; when editing an explicit source asset, omission preserves its saved context. Animation loops preserve the generated source pose receipt; an explicit conflicting variant returns 409 unless that variant intentionally includes the source among its references. For transitions, the two poses determine their own before/after contexts. For uploaded references without receipts, a matching selected variant resolves the context; ambiguous shared uploads return 409 before charging. List variants with GET /v1/mascots/{id}/variants. Playback activation does not change generation selection."},"name":{"type":"string","description":"Name for the new item. Required when creating a new item. Omit when passing item_id."},"item_id":{"type":"string","format":"uuid","description":"Existing item ID in this mascot. Pass this to add a new asset to an existing item, or to animate/edit its current image. For animations and edits, prefer item_id over source_image_asset_id so the API can resolve the source image from the item."},"type":{"type":"string","enum":["scene"]},"source_asset_id":{"type":"string","format":"uuid","description":"For a new scene: completed character image to use as its reference. Its saved variant context is retained unless an explicitly selected variant intentionally includes this reference. Use source_image_asset_id instead to edit an existing scene."},"scene":{"type":"string","description":"The environment, e.g. \"cozy reading nook with afternoon light\". Required unless editing (source_image_asset_id + edit_instructions)."},"action":{"type":"string","description":"What the mascot is doing in the scene, e.g. \"reading a book\". Required unless editing."},"aspect_ratio":{"type":"string","enum":["4:3","1:1","21:9","4:5","3:4","9:16"],"description":"Output aspect ratio. Use 4:3 for marketplace_card or marketplace_story, 1:1 for marketplace_square, 21:9 for hero_desktop, and 4:5 or 3:4 for hero_mobile."},"position":{"type":"string","enum":["left","center","right"],"description":"Where the mascot sits in the frame. Defaults: right for 21:9, center for others."},"source_image_asset_id":{"type":"string","format":"uuid","description":"For scene edits: existing scene asset to edit. Must be paired with edit_instructions."},"edit_instructions":{"type":"string","description":"For scene edits: what to change, e.g. \"warm up the lighting\". Paired with source_image_asset_id."}},"required":["type"],"description":"Generate a 4K scene image of the mascot in an environment, or edit an existing scene. Cost: 3 credits."},"StudioReferenceVideoBody":{"type":"object","properties":{"video_asset_id":{"type":"string","format":"uuid","description":"Owned, completed video asset containing the reference motion. Upload an MP4 or WebM with POST /v1/upload first."},"first_frame_asset_id":{"type":"string","format":"uuid","description":"Owned, completed image asset showing the first frame of the reference video. Upload it with POST /v1/upload."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Name for the animation. Start and end pose items are also created."},"prompt":{"type":"string","maxLength":10000,"description":"Optional instructions for the mascot pose and appearance."},"duration":{"type":"integer","minimum":4,"maximum":30,"default":5,"description":"Output duration in whole seconds, 4–30. Default 5. Premium costs 6 credits/sec plus 1 image credit."},"animation_model":{"type":"string","enum":["premium"],"default":"premium","description":"From Video always uses Premium. Standard is available for image-to-video animation through /generate."},"variant_id":{"type":"string","format":"uuid","description":"Optional approved mascot variant to animate."},"context_asset_id":{"type":"string","format":"uuid","description":"Optional asset in this mascot whose saved mascot context is reused when variant_id is omitted."}},"required":["video_asset_id","first_frame_asset_id","name"],"additionalProperties":false},"StudioGenerateBatchBody":{"type":"object","properties":{"requests":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/StudioGenerateImageBody"},{"$ref":"#/components/schemas/StudioGenerateAnimationBody"},{"$ref":"#/components/schemas/StudioGenerateEditBody"},{"$ref":"#/components/schemas/StudioGenerateLogoBody"},{"$ref":"#/components/schemas/StudioGenerateSceneBody"}],"discriminator":{"propertyName":"type","mapping":{"image":"#/components/schemas/GenerateImageBody","animation":"#/components/schemas/GenerateAnimationBody","edit":"#/components/schemas/GenerateEditBody","logo":"#/components/schemas/GenerateLogoBody","scene":"#/components/schemas/GenerateSceneBody"}}},"minItems":1,"maxItems":10,"description":"Up to 10 generate requests run in parallel. Each request follows the same discriminated schema as /generate. Credits are deducted per request. Talking animations (speech) are sent one by one to /generate."}},"required":["requests"]},"StudioGenerateSizeVariantsBody":{"type":"object","properties":{"sizes":{"type":"array","items":{"type":"integer","minimum":32,"maximum":1920},"description":"Sizes to generate. Defaults to the mascot's configured animation_sizes, or [360]."},"force":{"type":"boolean","description":"Regenerate even sizes that already exist. Default false (idempotent: only missing sizes, never supersedes in-flight jobs)."}}}},"parameters":{}},"paths":{"/v1/applications":{"get":{"operationId":"listApplications","summary":"List applications in the selected workspace","tags":["Applications"],"description":"Responses use Cache-Control: no-store. Application management requires the personal owner or workspace owner/admin. Existing application identities and credentials are preserved. Character playback issuance has been retired; use a backend REST key to retrieve signed canvas release delivery.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"publishable_key":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"organization_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","name","publishable_key","created_at","organization_id"]}}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Rate limited; Retry-After: 60","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"parameters":[{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]},"post":{"operationId":"createApplication","summary":"Create an application and publishable key","tags":["Applications"],"description":"Responses use Cache-Control: no-store. Application management requires the personal owner or workspace owner/admin. Existing application identities and credentials are preserved. Character playback issuance has been retired; use a backend REST key to retrieve signed canvas release delivery.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"publishable_key":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"organization_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","name","publishable_key","created_at","organization_id"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Rate limited; Retry-After: 60","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/applications/{id}":{"get":{"operationId":"getApplication","summary":"Read application keys","tags":["Applications"],"description":"Responses use Cache-Control: no-store. Application management requires the personal owner or workspace owner/admin. Existing application identities and credentials are preserved. Character playback issuance has been retired; use a backend REST key to retrieve signed canvas release delivery.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"publishable_key":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key_prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","key_prefix","created_at"]}}},"required":["id","name","publishable_key","created_at","organization_id","keys"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Rate limited; Retry-After: 60","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}}}},"/v1/applications/{id}/keys":{"post":{"operationId":"createApplicationKey","summary":"Create a backend secret, returned only once","tags":["Applications"],"description":"Responses use Cache-Control: no-store. Application management requires the personal owner or workspace owner/admin. Existing application identities and credentials are preserved. Character playback issuance has been retired; use a backend REST key to retrieve signed canvas release delivery.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key_prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"secret_key":{"type":"string"}},"required":["id","key_prefix","created_at","secret_key"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Rate limited; Retry-After: 60","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Request denied or unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}}}},"/v1/canvases":{"get":{"operationId":"listProjectCanvases","tags":["Canvases"],"summary":"List independently owned project canvases","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"project_id","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["canvas"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","project_id","mascot_id","name","graph","graph_content_hash","created_at","updated_at"]}}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Lists the canvases of one project, newest first. `project_id` is required. Without `limit`, `offset` or `cursor` every canvas is returned; with them, results are paged like other lists.","x-masko-api-version":"2026-09-26"},"post":{"operationId":"createProjectCanvas","tags":["Canvases"],"summary":"Create a project canvas with an initial mascot reference","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid"},"mascot_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"variant_id":{"type":"string","format":"uuid"}},"required":["project_id","mascot_id","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","enum":["canvas"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","project_id","mascot_id","name","graph","graph_content_hash","created_at","updated_at"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Creates an empty draft canvas in a project, bound to a mascot you own or acquired from Marketplace. Send `project_id`, `mascot_id` and `name`; optional `variant_id` selects the appearance. Save the graph next with `PATCH /v1/canvases/{canvasId}`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}":{"get":{"operationId":"getProjectCanvas","tags":["Canvases"],"summary":"Read a canvas by its own project access","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","enum":["canvas"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","project_id","mascot_id","name","graph","graph_content_hash","created_at","updated_at"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Returns the canvas draft: `graph` and its revision `graph_content_hash`. Send that hash as `expected_graph_hash` when you save. For generation progress use `GET /v1/canvases/{canvasId}/status`.","x-masko-api-version":"2026-09-26"},"patch":{"operationId":"updateProjectCanvas","tags":["Canvases"],"summary":"Save a draft with optimistic concurrency","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"graph":{"type":"object","additionalProperties":{"nullable":true}},"expected_graph_hash":{"type":"string","minLength":1}},"required":["graph","expected_graph_hash"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","enum":["canvas"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","project_id","mascot_id","name","graph","graph_content_hash","created_at","updated_at"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Replaces the whole graph. Send the latest `graph_content_hash` as `expected_graph_hash`; if the canvas changed since you read it, the request returns 409 and you should read it again.","x-masko-api-version":"2026-09-26"},"delete":{"operationId":"deleteProjectCanvas","tags":["Canvases"],"summary":"Delete a canvas without retained history","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"204":{"description":"Deleted","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Deletes a canvas that has no saved checkpoints or releases. A canvas with history returns 409.","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/status":{"get":{"operationId":"getProjectCanvasStatus","tags":["Canvases"],"summary":"Read canvas generation progress","description":"Generation progress for a canvas. Poll it every 15 to 30 seconds after `POST /v1/canvases/{canvasId}/generate-all`. Read-only keys can call it, and it never changes the canvas. `status.generation.nodes` and `status.generation.edges` count total, completed, pending and failed parts. Pending means neither finished nor failed. Stop polling when `status.generation.ready` is true: every node image and edge video exists. The canvas plays in the editor once `status.preview.ready` is also true. If `status.preview.waiting_edges` is above 0, keep polling because derivatives are still being prepared. If `status.preview.repairable` is true, call `POST /v1/canvases/{canvasId}/repair` with `dry_run: true` first. If any `failed` count is above 0, read `status.failed_nodes` and `status.failed_edges`. Each entry has the part id, its `job_id` and a customer-safe `error`. A retry is a new paid attempt, so ask before retrying. Returns 409 when the canvas has no mascot generation context.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","enum":["canvas_status"]},"canvas_id":{"type":"string","format":"uuid"},"graph_content_hash":{"type":"string"},"status":{"type":"object","properties":{"generation":{"type":"object","properties":{"ready":{"type":"boolean"},"nodes":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number","description":"Incomplete node count. Includes failed nodes for backward compatibility; inspect failed for the terminal subset."},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]},"edges":{"type":"object","properties":{"total":{"type":"number"},"completed":{"type":"number"},"pending":{"type":"number"},"failed":{"type":"number"}},"required":["total","completed","pending","failed"]}},"required":["ready","nodes","edges"]},"preview":{"type":"object","properties":{"ready":{"type":"boolean"},"repairable":{"type":"boolean"},"repairable_edges":{"type":"number"},"waiting_edges":{"type":"number"},"missing_edges":{"type":"number"},"missing_formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["ready","repairable","repairable_edges","waiting_edges","missing_edges","missing_formats"]},"variants":{"type":"object","properties":{"sizes":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"object","properties":{"edge_id":{"type":"string"},"size":{"type":"string"},"formats":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["edge_id","size","formats"]}}},"required":["sizes","missing"]},"failed_nodes":{"type":"array","items":{"type":"object","properties":{"node_id":{"type":"string"},"job_id":{"type":"string","nullable":true,"format":"uuid"},"error":{"type":"string"}},"required":["node_id","job_id","error"]}},"failed_edges":{"type":"array","items":{"type":"object","properties":{"edge_id":{"type":"string"},"job_id":{"type":"string","nullable":true,"format":"uuid"},"error":{"type":"string"}},"required":["edge_id","job_id","error"]}},"edge_media":{"type":"array","items":{"type":"object","properties":{"edge_id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"video_asset_id":{"type":"string","nullable":true,"format":"uuid"},"reuses_edge_id":{"type":"string"},"base":{"type":"object","properties":{"video_ready":{"type":"boolean"},"webm_ready":{"type":"boolean"},"hevc_ready":{"type":"boolean"},"preview_ready":{"type":"boolean"},"derivatives_in_flight":{"type":"boolean"},"source_job_id":{"type":"string","format":"uuid"},"source_job_status":{"type":"string"},"missing":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["video_ready","webm_ready","hevc_ready","preview_ready","derivatives_in_flight","missing"]},"variants":{"type":"object","additionalProperties":{"type":"object","properties":{"webm_ready":{"type":"boolean"},"hevc_ready":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string","enum":["webm","hevc"]}}},"required":["webm_ready","hevc_ready","missing"]}}},"required":["edge_id","source","target","video_asset_id","base","variants"]}}},"required":["generation","preview","variants","failed_nodes","failed_edges"]}},"required":["object","canvas_id","graph_content_hash","status"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/history":{"get":{"operationId":"getCanvasHistory","tags":["Canvases"],"summary":"Read draft, named checkpoints and immutable releases","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"draft":{"type":"object","properties":{"object":{"type":"string","enum":["canvas"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","project_id","mascot_id","name","graph","graph_content_hash","created_at","updated_at"]},"checkpoints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"canvas_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string"}},"required":["id","canvas_id","name","graph","graph_content_hash","created_by","created_at"]}},"releases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"canvas_id":{"type":"string","format":"uuid"},"number":{"type":"integer"},"notes":{"type":"string"},"mascot_version_id":{"type":"string","format":"uuid"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string"}},"required":["id","canvas_id","number","notes","mascot_version_id","created_by","created_at"],"additionalProperties":{"nullable":true}}}},"required":["draft","checkpoints","releases"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Returns the current draft, named checkpoints and immutable releases of a canvas.","x-masko-api-version":"2026-09-26"},"post":{"operationId":"changeCanvasHistory","tags":["Canvases"],"summary":"Save a checkpoint, restore as draft, or create a release","description":"Restore atomically checkpoints current work first. No generation is run. A release requires complete media and does not activate Desktop or publish a listing.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","enum":["checkpoint"]},"name":{"type":"string","minLength":1,"maxLength":120},"expected_graph_hash":{"type":"string","minLength":1}},"required":["action","name","expected_graph_hash"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["restore"]},"checkpoint_id":{"type":"string","format":"uuid"},"expected_graph_hash":{"type":"string","minLength":1}},"required":["action","checkpoint_id","expected_graph_hash"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["restore_release"]},"release_id":{"type":"string","format":"uuid"},"expected_graph_hash":{"type":"string","minLength":1}},"required":["action","release_id","expected_graph_hash"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["copy_release"]},"release_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"expected_graph_hash":{"type":"string","minLength":1}},"required":["action","release_id","name","expected_graph_hash"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["release"]},"notes":{"type":"string","maxLength":4000,"default":""},"operation_id":{"type":"string","format":"uuid"},"expected_graph_hash":{"type":"string","minLength":1}},"required":["action","operation_id","expected_graph_hash"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"canvas_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string"}},"required":["id","canvas_id","name","graph","graph_content_hash","created_by","created_at"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"canvas_id":{"type":"string","format":"uuid"},"number":{"type":"integer"},"notes":{"type":"string"},"mascot_version_id":{"type":"string","format":"uuid"},"created_by":{"type":"string","format":"uuid"},"created_at":{"type":"string"}},"required":["id","canvas_id","number","notes","mascot_version_id","created_by","created_at"],"additionalProperties":{"nullable":true}},{"type":"object","properties":{"object":{"type":"string","enum":["canvas"]},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"mascot_id":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"graph":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"graph_content_hash":{"type":"string"},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","project_id","mascot_id","name","graph","graph_content_hash","created_at","updated_at"]}]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/publication":{"get":{"operationId":"getMascotPublication","tags":["Mascots"],"summary":"Read selected customer publication and review status","description":"Customer publication is separate from CDN hosting. GET state is null until action:start. state.visibility (unpublished/published/archived) is independent of state.changes_status (draft/pending/approved/rejected). save_draft requires the current draft_id and accepts incomplete listing details. Preview and submit require an editable draft; all submissions, including admin submissions, enter pending review. The project workspace owns the seller identity. GET includes seller with exactly one of user_id or organization_id and can_publish (whether this viewer may manage publication). Team owners/admins manage publishing; submission also retains the existing creator eligibility requirement. A team listing uses the team profile and credits earnings to the team wallet. The submitting member is recorded separately. Marketplace submissions require a handle on the selling workspace profile. Approval and restore enforce this rule, and a creator cannot make their profile private or unlisted while a library is published. Pending changes leave approved media, price and description unchanged. Approval atomically replaces the selected content; rejection preserves the draft and approved version. archive stops new acquisition; restore republishes only the approved version. Archiving during review prevents approval from making the listing visible. Submitting while archived requests publication after approval. remove stages a draft change and never modifies the live listing directly. Existing buyers retain acquired content. Preview returns plan_id, valid for ten minutes. Submit requires that plan and fails with 409 if source context or dependencies changed. Review uses the frozen submission. Removing discovery preserves retained uses. Marketplace offers require at least one generated image on the mascot and a selection containing at least one image and five animations. Optional offer.cover_asset_id selects an included gallery image as the listing thumbnail; videos and exports are rejected. If omitted, an included generated image is preferred automatically, otherwise the first included image. Include at least one image. The mascot name is frozen at submission and changes publicly only after approval; display names need not be unique. Delivery formats are grouped under gallery assets; GET includes signed transparent_url, webm_url and hevc_url when available, plus has_generated_image.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"owner":{"type":"boolean","enum":[true]},"seller":{"anyOf":[{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"organization_id":{"nullable":true},"can_publish":{"type":"boolean"}},"required":["user_id","organization_id","can_publish"],"additionalProperties":false},{"type":"object","properties":{"user_id":{"nullable":true},"organization_id":{"type":"string","format":"uuid"},"can_publish":{"type":"boolean"}},"required":["user_id","organization_id","can_publish"],"additionalProperties":false}]}},"required":["owner","seller"],"additionalProperties":{"nullable":true}}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-masko-api-version":"2026-09-26"},"post":{"operationId":"changeMascotPublication","tags":["Mascots"],"summary":"Start, edit, review, archive or restore a mascot listing","description":"Customer publication is separate from CDN hosting. GET state is null until action:start. state.visibility (unpublished/published/archived) is independent of state.changes_status (draft/pending/approved/rejected). save_draft requires the current draft_id and accepts incomplete listing details. Preview and submit require an editable draft; all submissions, including admin submissions, enter pending review. The project workspace owns the seller identity. GET includes seller with exactly one of user_id or organization_id and can_publish (whether this viewer may manage publication). Team owners/admins manage publishing; submission also retains the existing creator eligibility requirement. A team listing uses the team profile and credits earnings to the team wallet. The submitting member is recorded separately. Marketplace submissions require a handle on the selling workspace profile. Approval and restore enforce this rule, and a creator cannot make their profile private or unlisted while a library is published. Pending changes leave approved media, price and description unchanged. Approval atomically replaces the selected content; rejection preserves the draft and approved version. archive stops new acquisition; restore republishes only the approved version. Archiving during review prevents approval from making the listing visible. Submitting while archived requests publication after approval. remove stages a draft change and never modifies the live listing directly. Existing buyers retain acquired content. Preview returns plan_id, valid for ten minutes. Submit requires that plan and fails with 409 if source context or dependencies changed. Review uses the frozen submission. Removing discovery preserves retained uses. Marketplace offers require at least one generated image on the mascot and a selection containing at least one image and five animations. Optional offer.cover_asset_id selects an included gallery image as the listing thumbnail; videos and exports are rejected. If omitted, an included generated image is preferred automatically, otherwise the first included image. Include at least one image. The mascot name is frozen at submission and changes publicly only after approval; display names need not be unique. Delivery formats are grouped under gallery assets; GET includes signed transparent_url, webm_url and hevc_url when available, plus has_generated_image.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","enum":["start"]}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["save_draft"]},"draft_id":{"type":"string","format":"uuid"},"selection":{"type":"object","properties":{"asset_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":500},"identity_ids":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"asset_identity_ids":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":2}},"offer":{"type":"object","properties":{"cover_asset_id":{"type":"string","format":"uuid","description":"Included image used as the listing thumbnail; animations and exports are not supported."},"price_credits":{"type":"integer","minimum":0,"maximum":100000},"description":{"type":"string","maxLength":2000},"accept_creator_terms":{"type":"boolean"}},"required":["price_credits","description"],"additionalProperties":false}},"required":["asset_ids","identity_ids"],"additionalProperties":false}},"required":["action","draft_id","selection"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["archive"]}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["restore"]}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["withdraw"]}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["preview"]},"selection":{"type":"object","properties":{"asset_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":500},"identity_ids":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"asset_identity_ids":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":2}},"offer":{"type":"object","properties":{"cover_asset_id":{"type":"string","format":"uuid","description":"Included image used as the listing thumbnail; animations and exports are not supported."},"price_credits":{"type":"integer","minimum":0,"maximum":100000},"description":{"type":"string","maxLength":2000},"accept_creator_terms":{"type":"boolean","enum":[true]}},"required":["price_credits","accept_creator_terms"],"additionalProperties":false}},"required":["asset_ids","identity_ids"],"additionalProperties":false}},"required":["action","selection"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["submit"]},"selection":{"type":"object","properties":{"asset_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":500},"identity_ids":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100},"asset_identity_ids":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":2}},"offer":{"type":"object","properties":{"cover_asset_id":{"type":"string","format":"uuid","description":"Included image used as the listing thumbnail; animations and exports are not supported."},"price_credits":{"type":"integer","minimum":0,"maximum":100000},"description":{"type":"string","maxLength":2000},"accept_creator_terms":{"type":"boolean","enum":[true]}},"required":["price_credits","accept_creator_terms"],"additionalProperties":false}},"required":["asset_ids","identity_ids"],"additionalProperties":false},"plan_id":{"type":"string","format":"uuid"}},"required":["action","selection","plan_id"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["remove"]},"kind":{"type":"string","enum":["identity","asset"]},"resource_id":{"type":"string","minLength":1}},"required":["action","kind","resource_id"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","enum":["duplicate"]},"variant":{"type":"object","properties":{"identity_id":{"type":"string","minLength":1},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":100}},"required":["identity_id","project_id","name"],"additionalProperties":false}},"required":["action","variant"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/duplicate":{"post":{"operationId":"duplicateMascotIdentity","tags":["Mascots"],"summary":"Copy Original or a variant without generation or a canvas","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"identity_id":{"type":"string","minLength":1},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":80}},"required":["identity_id","project_id","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"nullable":true}}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Copies the Original appearance or a variant into a new variant without generating anything and without a canvas.","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/releases/{releaseId}/delivery":{"get":{"operationId":"getCanvasReleaseDelivery","tags":["Canvases"],"summary":"Get signed playback media for one immutable release","description":"Call from your backend with its API key and forward only delivery to website visitors. This response contains no authoring credentials, generation context or private identity references. Creating a release does not activate it.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"releaseId","in":"path"},{"schema":{"type":"string","enum":["web","desktop"],"default":"web"},"required":false,"name":"target","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"release_id":{"type":"string","format":"uuid"},"number":{"type":"integer"},"delivery":{"type":"object","additionalProperties":{"nullable":true}}},"required":["release_id","number","delivery"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/published-library":{"get":{"operationId":"getPublishedMascotLibrary","description":"Requires a library license owned by the credential workspace, or a mascot authored in that workspace. A personal purchase does not grant an organization license. Organization purchases are shared with current members only within that organization. Retained purchase content is scoped to the same owner.","tags":["Mascots"],"summary":"Read approved content through a project in the credential workspace","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"project_id","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"mascot_id":{"type":"string","format":"uuid"},"content":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["mascot_id","content"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid input","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write key required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found in credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Revision conflict or retained history","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required release media unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-masko-api-version":"2026-09-26"}},"/v1/auth/device":{"post":{"operationId":"createCLIDeviceGrant","tags":["Authentication"],"summary":"Start device authorization for Masko CLI (remote terminals)","description":"No bearer required. Show user_code and verification_uri_complete, then poll auth/token at interval seconds. Codes expire after 600 seconds. Explicit signed-in browser approval selects the workspace. Uses the Masko JSON envelope and device-grant semantics, not form-encoded OAuth transport.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","enum":["masko-cli"]},"device_name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\u0000-\\u001f\\u007f]+$"},"scope":{"type":"string","enum":["read","write"],"default":"write"}},"required":["client_id","device_name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success. Cache-Control: no-store.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"number"},"interval":{"type":"number"}},"required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation or device-grant state error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"429":{"description":"Rate limited.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication service unavailable.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/token":{"post":{"operationId":"exchangeCLIToken","tags":["Authentication"],"summary":"Exchange a PKCE authorization code, poll a device code, or rotate a CLI refresh token","description":"No bearer required. For authorization_code, send code, exact redirect_uri, and the original code_verifier; S256 must match the approved challenge. Codes expire after 120 seconds and are single-use. For device grants: authorization_pending: continue polling; slow_down: add 5 seconds to every subsequent interval; access_denied, expired_token, invalid_grant: stop. Access tokens last 900 seconds. Refresh tokens rotate once per use; reuse revokes the session. Serialize refreshes and save the returned pair atomically. Sessions expire after 90 days. Never log tokens.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"client_id":{"type":"string","enum":["masko-cli"]},"grant_type":{"type":"string","enum":["authorization_code"]},"code":{"type":"string","pattern":"^masko_ac_[a-f0-9]{64}$"},"redirect_uri":{"type":"string","maxLength":200,"format":"uri"},"code_verifier":{"type":"string","pattern":"^[A-Za-z0-9._~-]{43,128}$"}},"required":["client_id","grant_type","code","redirect_uri","code_verifier"],"additionalProperties":false},{"type":"object","properties":{"client_id":{"type":"string","enum":["masko-cli"]},"grant_type":{"type":"string","enum":["urn:ietf:params:oauth:grant-type:device_code"]},"device_code":{"type":"string","pattern":"^masko_dc_[a-f0-9]{64}$"}},"required":["client_id","grant_type","device_code"],"additionalProperties":false},{"type":"object","properties":{"client_id":{"type":"string","enum":["masko-cli"]},"grant_type":{"type":"string","enum":["refresh_token"]},"refresh_token":{"type":"string","pattern":"^masko_rt_[a-f0-9]{64}$"}},"required":["client_id","grant_type","refresh_token"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"Success. Cache-Control: no-store.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"},"session_id":{"type":"string","format":"uuid"},"session_expires_at":{"type":"string"}},"required":["access_token","refresh_token","token_type","expires_in","session_id","session_expires_at"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation or device-grant state error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"429":{"description":"Rate limited.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication service unavailable.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/revoke":{"post":{"operationId":"revokeCLISession","tags":["Authentication"],"summary":"End a CLI browser session using its refresh token","description":"Idempotent. Ends access immediately. Does not revoke API keys or other installations.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refresh_token":{"type":"string","pattern":"^masko_rt_[a-f0-9]{64}$"}},"required":["refresh_token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success. Cache-Control: no-store.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revoked":{"type":"boolean"}},"required":["revoked"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation or device-grant state error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"429":{"description":"Rate limited.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Authentication service unavailable.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/session":{"get":{"operationId":"getAuthSession","tags":["Authentication"],"summary":"Identify the account, workspace, and credential in use","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Authenticated identity.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"email":{"type":"string"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"permissions":{"type":"string","enum":["read","write","admin"]},"method":{"type":"string","enum":["browser","api_key"]},"session_id":{"type":"string","nullable":true,"format":"uuid"}},"required":["user_id","organization_id","permissions","method","session_id"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Expired, revoked, or missing credential.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Restricted credential.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Account unavailable.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"description":"Returns the account, workspace and credential that authenticated this request. Use it to check which key an integration is using."}},"/v1/auth/config":{"get":{"operationId":"getCLIAuthConfig","tags":["Authentication"],"summary":"Discover Masko CLI browser authorization","security":[],"description":"The registered masko-cli client opens authorization_endpoint with response_type=code, client_id=masko-cli, device_name, scope read/write, redirect_uri, state, code_challenge, and code_challenge_method=S256. Only http://127.0.0.1:PORT/oauth/callback with port 1024..65535 is accepted. Use independent random verifier and state values with at least 32 random bytes; state is echoed and must be checked by the CLI. Browser sign-in and explicit workspace approval return a one-time code, never access or refresh tokens. This is Masko JSON transport, not general OAuth server discovery.","responses":{"200":{"description":"Configuration. Cache-Control: no-store.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"authorization_endpoint":{"type":"string","format":"uri"},"code_challenge_methods_supported":{"type":"array","items":{"type":"string","enum":["S256"]}},"grant_types_supported":{"type":"array","items":{"type":"string","enum":["authorization_code","urn:ietf:params:oauth:grant-type:device_code","refresh_token"]}}},"required":["authorization_endpoint","code_challenge_methods_supported","grant_types_supported"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}}}},"/v1/collections/{id}/canvases/{canvasId}/validate":{"get":{"tags":["Canvases"],"summary":"Validate the stored canvas graph","description":"Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. GET requires read access. A structurally invalid graph still returns 200 with data.valid=false.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"200":{"description":"Graph validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"code":{"type":"string"},"message":{"type":"string"},"nodeId":{"type":"string"},"edgeId":{"type":"string"}},"required":["severity","code","message"]}},"summary":{"type":"object","properties":{"errors":{"type":"number"},"warnings":{"type":"number"}},"required":["errors","warnings"]}},"required":["valid","issues","summary"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Missing or invalid credential.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient credential permissions.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection or canvas not found in this workspace.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Validation could not be completed.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyGetCollectionCanvasValidate"},"post":{"tags":["Canvases"],"summary":"Validate the stored canvas graph","description":"Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. POST requires write access and accepts no body; prefer GET for read-only checks. A structurally invalid graph still returns 200 with data.valid=false.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Graph validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"code":{"type":"string"},"message":{"type":"string"},"nodeId":{"type":"string"},"edgeId":{"type":"string"}},"required":["severity","code","message"]}},"summary":{"type":"object","properties":{"errors":{"type":"number"},"warnings":{"type":"number"}},"required":["errors","warnings"]}},"required":["valid","issues","summary"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Missing or invalid credential.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient credential permissions.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection or canvas not found in this workspace.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Validation could not be completed.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyValidateCollectionCanvas"}},"/v1/canvases/{canvasId}/generation-estimate":{"get":{"operationId":"estimateCanvasGeneration","tags":["Canvases"],"summary":"Estimate canvas generation without starting jobs","description":"Read-only cost and work preview. Accepts read or write credentials in the canvas workspace. Always runs a dry run without charging credits, creating jobs or changing the graph. Returns estimated_cost, planned_jobs, plan_id and graph_content_hash. After approval, send identical options and the returned plan identifiers to POST /v1/canvases/{canvasId}/generate-all using a write credential.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string","default":"{}","description":"URL-encoded JSON object with animation_model (standard or premium, default standard), duration (default 5; standard 5–15, premium 4–30), targets, include_stickers, skip_completed, and optional node_ids or edge_ids arrays. Execution controls such as dry_run, approved_plan_id and max_credits are rejected. This endpoint always estimates only."},"required":false,"description":"URL-encoded JSON object with animation_model (standard or premium, default standard), duration (default 5; standard 5–15, premium 4–30), targets, include_stickers, skip_completed, and optional node_ids or edge_ids arrays. Execution controls such as dry_run, approved_plan_id and max_credits are rejected. This endpoint always estimates only.","name":"options","in":"query"}],"responses":{"200":{"description":"Read-only generation plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasGenerateAllResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid options or canvas selection","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential is not allowed to use the public API","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Canvas or mascot not found in the credential workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Canvas has no mascot generation context","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-masko-api-version":"2026-09-26"}},"/v1/credit-checkouts":{"post":{"operationId":"createCreditCheckout","tags":["Credits"],"summary":"Create a hosted Stripe checkout for credits","description":"Creates a payment link, not a charge. Requires write permission and an Idempotency-Key. Uses only the credential workspace; team purchases require the active owner. Amount is USD before checkout taxes and discounts. No payment data is accepted. Reuse identical inputs and the same key after an uncertain result. Successful responses replay for 24 hours; the checkout URL can expire sooner. Only a verified successful payment webhook grants credits.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount_cents":{"type":"integer","minimum":1000,"maximum":1000000,"description":"USD purchase amount in whole cents, from $10 to $10,000, before checkout taxes or discounts. Workspace comes from authentication."}},"required":["amount_cents"],"additionalProperties":false}}}},"responses":{"201":{"description":"Hosted checkout; no payment taken","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","maxLength":255,"pattern":"^cs_(?:test_|live_)?[A-Za-z0-9]+$"},"url":{"type":"string","format":"uri"},"amount_cents":{"type":"integer"},"currency":{"type":"string","enum":["usd"]},"credits":{"type":"integer"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"expires_at":{"type":"integer"},"status_url":{"type":"string"}},"required":["id","url","amount_cents","currency","credits","organization_id","expires_at","status_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid input or missing Idempotency-Key","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write permission or active team ownership required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Checkout not found for this user and workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency key reused with different input or request still in progress","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Checkout provider or database unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Idempotency receipt unavailable; retry only with the same key","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/credit-checkouts/{id}":{"get":{"operationId":"getCreditCheckout","tags":["Credits"],"summary":"Read payment and credit delivery status","description":"Read-only. Only the creating user in the same credential workspace may read the checkout; team ownership must still be active. A paid session does not guarantee credits have been delivered yet. credits_added is true only when the credit ledger contains the matching grant. Does not grant credits or return customer/payment credentials.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"pattern":"^cs_(?:test_|live_)?[A-Za-z0-9]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment and credit delivery status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","maxLength":255,"pattern":"^cs_(?:test_|live_)?[A-Za-z0-9]+$"},"status":{"type":"string","nullable":true,"enum":["open","complete","expired",null]},"payment_status":{"type":"string","enum":["paid","unpaid","no_payment_required"]},"credits":{"type":"integer"},"credits_added":{"type":"boolean"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"balance":{"type":"number"},"amount_total":{"type":"integer","nullable":true},"currency":{"type":"string","nullable":true}},"required":["id","status","payment_status","credits","credits_added","organization_id","balance","amount_total","currency"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid input or missing Idempotency-Key","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write permission or active team ownership required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Checkout not found for this user and workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency key reused with different input or request still in progress","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Checkout provider or database unavailable","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Idempotency receipt unavailable; retry only with the same key","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/credit-payments":{"post":{"operationId":"createCreditPayment","tags":["Credits"],"summary":"Test a direct Shared Payment Token credit purchase (local sandbox only)","description":"Unavailable in production. Requires explicit sandbox configuration and local Supabase. Attempts a test payment using a payer-issued SPT and the same USD base credit pricing as Checkout; no taxes or discounts are calculated. Requires write permission and Idempotency-Key; team purchases require active ownership. Workspace comes from authentication. The caller must obtain user approval for this exact purchase before submitting the token over HTTPS (HTTP only on localhost). Never put payment tokens in prompts or URLs. Only the dedicated signature-verified sandbox webhook grants credits. This is not MPP, a Muse-specific payment contract, or a Managed Payments integration. Never retry an uncertain outcome with a new key or token.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount_cents":{"type":"integer","minimum":1000,"maximum":1000000,"description":"USD purchase amount in whole cents, from $10 to $10,000, before checkout taxes or discounts. Workspace comes from authentication."},"shared_payment_token":{"type":"string","maxLength":255,"pattern":"^spt_[A-Za-z0-9_]+$","description":"Sandbox Shared Payment Token issued by the payer wallet for this approved purchase. Never put it in a prompt, URL, log or saved card field."}},"required":["amount_cents","shared_payment_token"],"additionalProperties":false}}}},"responses":{"201":{"description":"Sandbox payment status; credits_added is backed by the ledger","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["requires_payment_method","requires_confirmation","requires_action","processing","requires_capture","canceled","succeeded"]},"amount_cents":{"type":"integer"},"currency":{"type":"string","enum":["usd"]},"credits":{"type":"integer"},"credits_added":{"type":"boolean"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"livemode":{"type":"boolean","enum":[false]},"status_url":{"type":"string"}},"required":["id","status","amount_cents","currency","credits","credits_added","organization_id","livemode","status_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"202":{"description":"Sandbox payment status; credits_added is backed by the ledger","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["requires_payment_method","requires_confirmation","requires_action","processing","requires_capture","canceled","succeeded"]},"amount_cents":{"type":"integer"},"currency":{"type":"string","enum":["usd"]},"credits":{"type":"integer"},"credits_added":{"type":"boolean"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"livemode":{"type":"boolean","enum":[false]},"status_url":{"type":"string"}},"required":["id","status","amount_cents","currency","credits","credits_added","organization_id","livemode","status_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid input or missing Idempotency-Key","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write permission or active team ownership required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Payment or token not found in this account/workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Operation conflict or unconfirmed execution","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Token rejected or payment needs unsupported customer action","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Invalid payment record","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Sandbox disabled, provider unavailable, or payment outcome unknown","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/credit-payments/{id}":{"get":{"operationId":"getCreditPayment","tags":["Credits"],"summary":"Read a sandbox token payment and credit delivery status","description":"Unavailable in production. Read-only; never grants credits. Requires the creating user and exact workspace, with active ownership for teams. Returns no token, client secret, payment method or customer information. A succeeded payment can precede webhook credit delivery. This endpoint uses the dedicated sandbox Stripe account, never the existing live Checkout client.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255,"pattern":"^pi_[A-Za-z0-9]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Sandbox payment status; credits_added is backed by the ledger","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["requires_payment_method","requires_confirmation","requires_action","processing","requires_capture","canceled","succeeded"]},"amount_cents":{"type":"integer"},"currency":{"type":"string","enum":["usd"]},"credits":{"type":"integer"},"credits_added":{"type":"boolean"},"organization_id":{"type":"string","nullable":true,"format":"uuid"},"livemode":{"type":"boolean","enum":[false]},"status_url":{"type":"string"}},"required":["id","status","amount_cents","currency","credits","credits_added","organization_id","livemode","status_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid input or missing Idempotency-Key","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Write permission or active team ownership required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Payment or token not found in this account/workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Operation conflict or unconfirmed execution","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Token rejected or payment needs unsupported customer action","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Invalid payment record","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Sandbox disabled, provider unavailable, or payment outcome unknown","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/collections/{id}/variants":{"get":{"operationId":"legacyListCollectionVariants","tags":["Collections"],"summary":"List named mascot variants","description":"Lists the collection’s named generation contexts. Variant authoring follows collection project permissions, including authorized teammates; API keys must match the collection workspace. Create and approve variants through the API or web app, then pass the id as variant_id to /generate. Selecting a generation variant does not change active playback. A null approved_at means the variant is still a draft.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Variants in creation order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MascotVariant"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"has_more":{"type":"boolean"}},"required":["total","limit","offset","has_more"]}},"required":["pagination"]}},"required":["data","meta"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot not found in this workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true},"post":{"operationId":"legacyCreateCollectionVariant","tags":["Collections"],"summary":"Create a named mascot variant","description":"Creates a draft from Original or source_variant_id. The source context and references are frozen. Supply reference_asset_id to use an existing collection image or your unassigned /v1/upload image and immediately approve the context, with no generation charge. Otherwise generate and approve a reference next. Reuse id for retries with the same inputs. This does not activate playback.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMascotVariantBody"}}}},"responses":{"201":{"description":"Created variant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MascotVariant"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true}},"/v1/collections/{id}/variants/{variantId}":{"get":{"operationId":"legacyGetCollectionVariant","tags":["Collections"],"summary":"Read a variant and its reference candidates","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"responses":{"200":{"description":"Variant and candidate previews","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MascotVariantDetail"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"description":"Returns one variant with its reference candidates and approval state."}},"/v1/collections/{id}/variants/{variantId}/reference":{"post":{"operationId":"legacyCreateCollectionVariantReference","tags":["Collections"],"summary":"Generate a draft variant reference","description":"Costs 1 credit. Uses the frozen source references and the requested variant description. Reuse operation_id to retry the same job. Poll the job, inspect candidates with GET variant, then approve the selected candidate.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateVariantReferenceBody"}}}},"responses":{"202":{"description":"Reference generation queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"candidate_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"estimated_cost":{"type":"number"},"poll_url":{"type":"string"}},"required":["job_id","candidate_id","variant_id","estimated_cost","poll_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Not enough credits","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true}},"/v1/collections/{id}/variants/{variantId}/approve":{"post":{"operationId":"legacyApproveCollectionVariant","tags":["Collections"],"summary":"Approve a generated variant reference","description":"Select a completed candidate belonging to this variant. Creates its canvas and makes variant_id usable for generation. Does not generate poses or change active playback. Repeating approval of the same candidate is safe.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveMascotVariantBody"}}}},"responses":{"200":{"description":"Approved variant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MascotVariant"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Collection, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true}},"/v1/collections/{id}/interactive":{"post":{"operationId":"legacyCreateCollectionInteractive","tags":["Generate"],"summary":"Generate a follow-cursor interaction","description":"Creates nine 1024×1024 transparent gaze directions from one completed image. Requires a completed transparent source or transparent derivative in the same collection. Preserves the source variant automatically; no variant_id override. Optional name (maximum 60 characters after trimming) labels only the interaction; omitted or blank names use the source image name without renaming the image. Costs 9 credits. Returns an asynchronous job receipt. Send once and poll the returned job URL; repeating POST creates and charges a new set. Hosted collections automatically publish a JSON manifest and nine lossless WebPs. Retrieve them with GET /v1/collections/{id}/cdn-export after completion. This interaction is independent of Canvas state machines.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInteractionBody"}}}},"responses":{"202":{"description":"Nine-direction generation queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionGenerationResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Write access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Collection or completed source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"422":{"description":"Transparent image required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"500":{"description":"Could not queue generation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true}},"/v1/logo-styles":{"get":{"operationId":"listLogoStyles","tags":["Styles"],"summary":"List logo style presets","description":"Nine logo treatments shared with the dashboard, including preview URLs and full instructions. Use id as logo_style_id when generating a logo. No credit cost.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Logo styles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["graphic-app-icon","cut-paper","soft-depth","geometric","abstract-symbol","monoline-symbol","negative-space","retro-emblem","hand-drawn"]},"name":{"type":"string"},"description":{"type":"string"},"instruction":{"type":"string"},"preview_url":{"type":"string"}},"required":["id","name","description","instruction","preview_url"]}}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Write access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Source or collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Request ID conflict or variant not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"503":{"description":"Generation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}}}},"/v1/collections/{id}/logos/suggestions":{"get":{"operationId":"legacyListCollectionLogoSuggestions","tags":["Suggestions"],"summary":"Suggest logo directions and styles","description":"Five directions, including face portrait and full body, plus three suggested styles. Each direction can include a style. A style can be custom; preset_id is present only when it exactly matches a built-in preset. Returns defaults if generation is unavailable, unless refresh=true, which returns 503. No image credits; does not change the collection.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"variant_id","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"refresh","in":"query"}],"responses":{"200":{"description":"Logo ideas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"prompt_version":{"type":"number"},"cached":{"type":"boolean"},"descriptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"style":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"instruction":{"type":"string"},"preset_id":{"type":"string","enum":["graphic-app-icon","cut-paper","soft-depth","geometric","abstract-symbol","monoline-symbol","negative-space","retro-emblem","hand-drawn"]}},"required":["name","instruction"]}},"required":["name","description"]}},"styles":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"instruction":{"type":"string"},"preset_id":{"type":"string","enum":["graphic-app-icon","cut-paper","soft-depth","geometric","abstract-symbol","monoline-symbol","negative-space","retro-emblem","hand-drawn"]}},"required":["name","instruction"]}}},"required":["prompt_version","cached","descriptions","styles"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Write access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Source or collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Request ID conflict or variant not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"503":{"description":"Generation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true}},"/v1/assets/{id}/svg":{"post":{"operationId":"generateAssetSvg","tags":["Assets"],"summary":"Generate an SVG from a selected image or logo","description":"Creates an editable vector derivative from this exact completed image, transparent image or sticker, attached to the same item. Uses the highest-quality configured vector model. Costs 30 credits; failures refund charged credits. Async: poll the returned job URL. Generation can take several minutes. Reuse request_id to retry the same submission without another charge; a new ID starts a new paid attempt. SVG details can differ from the source. Published logo items expose the newest completed vector at logos.svg in cdn-export. Download via the returned asset file_url or cdn_url.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid","description":"Idempotency ID. Reuse for retries of this source; use a new ID only for a new paid generation."}},"required":["request_id"],"additionalProperties":false}}}},"responses":{"202":{"description":"SVG job receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"asset_ids":{"type":"object","properties":{"svg":{"type":"string","format":"uuid"}},"required":["svg"]},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"estimated_cost":{"type":"number"},"poll_url":{"type":"string"}},"required":["job_id","asset_ids","status","estimated_cost","poll_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Write access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Source or collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request ID conflict or variant not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"503":{"description":"Generation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}}}},"/v1/assets/{id}/exports":{"post":{"operationId":"createAssetExport","tags":["Assets"],"summary":"Export one image, video or chat sticker","description":"Creates a derivative of this exact completed source asset. Create a library sticker first with POST /v1/assets/{animation_id}/sticker to prepare all four platforms. Its sticker_animation asset ID can then request an individual platform export here. Image sources: image, transparent_image or sticker_image; formats PNG/WebP. Size is the maximum image dimension (32–2048), preserving aspect ratio and alpha without upscaling. Video sources: video/webm/hevc with an existing background-removal job; size is width (32–1920). Video formats: webm, hevc, prores (ProRes 4444 MOV with alpha for video editing), stacked_video, gif, lottie, dotlottie, png_sequence. Omit size for original. Choose format: sticker-telegram-v1, sticker-whatsapp-v1, sticker-wechat-v1 or sticker-discord-v1 for animated chat stickers. Each version determines codec, dimensions and duration and keeps 10% file-size headroom. Omit size. Only validated results become downloadable. The legacy sticker_profile input remains accepted. No generation credits. Reuses a pending/completed export for the same source/format/size; force requests a new file without changing old URLs. Poll the job, then GET this export list for signed downloads. Accepts Idempotency-Key.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["png","webp","webm","hevc","prores","stacked_video","gif","animated_webp","apng","lottie","dotlottie","png_sequence","sticker-telegram-v1","sticker-whatsapp-v1","sticker-wechat-v1","sticker-discord-v1"]},"sticker_profile":{"type":"string","enum":["telegram-v1","whatsapp-v1","wechat-v1","discord-v1"],"description":"Legacy input. Prefer format: sticker-telegram-v1, sticker-whatsapp-v1, sticker-wechat-v1 or sticker-discord-v1."},"size":{"type":"integer","minimum":32,"maximum":2048,"description":"Maximum image dimension, or video width. Omit for original size. Videos support up to 1920."},"force":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Completed reusable export","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source_asset_id":{"type":"string","format":"uuid"},"format":{"type":"string"},"size":{"type":"number","nullable":true},"job_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"error":{"type":"string","nullable":true},"file_url":{"type":"string","nullable":true},"public_url":{"type":"string","nullable":true},"metadata":{"nullable":true},"sticker_profile":{"type":"string"},"poster_url":{"type":"string","nullable":true},"poll_url":{"type":"string"}},"required":["id","source_asset_id","format","size","job_id","asset_id","status","error","file_url","public_url","poll_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"202":{"description":"Export queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source_asset_id":{"type":"string","format":"uuid"},"format":{"type":"string"},"size":{"type":"number","nullable":true},"job_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"error":{"type":"string","nullable":true},"file_url":{"type":"string","nullable":true},"public_url":{"type":"string","nullable":true},"metadata":{"nullable":true},"sticker_profile":{"type":"string"},"poster_url":{"type":"string","nullable":true},"poll_url":{"type":"string"}},"required":["id","source_asset_id","format","size","job_id","asset_id","status","error","file_url","public_url","poll_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}}},"get":{"operationId":"listAssetExports","tags":["Assets"],"summary":"List exports for one asset","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"200":{"description":"Current export files and jobs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source_asset_id":{"type":"string","format":"uuid"},"format":{"type":"string"},"size":{"type":"number","nullable":true},"job_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"error":{"type":"string","nullable":true},"file_url":{"type":"string","nullable":true},"public_url":{"type":"string","nullable":true},"metadata":{"nullable":true},"sticker_profile":{"type":"string"},"poster_url":{"type":"string","nullable":true},"poll_url":{"type":"string"}},"required":["id","source_asset_id","format","size","job_id","asset_id","status","error","file_url","public_url","poll_url"]}}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"description":"\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400."}},"/v1/mascots/{id}/exports":{"post":{"operationId":"backfillMascotExports","tags":["Collections"],"summary":"Generate missing image and video exports","description":"Uses the mascot’s saved image_exports, prores_exports and animation_sizes settings. ProRes is opt-in and exports one original-delivery-size MOV per video. Disabled sections are skipped. Creates an asynchronous batch job which schedules individual export jobs. Batch completion means scheduling finished, not that every file is ready. Existing in-flight work is reused; force regenerates completed exports. No settings change and no generation credit charge.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"types":{"type":"array","items":{"type":"string","enum":["image","video"]},"minItems":1,"maxItems":2,"default":["image","video"]},"force":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"202":{"description":"Batch job receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"poll_url":{"type":"string"}},"required":["job_id","poll_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"x-masko-api-version":"2026-09-26"}},"/v1/projects/{id}/export-settings":{"post":{"operationId":"applyProjectExportSettings","tags":["Projects"],"summary":"Apply export settings to project or folder mascots","description":"Merges supplied settings into mascots currently in the selected project or folder. Does not establish inherited defaults for future mascots. Image settings apply to future completed assets; apply_to_existing explicitly queues backfill jobs for existing assets. Preserves omitted settings.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"publish_params":{"type":"object","properties":{"image_exports":{"type":"object","properties":{"enabled":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string","enum":["original","transparent","sticker"]},"minItems":1,"maxItems":3},"formats":{"type":"array","items":{"type":"string","enum":["png","webp"]},"minItems":1,"maxItems":2},"sizes":{"type":"array","items":{"type":"integer","minimum":32,"maximum":2048},"minItems":1,"maxItems":5}},"required":["enabled","sources","formats","sizes"],"additionalProperties":false},"prores_exports":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false,"description":"Automatically create original-delivery-size ProRes 4444 MOV files with alpha after transparent animations finish. Disabled by default."},"animation_sizes":{"type":"object","properties":{"enabled":{"type":"boolean"},"sizes":{"type":"array","items":{"type":"integer","minimum":32,"maximum":1920},"maxItems":6},"custom_size":{"type":"integer","minimum":32,"maximum":1920}},"required":["enabled","sizes"],"additionalProperties":false}},"additionalProperties":false},"folder_id":{"type":"string","format":"uuid"},"apply_to_existing":{"type":"boolean","default":false}},"required":["publish_params"],"additionalProperties":false}}}},"responses":{"200":{"description":"Applied settings and optional backfill jobs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"updated_count":{"type":"number"},"jobs":{"type":"array","items":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"poll_url":{"type":"string"}},"required":["job_id","poll_url"]}}},"required":["updated_count","jobs"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}}}},"/v1/animations":{"post":{"operationId":"createAnimation","tags":["Generate"],"summary":"Animate an uploaded image","description":"Animate a completed image without generating another pose. Send either mascot_id to reuse an existing mascot, or create_mascot: {project_id, name?} to explicitly create one from an unattached upload in the same request. Omit create_mascot.name for an AI-chosen character name; no character description is generated. Returns mascot_id, mascot_name and mascot_created alongside the normal job receipt. Reuse mascot_id for subsequent animations to avoid creating extra mascots. Non-square inputs are center-cropped to square before animation; source_image_crop overrides framing. Originals are preserved. Only animation credits are charged: Standard (default) 2/sec, Premium 6/sec, default 5 seconds. Use Idempotency-Key to retry the complete operation without creating another mascot or job. If generation fails after mascot creation, error.details.mascot_id identifies the saved mascot; reuse it in a corrected request with a new key. This endpoint uses the canonical mascot API contract automatically.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAnimationBody"}}}},"responses":{"202":{"description":"Animation accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAnimationResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"402":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"500":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"x-masko-api-version":"2026-09-26"}},"/v1/collections/{id}/voice":{"get":{"tags":["Voice"],"summary":"Get the voice","description":"Returns the voice the mascot speaks with in talking animations, or null. A marketplace copy speaks with its creator's voice (source creator). sample_url is a short recording.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The voice, or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyGetCollectionVoice"},"put":{"tags":["Voice"],"summary":"Keep a voice","description":"Keeps one sample from POST /v1/collections/{id}/voice/samples as the voice of the mascot. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeepVoiceBody"}}}},"responses":{"200":{"description":"The kept voice","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyUpdateCollectionVoice"},"delete":{"tags":["Voice"],"summary":"Remove the voice","description":"Removes the mascot's voice. Talking animations already made keep their sound; new ones need a voice.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removed","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyDeleteCollectionVoice"}},"/v1/collections/{id}/voice/suggestions":{"get":{"tags":["Voice"],"summary":"Suggest voices","description":"Returns voice ideas written for the mascot from its references and description. Each description is ready for POST /v1/collections/{id}/voice/samples. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Return other ideas than a plain request would."},"required":false,"description":"Return other ideas than a plain request would.","name":"refresh","in":"query"},{"schema":{"type":"string","maxLength":500,"description":"Comma-separated idea titles not to suggest again."},"required":false,"description":"Comma-separated idea titles not to suggest again.","name":"avoid","in":"query"}],"responses":{"200":{"description":"Voice ideas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"$ref":"#/components/schemas/VoiceIdea"}}},"required":["ideas"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyListCollectionVoiceSuggestions"}},"/v1/collections/{id}/voice/adjust":{"post":{"tags":["Voice"],"summary":"Adjust a voice description","description":"Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustVoiceBody"}}}},"responses":{"200":{"description":"The rewritten description","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceAdjustment"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyAdjustCollectionVoice"}},"/v1/collections/{id}/voice/samples":{"post":{"tags":["Voice"],"summary":"Hear voice samples","description":"Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/collections/{id}/voice within 24 hours.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceSamplesBody"}}}},"responses":{"201":{"description":"Three samples","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceSamples"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Not enough credits","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyCreateCollectionVoiceSample"}},"/v1/collections/{id}/variants/{variantId}/voice":{"get":{"tags":["Voice"],"summary":"Get the voice of a variant","description":"Returns the voice this variant speaks with: its own (source variant), the Original's until it gets one (source original), or null. sample_url is a short recording.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"responses":{"200":{"description":"The voice, or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyGetCollectionVariantVoice"},"put":{"tags":["Voice"],"summary":"Keep a voice of a variant","description":"Keeps one sample from POST /v1/collections/{id}/variants/{variantId}/voice/samples as the voice of an approved variant. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeepVoiceBody"}}}},"responses":{"200":{"description":"The kept voice","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyUpdateCollectionVariantVoice"},"delete":{"tags":["Voice"],"summary":"Remove the voice of a variant","description":"Removes the variant's own voice; it speaks with the Original's voice again.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"responses":{"204":{"description":"Removed","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyDeleteCollectionVariantVoice"}},"/v1/collections/{id}/variants/{variantId}/voice/suggestions":{"get":{"tags":["Voice"],"summary":"Suggest voices of a variant","description":"Returns voice ideas written for an approved variant from its references and description. Each description is ready for POST /v1/collections/{id}/variants/{variantId}/voice/samples. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Return other ideas than a plain request would."},"required":false,"description":"Return other ideas than a plain request would.","name":"refresh","in":"query"},{"schema":{"type":"string","maxLength":500,"description":"Comma-separated idea titles not to suggest again."},"required":false,"description":"Comma-separated idea titles not to suggest again.","name":"avoid","in":"query"}],"responses":{"200":{"description":"Voice ideas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"$ref":"#/components/schemas/VoiceIdea"}}},"required":["ideas"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyListCollectionVariantVoiceSuggestions"}},"/v1/collections/{id}/variants/{variantId}/voice/adjust":{"post":{"tags":["Voice"],"summary":"Adjust a voice description of a variant","description":"Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustVoiceBody"}}}},"responses":{"200":{"description":"The rewritten description","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceAdjustment"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyAdjustCollectionVariantVoice"}},"/v1/collections/{id}/variants/{variantId}/voice/samples":{"post":{"tags":["Voice"],"summary":"Hear voice samples of a variant","description":"Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/collections/{id}/variants/{variantId}/voice within 24 hours.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceSamplesBody"}}}},"responses":{"201":{"description":"Three samples","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceSamples"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Not enough credits","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"deprecated":true,"operationId":"legacyCreateCollectionVariantVoiceSample"}},"/v1/projects":{"get":{"tags":["Projects"],"summary":"List projects","description":"Returns all projects owned by the authenticated user, paginated. Projects are the top-level containers for mascots. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"200":{"description":"List of projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"},"example":{"data":[{"id":"04dae799-dd9a-4296-ba86-9e3913c2f8d1","name":"test","created_at":"2026-04-08T03:30:21.168491+00:00","updated_at":"2026-04-08T03:30:21.168491+00:00","organization_id":"bc5a4520-ee23-46e7-b714-2835bd3a7f80"}],"meta":{"pagination":{"total":2,"limit":5,"offset":0,"has_more":false}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"listProjects"},"post":{"tags":["Projects"],"summary":"Create a project","description":"Creates a new project under the authenticated user. Projects are lightweight containers - create one per product or per workspace. Returns 201 with the new project record. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectBody"}}}},"responses":{"201":{"description":"Created project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"createProject","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/collections":{"get":{"tags":["Collections"],"summary":"List collections","description":"Returns all collections owned by the authenticated user, paginated. A collection is a single mascot character with its own style, references, and items. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter to this project."},"required":false,"description":"Filter to this project.","name":"project_id","in":"query"},{"schema":{"type":"string","description":"Filter by type, e.g. \"mascot\"."},"required":false,"description":"Filter by type, e.g. \"mascot\".","name":"type","in":"query"}],"responses":{"200":{"description":"List of collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"},"example":{"data":[{"id":"f9503022-a991-46ea-bf8c-d628c921b6b0","name":"v1-api-test-cat-1776591403","type":"mascot","project_id":"04dae799-dd9a-4296-ba86-9e3913c2f8d1","project_name":"test","is_published":true,"public_slug":"v1-api-test-cat-1776591403-rmau1uyd","user_prefix":"fda8417d","created_at":"2026-04-19T09:36:43.46139+00:00"}],"meta":{"pagination":{"total":6,"limit":5,"offset":0,"has_more":true}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyListCollections"},"post":{"tags":["Collections"],"summary":"Create a mascot (collection)","description":"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.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectionBody"}}}},"responses":{"201":{"description":"Created collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"},"example":{"data":{"id":"f9503022-a991-46ea-bf8c-d628c921b6b0","name":"v1-api-test-cat-1776591403","slug":"v1-api-test-cat-1776591403-rmau1uyd","type":"mascot","reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf"],"settings":{"cdn_enabled":true,"animation_sizes":[]}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyCreateCollection","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}]}},"/v1/collections/{id}":{"get":{"tags":["Collections"],"summary":"Get collection details","description":"Returns the full collection record including config (prompt, reference_asset_ids, style_card, caution_list) and cdn_status. Returns 404 if the collection does not exist or is not owned by the caller.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Collection details with cdn_status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"},"example":{"data":{"id":"f9503022-a991-46ea-bf8c-d628c921b6b0","name":"v1-api-test-cat-1776591403","type":"mascot","project_id":"04dae799-dd9a-4296-ba86-9e3913c2f8d1","config":{"prompt":"terracotta clay cat mascot with big eyes and speckled texture","reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf"],"style_card":null,"caution_list":[]},"is_published":true,"slug":"v1-api-test-cat-1776591403-rmau1uyd","user_prefix":"fda8417d","cdn_status":[],"created_at":"2026-04-19T09:36:43.46139+00:00","updated_at":"2026-04-19T09:36:46.966862+00:00"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGetCollection"},"patch":{"tags":["Collections"],"summary":"Update collection metadata","description":"Updates a collection name, prompt, or public slug. Returns { updated: true }. Returns 404 if not found or not owned by the caller. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectionBody"}}}},"responses":{"200":{"description":"Updated collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatedFlagResponse"},"example":{"data":{"updated":true}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyUpdateCollection"}},"/v1/collections/{id}/items":{"get":{"tags":["Items"],"summary":"List items in a collection","description":"Returns paginated items in a collection. An item groups related assets (e.g. \"wave\" item may have an image, a transparent image, and animation variants). Filter by `type` to narrow results. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"List of items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemListResponse"},"example":{"data":[],"meta":{"pagination":{"total":0,"limit":5,"offset":0,"has_more":false}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyListCollectionItems"}},"/v1/collections/{id}/items/{itemId}":{"get":{"tags":["Items"],"summary":"Get item details","description":"Returns the item record with all its generated assets (images, animations, logos). Returns 404 if the item does not exist or is not in the given collection. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"responses":{"200":{"description":"Item details with assets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGetCollectionItem"},"patch":{"tags":["Items"],"summary":"Update item name or prompt","description":"Updates the item name (used to derive the public slug) and/or the prompt. Does not re-generate assets. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateItemBody"}}}},"responses":{"200":{"description":"Updated item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemResponse"},"example":{"data":{"id":"e8ca0d1b-b445-46f6-862f-26b26ac2c6ff","name":"sitting-calmly","prompt":"sitting on ground with closed eyes peacefully","public_slug":"sitting","created_at":"2026-04-19T09:44:26.659167+00:00"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyUpdateCollectionItem"},"delete":{"tags":["Items"],"summary":"Archive an item","description":"Soft-deletes (archives) the item and its assets. Files are retained but filtered from reads. Returns 204 on success. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"responses":{"204":{"description":"Archived","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyDeleteCollectionItem"}},"/v1/collections/{id}/assets":{"get":{"tags":["Assets"],"summary":"List assets in a collection","description":"Returns paginated assets in a collection (images, videos, transparent variants). Each asset has a signed `file_url` (1-hour expiry) and a `cdn_url` when published. Filter by `type` or `item_id`. Set `include_file_urls=false` for faster metadata-only listings. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"item_id","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings."},"required":false,"description":"Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.","name":"include_file_urls","in":"query"}],"responses":{"200":{"description":"List of assets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetListResponse"},"example":{"data":[{"id":"5114bec3-b92a-4917-8675-84fce713d3cf","type":"image","status":"completed","metadata":{},"item_id":null,"file_url":"https://storage.googleapis.com/masco-media/references/.../f4bdfb19.png?GoogleAccessId=...&Expires=...&Signature=...","cdn_url":null,"created_at":"2026-04-19T09:36:46.95543+00:00"}],"meta":{"pagination":{"total":2,"limit":5,"offset":0,"has_more":false}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyListCollectionAssets"}},"/v1/collections/{id}/cdn-export":{"get":{"tags":["Collections"],"summary":"Export published CDN links","description":"Returns the same clean hosted-link JSON shown in the collection page Get Links export modal. This endpoint is built from published CDN assets, not raw item types, so pose/image items with attached video loops are included. Includes image sticker URL arrays, animated_stickers grouped by sticker ID with telegram, whatsapp, wechat and discord URL keys in formats, and complete cursor-follower interactions with nine WebP frame URLs and a JSON manifest URL. Only completed, non-archived hosted assets are included. Create cursor followers with POST /v1/collections/{id}/interactive. Use the raw items and assets endpoints for IDs, prompts, metadata, and status checks. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Collection CDN export JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnExportResponse"},"example":{"collection":"Fox Mascot","items":[{"name":"card-sit","image":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.png","transparent_image":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-transparent.png","animations":[{"video":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mp4","transparent_video_webm":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.webm","transparent_video_mov":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mov","transparent_video_android":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-android.mp4","transparent_video_android_360":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-360.mp4"}],"animated_stickers":[{"id":"22222222-2222-4222-8222-222222222222","source_asset_id":"33333333-3333-4333-8333-333333333333","formats":{"telegram":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webm","whatsapp":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webp","wechat":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.gif","discord":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.png"}}]}]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"CDN export is not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGetCollectionCdnExport"}},"/v1/assets":{"get":{"tags":["Assets"],"summary":"List assets across all collections","description":"Returns paginated assets spanning every mascot owned by the caller, each annotated with its `mascot_id`. Filter by `type`, `status`, or `mascot_id`. Set `include_file_urls=false` for faster metadata-only listings. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter to a single mascot. Omit to list across all of your mascots."},"required":false,"description":"Filter to a single mascot. Omit to list across all of your mascots.","name":"mascot_id","in":"query"},{"schema":{"type":"string","description":"Filter by asset type: image, transparent_image, video, webm, hevc, stacked_video, svg, etc."},"required":false,"description":"Filter by asset type: image, transparent_image, video, webm, hevc, stacked_video, svg, etc.","name":"type","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include archived assets. Defaults to false (active only)."},"required":false,"description":"Include archived assets. Defaults to false (active only).","name":"is_archived","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter to a single item within a mascot."},"required":false,"description":"Filter to a single item within a mascot.","name":"item_id","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings."},"required":false,"description":"Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.","name":"include_file_urls","in":"query"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."},{"schema":{"type":"string","format":"uuid","description":"Filter to a single mascot. Omit to list across all of your mascots."},"required":false,"description":"Legacy-only filter. Use mascot_id for new clients; never send both.","name":"collection_id","in":"query","deprecated":true}],"responses":{"200":{"description":"List of assets across your collections","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioAssetListResponse"},{"$ref":"#/components/schemas/AssetListResponse"}]},"example":{"data":[{"id":"5114bec3-b92a-4917-8675-84fce713d3cf","type":"image","status":"completed","metadata":{},"item_id":null,"mascot_id":"f9503022-a991-46ea-bf8c-d628c921b6b0","file_url":"https://storage.googleapis.com/masco-media/...signed-url...","cdn_url":null,"created_at":"2026-04-19T09:36:46.95543+00:00"}],"meta":{"pagination":{"total":215,"limit":3,"offset":0,"has_more":true}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"listAssets"}},"/v1/assets/{id}":{"get":{"tags":["Assets"],"summary":"Get asset details","description":"Returns a single asset record with its signed `file_url` and optional `cdn_url`. Returns 404 if the asset is not owned by the caller. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"200":{"description":"Asset details","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioAssetResponse"},{"$ref":"#/components/schemas/AssetResponse"}]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"getAsset"},"delete":{"tags":["Assets"],"summary":"Archive an asset","description":"Soft-deletes (archives) a single asset. The underlying file is retained on storage but filtered from reads. Returns 204 on success. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"204":{"description":"Archived","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"deleteAsset"}},"/v1/assets/{id}/sticker":{"post":{"tags":["Assets"],"summary":"Create a sticker from an image or animation","description":"Image: generates transparent sticker artwork for 1 credit and returns the existing 201 image receipt. Animation: creates one sticker_animation library asset and automatically prepares Telegram, WhatsApp, WeChat and Discord files in a CPU batch using its saved video and mask, for zero generation credits. Requires a completed video/webm/hevc with a background-removal result. Reuses the same sticker and valid cached files. Omit the body or send {}. force:true regenerates completed platform exports. Returns 202 while preparing, otherwise 200. Poll GET /v1/assets/{sticker_id}/sticker. Each format includes a validated file_url and a public_url when mascot asset hosting is enabled. Platform failures are independent.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnimatedStickerCreateBody"}}}},"responses":{"200":{"description":"Reused prepared animated sticker","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnimatedStickerReceipt"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"201":{"description":"Sticker generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StickerGenerateResponse"},"example":{"data":{"job_id":"8c458fc7-df42-4e5a-b5cb-8768c4d9f4a1","status":"completed","source_asset_id":"5114bec3-b92a-4917-8675-84fce713d3cf","asset_ids":{"sticker_image":"bafc3f5e-e90c-4cf8-88c2-bb5bcf3c5088"},"estimated_cost":1,"sticker_image":{"id":"bafc3f5e-e90c-4cf8-88c2-bb5bcf3c5088","type":"sticker_image","status":"completed","file_url":"https://storage.googleapis.com/masco-media/...signed-url...","width":1024,"height":1024}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"202":{"description":"Animated sticker created; platform files preparing","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnimatedStickerReceipt"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"stickerAsset"},"get":{"tags":["Assets"],"summary":"Get an animated sticker and its platform files","description":"Use the sticker_animation asset ID returned by creation. Reports each platform independently, including signed or hosted file_url and public_url. A partial_failure keeps successful platform files usable. Public URLs require asset hosting. No credit charge.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"200":{"description":"Animated sticker","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnimatedStickerReceipt"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"getAssetSticker"}},"/v1/assets/{id}/refine-mask":{"post":{"tags":["Assets"],"summary":"Refine a video asset mask","description":"Refines the active background mask for a completed video asset, then re-exports the requested derived formats and sizes from the refined mask. Omit `formats` and `sizes` to infer the currently active linked variants and refresh all of them. Old matching derived assets are archived and unlinked only after replacement assets are successfully published. Defaults to `dry_run=true` so agents can inspect the exact plan before starting the workflow.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefineAssetMaskBody"}}}},"responses":{"200":{"description":"Mask refinement dry-run plan returned","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioAssetMaskRefinementResponse"},{"$ref":"#/components/schemas/AssetMaskRefinementResponse"}]},"example":{"data":{"target":"video_mask_refinement","dry_run":true,"video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","bg_job_id":"5eb2db13-0000-0000-0000-000000000001","prompt":"the soccer ball","op":"add","model":"pro","edge_cleanup":{"enabled":true,"size":512},"formats":["webm","hevc","stacked_video"],"sizes":[360],"export_count":6,"archive_old":true,"active_variants":[]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"202":{"description":"Mask refinement job started","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioAssetMaskRefinementResponse"},{"$ref":"#/components/schemas/AssetMaskRefinementResponse"}]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"refineMaskAsset"}},"/v1/collections/{id}/references":{"post":{"tags":["References"],"summary":"Add a reference image","description":"Adds an image as a collection-scoped style reference (up to 6 references). Pass either `url` to download and store a new reference, or `asset_id` to copy an existing uploaded/generated image into this collection when needed. The returned `reference_asset_ids` are always collection-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddReferenceBody"}}}},"responses":{"201":{"description":"Reference added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceResponse"},"example":{"data":{"reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf","b357dfe9-92ab-4696-beb3-4f36779808f2"]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyCreateCollectionReference"}},"/v1/collections/{id}/references/{assetId}":{"delete":{"tags":["References"],"summary":"Remove a reference image","description":"Removes an asset from the collection reference list. Returns the updated `reference_asset_ids` array. Invalidates the cached style_card. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"assetId","in":"path"}],"responses":{"200":{"description":"Reference removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceResponse"},"example":{"data":{"reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf"]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyDeleteCollectionReference"}},"/v1/collections/{id}/generate":{"post":{"tags":["Generate"],"summary":"Generate image or animation","description":"Starts an async generation job. Returns 202 with `data.job_id` - poll via GET `/v1/jobs/{id}` (or pass `?wait=true` for long-polling). Cost by type: image=1, animation=2/sec with animation_model=standard (5–15s) or 6/sec with animation_model=premium (4–30s), default 5s for either choice (+1 if no source image); omitting animation_model preserves legacy 5/sec, 4–10s, default 4s, logo=5, edit=1 for images, scene=3, reverse=0. For `type: animation`, you can skip providing a source image: pass only `animation_prompt` (and optionally `image_prompt`) and the system generates a fresh source image first, then animates it. To animate an uploaded image directly, pass its POST /v1/upload asset_id as source_image_asset_id with type=animation. The upload is imported into the mascot without changing references; no image-generation credits are charged. Existing mascot assets preserve their saved context. Before video generation, non-square starting and ending images are center-cropped to square; square images are reused unchanged. Optional source_image_crop and end_image_crop specify integer x, y, width and height in pixels after image orientation. Cropped copies preserve the originals and incur no extra credits. Invalid crops return 400 before charging. If you have an existing item, pass `item_id` to animate/edit its current image. For image generation and image edits, pass optional `visual_references` for one-time pose, expression, motion, prop, style, or scene cues; these references do not become collection mascot references. Scene generation and scene editing also use this endpoint with `type: \"scene\"`. For a new scene, optional `source_asset_id` selects its character reference and saved variant context. For scene edits use `source_image_asset_id` with `edit_instructions`; the two source fields are mutually exclusive. Talking animations: pass `speech` with `type: animation` and the mascot says the line in its voice (see the Voice endpoints). The length follows the speech, 5 seconds to 5 minutes at 2 credits per second; the receipt charges the longest the line could need and unused seconds are refunded once the voice is recorded. Talking adds audio (MP3) and transcript (JSON) assets. With `dry_run: true` it returns 200 with the estimate instead. Returns 409 with details.reason voice_required when the mascot has no voice yet. Returns 402 if credits are insufficient.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateBody"}}}},"responses":{"200":{"description":"Talking estimate (speech with dry_run)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TalkingDryRunResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"202":{"description":"Generation job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateAsyncResponse"},"example":{"data":{"job_id":"b87c9579-7460-4bd0-aa54-77991615dfef","status":"pending","type":"image","item_id":"e328c567-0965-42fc-90b5-7ff6faa61b25","item_name":"wave","estimated_cost":1,"asset_ids":{"image":"a8b158bb-5698-431a-b0f1-98ee30228b11"},"urls":{"transparent_image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-91a9ac20.png","image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-a8b158bb.png"},"poll_url":"/api/v1/jobs/b87c9579-7460-4bd0-aa54-77991615dfef"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGenerateCollection"}},"/v1/collections/{id}/animations/reference-video":{"post":{"tags":["Generate"],"summary":"Animate a mascot from a reference video","description":"From Video uses Premium to transfer reference motion to your mascot. Upload a video and its first frame through POST /v1/upload, then provide their asset IDs. Source assets must be completed, active, and accessible to the credential; collection assets must belong to its workspace. Creates one animation item plus start and end pose items, with MP4, transparent WebM/HEVC, and pose images. Costs 6 credits per output second plus 1 image credit, so the default 5s costs 31 credits. Output duration is 4–30 whole seconds. Standard is not supported for this operation. Returns 202; poll the returned job until completed. Do not resubmit while the job is running.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceVideoBody"}}}},"responses":{"202":{"description":"Reference video job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceVideoAsyncResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyCreateCollectionAnimationReferenceVideo"}},"/v1/collections/{id}/generate-batch":{"post":{"tags":["Generate"],"summary":"Batch-generate multiple items","description":"Starts multiple generation jobs in one call (up to the per-request cap). Returns 202 with an array of `data.jobs[]`, each with its own `job_id`. Cost is summed across all items. Returns 402 if credits are insufficient for the whole batch.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateBatchBody"}}}},"responses":{"202":{"description":"Batch generation jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAsyncResponse"},"example":{"data":{"jobs":[{"job_id":"fe21477f-7e46-448f-bfdb-96eac80205b8","item_id":"e8ca0d1b-b445-46f6-862f-26b26ac2c6ff","item_name":"sitting","status":"pending","estimated_cost":1,"asset_ids":{"image":"25dc5edf-bf41-4a7f-ba23-b783ea2718d8"},"urls":{"transparent_image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-fb7bbd6f.png","image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-25dc5edf.png"}}],"total_cost":2,"poll_url":"/api/v1/jobs"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGenerateBatchCollection"}},"/v1/collections/{id}/suggestions":{"get":{"tags":["Generate"],"summary":"Suggest action poses","description":"Returns AI-generated action/pose suggestions (e.g. \"waving\", \"thinking\") tailored to the same resolved parent-plus-child mascot context used by generation. Use these as prompts for POST `/v1/collections/{id}/generate`. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Use this approved mascot variant for suggestions. Omit for Original."},"required":false,"description":"Use this approved mascot variant for suggestions. Omit for Original.","name":"variant_id","in":"query"}],"responses":{"200":{"description":"Suggested actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionsResponse"},"example":{"data":{"suggestions":["Curious Head Tilt","Wide Eyed Stare","Slow Clay Blink","Gentle Tail Wag","Heavy Paw Waddle","Playful Pounce","Happy Ear Twitch"]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyListCollectionSuggestions"}},"/v1/collections/{id}/scenes/suggestions":{"get":{"tags":["Generate"],"summary":"Suggest scenes for a collection","description":"Returns AI-generated scene ideas (setting + action + recommended position) tailored to the collection. Use these as payloads for POST `/v1/collections/{id}/generate` with `type: \"scene\"`. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Use this approved mascot variant for suggestions. Omit for Original."},"required":false,"description":"Use this approved mascot variant for suggestions. Omit for Original.","name":"variant_id","in":"query"},{"schema":{"type":"string","enum":["4:3","1:1","21:9","4:5","3:4","9:16"],"default":"4:5","description":"Aspect ratio to optimize the suggestions for. Defaults to 4:5."},"required":false,"description":"Aspect ratio to optimize the suggestions for. Defaults to 4:5.","name":"aspect_ratio","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":6,"description":"Number of scene suggestions to return. Defaults to 6, max 10."},"required":false,"description":"Number of scene suggestions to return. Defaults to 6, max 10.","name":"count","in":"query"}],"responses":{"200":{"description":"AI-suggested scenes for the collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SceneSuggestionsResponse"},"example":{"data":{"suggestions":[{"name":"Sunlit Terrace","emoji":"☀️","scene":"A sun-drenched Mediterranean stone balcony overlooking a sparkling blue coastline, decorated with potted succulents and blooming bougainvillea in earthen jars.","action":"Sitting contentedly among the flower pots and soaking up the afternoon warmth.","position":"center"}]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyListCollectionSceneSuggestions"}},"/v1/collections/{id}/settings":{"patch":{"tags":["Settings"],"summary":"Update collection settings","description":"Updates mascot export settings. image_exports configures future PNG/WebP derivatives of original, transparent and sticker images; it does not backfill existing images. animation_sizes preserves existing behavior: changed settings may queue exports for existing animations as well as future outputs. Use POST /v1/mascots/{id}/exports for explicit image/video backfill, or the legacy size-variants endpoint for video-only repair. Returns settings_applied, size_variant_jobs and sizes_enabled. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSettingsBody"}}}},"responses":{"200":{"description":"Settings updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatedFlagResponse"},"example":{"data":{"updated":true}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyUpdateCollectionSettings"}},"/v1/collections/{id}/size-variants":{"post":{"tags":["Settings"],"summary":"Backfill animation size variants","description":"Starts idempotent jobs for missing animation size variants on completed videos in this collection. Normal pipeline usage sends `{}`: it uses the collection configured `animation_sizes`, or `[360]` when no sizes are configured, and only creates missing variants. `force=true` is an explicit admin recovery option that regenerates existing variants too; do not use it for normal marketplace/canvas backfills or while relevant jobs are in flight. This endpoint does not regenerate source animations and does not toggle collection settings.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateSizeVariantsBody"}}}},"responses":{"200":{"description":"Size variant jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SizeVariantsResponse"},"example":{"data":{"size_variant_jobs":3,"sizes":[360],"force":false}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyCreateCollectionSizeVariant"}},"/v1/collections/{id}/canvases":{"get":{"tags":["Canvases"],"summary":"List canvases in a collection","description":"Returns all canvases (state machines / animation graphs) attached to the collection. A canvas describes nodes (poses) and edges (loops or transitions). No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of canvases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasListResponse"},"example":{"data":[]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyListCollectionCanvases"},"post":{"tags":["Canvases"],"summary":"Create a canvas","description":"Creates a canvas for the collection. If `template_id` is provided, items and images are generated for every node (image cost per node, 1 credit each). With no `template_id`, creates an empty canvas with zero cost. Returns 201.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCanvasBody"}}}},"responses":{"201":{"description":"Created canvas (populated if template_id provided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasResponse"},"example":{"data":{"id":"8c4b872c-df43-4d64-b84c-00f0d8314140","name":"test-empty-canvas","graph":{"edges":[],"nodes":[],"inputs":[],"viewport":{"x":0,"y":0,"zoom":1}},"created_at":"2026-04-19T09:42:15.222526+00:00"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyCreateCollectionCanvas"}},"/v1/collections/{id}/canvases/{canvasId}":{"get":{"tags":["Canvases"],"summary":"Get canvas details","description":"Returns the canvas with its full graph (nodes, edges, inputs, viewport) and media status. For agents: use `status.media` as the canonical readiness interface. `status.media.generation.ready` means node images and parent edge videos exist. Inspect `status.failed_nodes` and `status.failed_edges` for terminal generation failures and customer-safe error messages before deciding whether to start a new paid attempt. `status.nodes.pending` remains the backward-compatible count of all incomplete nodes, including failed nodes; `status.nodes.failed` identifies the terminal subset. `status.media.preview.ready` means the canvas editor can play every concrete edge using completed base WebM and HEVC derivatives. If `status.media.preview.waiting_edges > 0`, wait and poll again because the original generation job is still preparing derivatives. If `status.media.preview.repairable=true`, call POST `/v1/collections/{id}/canvases/{canvasId}/repair` with `dry_run=true` before repairing. `status.media.variants` reports optimized size-variant facts only; base preview repair does not create variants. `status.ready`, `status.generated_ready`, and `status.preview_ready` remain as backward-compatible aliases.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"200":{"description":"Canvas details with status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasResponse"},"example":{"data":{"id":"280ceab9-4673-4c78-b37c-3617feb51914","name":"test-canvas-from-template","graph":{"edges":[{"id":"d7420e54-9545-4527-bff0-912be67c3758","jobId":"a3c6ec30-a82c-41b2-a28f-37bedf369815","source":"38df9602-c21a-4637-9cea-c0962433d2e1","target":"38df9602-c21a-4637-9cea-c0962433d2e1","reverse":false,"duration":4,"conditions":[],"description":"Gentle breathing, slow blinking, tail curling slightly","videoAssetId":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","reverseOfEdgeId":null}],"nodes":[{"x":0,"y":0,"id":"38df9602-c21a-4637-9cea-c0962433d2e1","itemName":"Idle"}],"inputs":[],"viewport":{"x":0,"y":0,"zoom":0.8}},"status":{"nodes":{"total":2,"completed":2,"pending":0,"failed":0},"edges":{"total":3,"completed":3,"pending":0,"failed":0},"ready":true,"generated_ready":true,"preview_ready":true,"media":{"generation":{"ready":true,"nodes":{"total":2,"completed":2,"pending":0,"failed":0},"edges":{"total":3,"completed":3,"pending":0,"failed":0}},"preview":{"ready":true,"repairable":false,"repairable_edges":0,"waiting_edges":0,"missing_edges":0,"missing_formats":[]},"variants":{"sizes":[],"missing":[]}},"failed_nodes":[],"failed_edges":[],"edge_media":[{"edge_id":"d7420e54-9545-4527-bff0-912be67c3758","source":"38df9602-c21a-4637-9cea-c0962433d2e1","target":"38df9602-c21a-4637-9cea-c0962433d2e1","video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","base":{"video_ready":true,"webm_ready":true,"hevc_ready":true,"preview_ready":true,"derivatives_in_flight":false,"missing":[]},"variants":{}}]}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGetCollectionCanvas"},"patch":{"tags":["Canvases"],"summary":"Replace a complete canvas graph","description":"Replaces the complete authored graph. Read the canvas first and send its graph_content_hash as expected_graph_hash. If another editor changes the graph first, the write returns 409 instead of overwriting it. Generated asset fields on unchanged nodes and edges are preserved. No credit cost; generation is triggered separately.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCanvasBody"}}}},"responses":{"200":{"description":"Canvas updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyUpdateCollectionCanvas"},"delete":{"tags":["Canvases"],"summary":"Delete a canvas","description":"Deletes a canvas without saved history. Generated node/edge assets are kept. Returns 204, or 409 when checkpoints or releases retain the canvas. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"204":{"description":"Canvas deleted","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyDeleteCollectionCanvas"}},"/v1/collections/{id}/canvases/{canvasId}/repair":{"post":{"tags":["Canvases"],"summary":"Repair canvas preview media","description":"Plans or starts a narrow repair for missing base WebM/HEVC derivatives on videos already assigned to this canvas. Agent workflow: first call with `dry_run=true` or omit `dry_run` because it defaults to true. Read `status.media.preview`, `summary`, `repairs`, `in_flight`, and `skipped`. If `status.media.preview.waiting_edges > 0`, wait and poll again instead of repairing. Only call again with `dry_run=false` if the repair plan matches the intended canvas videos. This endpoint is for the specific case where `status.media.generation.ready=true`, `status.media.preview.ready=false`, and `status.media.preview.repairable=true`. It does not regenerate animations, does not run collection-wide jobs, does not create size variants, does not expose prompt/model controls, does not force regeneration, and does not archive existing assets.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepairCanvasBody"}}}},"responses":{"200":{"description":"Repair plan returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasRepairResponse"},"example":{"data":{"target":"video_derivatives","dry_run":true,"formats":["webm","hevc"],"status":{"generated_ready":true,"preview_ready":false,"media":{"generation":{"ready":true,"nodes":{"total":6,"completed":6,"pending":0,"failed":0},"edges":{"total":42,"completed":42,"pending":0,"failed":0}},"preview":{"ready":false,"repairable":true,"repairable_edges":2,"waiting_edges":0,"missing_edges":2,"missing_formats":["webm","hevc"]},"variants":{"sizes":["360"],"missing":[]}}},"summary":{"edges_checked":42,"videos_checked":38,"videos_ready":36,"videos_to_repair":2,"videos_in_flight":0,"videos_skipped":0},"repairs":[{"video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","edge_ids":["enter-hover-perk"],"missing":["webm","hevc"],"action":"create_derivatives"}],"in_flight":[],"skipped":[]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"202":{"description":"Repair jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasRepairResponse"},"example":{"data":{"target":"video_derivatives","dry_run":false,"formats":["webm","hevc"],"status":{"generated_ready":true,"preview_ready":false,"media":{"generation":{"ready":true,"nodes":{"total":6,"completed":6,"pending":0,"failed":0},"edges":{"total":42,"completed":42,"pending":0,"failed":0}},"preview":{"ready":false,"repairable":true,"repairable_edges":2,"waiting_edges":0,"missing_edges":2,"missing_formats":["webm","hevc"]},"variants":{"sizes":["360"],"missing":[]}}},"summary":{"edges_checked":42,"videos_checked":38,"videos_ready":36,"videos_to_repair":2,"videos_in_flight":0,"videos_skipped":0},"repairs":[{"video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","edge_ids":["enter-hover-perk"],"missing":["webm","hevc"],"action":"create_derivatives"}],"in_flight":[],"skipped":[],"jobs":[{"job_id":"a1b2c3d4-0000-0000-0000-000000000001","poll_url":"/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001","video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","edge_ids":["enter-hover-perk"],"formats":["webm","hevc"]}]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyRepairCollectionCanvas"}},"/v1/collections/{id}/canvases/{canvasId}/presentation/detect-facing":{"post":{"tags":["Canvases"],"summary":"Detect canvas natural facing","description":"Analyzes completed canvas node images and returns a suggested presentation.naturalFacing value plus node-level evidence. This is a synchronous analysis endpoint. It does not write to the canvas graph and has no credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Suggested natural-facing presentation value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasFacingDetectionResponse"},"example":{"data":{"suggestedNaturalFacing":"left","confidence":0.82,"analyzedNodeCount":3,"nodeResults":[{"nodeId":"idle","nodeName":"Idle","facing":"left","confidence":0.88,"reason":"The mascot has a consistent left-facing body angle."}]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyDetectFacingCollectionCanvasPresentation"}},"/v1/collections/{id}/canvases/{canvasId}/graph/extend":{"post":{"tags":["Canvases"],"summary":"Legacy partial canvas graph extension","deprecated":true,"description":"Deprecated compatibility endpoint. New authoring clients should read the complete graph and graph_content_hash, reconcile locally, and PATCH the complete graph with expected_graph_hash.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendCanvasGraphBody"}}}},"responses":{"200":{"description":"Canvas graph extended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasGraphExtendResponse"},"example":{"data":{"id":"280ceab9-4673-4c78-b37c-3617feb51914","name":"Main canvas","graph":{"nodes":[],"edges":[],"inputs":[],"viewport":{"x":0,"y":0,"zoom":1}},"updated_at":"2026-05-04T12:00:00.000Z","added":{"nodes":1,"edges":2,"inputs":1},"updated":{"edges":1}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"operationId":"legacyExtendCollectionCanvasGraph"}},"/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}":{"patch":{"tags":["Canvases"],"summary":"Patch a canvas edge","description":"Patches one edge without replacing the graph. Use this for speed tuning after generation: normal transitions use speed 2, snappy interact transitions use 3-4, held/special loops use 2, and calm loops use 1.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"edgeId","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchCanvasEdgeBody"}}}},"responses":{"200":{"description":"Canvas edge patched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEdgePatchResponse"},"example":{"data":{"id":"280ceab9-4673-4c78-b37c-3617feb51914","name":"Main canvas","edge":{"id":"idle-to-interact","source":"idle","target":"interact","duration":4,"speed":3},"graph":{"nodes":[],"edges":[],"inputs":[],"viewport":{"x":0,"y":0,"zoom":1}},"updated_at":"2026-05-04T12:00:00.000Z"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyUpdateCollectionCanvasEdge"}},"/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}/generate":{"post":{"tags":["Canvases"],"summary":"Generate a single canvas edge","description":"Dispatches generation for one specific canvas edge by ID. Costs the same as a single edge in generate-all: duration * 2 for animation_model=standard or duration * 6 for premium. Without animation_model, legacy duration * 5 pricing is retained. If the edge already has a video asset, archives the old assets and re-dispatches. Any State edges (source: \"*\") and reverse edges are rejected with 400. Requires the source and target nodes to already have generated images. Loops use the source pose receipt, even on a mixed-variant canvas. Transitions retain both endpoint contexts. For uploads without receipts, the canvas context selects matching references; ambiguous shared uploads return 409 before charging.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"edgeId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateEdgeBody"}}}},"responses":{"202":{"description":"Edge generation started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEdgeGenerateResponse"},"example":{"data":{"job_id":"a1b2c3d4-0000-0000-0000-000000000001","edge_id":"idle-to-interact","type":"transition","source":"Idle","target":"Interact","cost":20,"urls":{},"poll_url":"/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGenerateCollectionCanvasEdge"}},"/v1/collections/{id}/canvases/{canvasId}/edges/{edgeId}/refine-mask":{"post":{"tags":["Canvases"],"summary":"Refine a canvas edge video mask","description":"Convenience wrapper around `POST /v1/assets/{id}/refine-mask` for a canvas edge. The route resolves the edge `videoAssetId`, refines that video asset mask, and re-exports the active derived formats/sizes. The canvas graph keeps the same raw video asset; desktop playback updates because the active linked WebM/HEVC/stacked variants are replaced underneath it. Any State and reverse edges are rejected because they do not own an independent video asset.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"edgeId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefineCanvasEdgeMaskBody"}}}},"responses":{"200":{"description":"Canvas edge mask refinement dry-run plan returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetMaskRefinementResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"202":{"description":"Canvas edge mask refinement job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetMaskRefinementResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyRefineMaskCollectionCanvasEdge"}},"/v1/collections/{id}/canvases/{canvasId}/generate-all":{"post":{"tags":["Canvases"],"summary":"Generate canvas images, stickers, and animations","description":"Kicks off generation for pending canvas node images, sticker derivatives, and/or edge animations. Pass animation_model=standard (2 credits/sec, 5–15s) or premium (6 credits/sec, 4–30s); both default to 5s. Omit the field for legacy generation (5 credits/sec, 4–10s, default 4s). Model choice is included in plan approval and idempotent replay checks. Requires a write key in the collection workspace and project access, including for dry runs. Cross-workspace collections return 404. Use `dry_run=true` first to preview planned work, prompts, skipped items, and estimated credits without creating jobs/assets or spending credits. Dry-run returns `plan_id` and `graph_content_hash`; send them as `approved_plan_id` and `expected_graph_hash` on execution so a changed graph, prompt, option, or selection returns 409 before spending. Use `targets=\"images\"` to generate poses, `targets=\"stickers\"` to backfill transparent sticker derivatives for completed node images, `targets=\"animations\"` for edge videos, or `include_stickers=true` to create stickers alongside newly generated images.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateAllBody"}}}},"responses":{"200":{"description":"Generation plan returned or jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasGenerateAllResponse"},"example":{"data":{"jobs":[{"job_id":"58341ab3-80fc-4fca-8a86-f9d2caee9a14","edge_id":"095872b7-c6f6-4f6d-8679-9739436fd16c","type":"transition","source":"Idle","target":"Waving","cost":20,"urls":{"webm":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-a622eb51.webm","video":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-7e5fe2ec.mp4","hevc":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-2880976b.mov"}}],"total_jobs":3,"total_cost":60,"dry_run":false,"generated":[],"skipped":0,"skipped_items":[],"reverse_free":[{"kind":"edge","id":"waving-to-idle","reason":"reverse_edge_free","reverse_of_edge_id":"idle-to-waving"}],"already_complete":[],"estimated_cost":60,"would_charge_credits":60,"actual_cost":60}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGenerateAllCollectionCanvas"}},"/v1/collections/{id}/canvases/{canvasId}/export":{"get":{"tags":["Canvases"],"summary":"Export a canvas","description":"Exports the canvas as legacy MaskoAnimationConfig JSON by default, or as a target-specific delivery envelope with delivery=1. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string","enum":["json"]},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["1"],"description":"Return the delivery envelope instead of legacy MaskoAnimationConfig data."},"required":false,"description":"Return the delivery envelope instead of legacy MaskoAnimationConfig data.","name":"delivery","in":"query"},{"schema":{"type":"string","enum":["macos","windows","web","full"],"description":"Delivery media target. macos returns HEVC URLs, windows returns WebM URLs, web returns WebM and HEVC URLs, full returns all selected formats."},"required":false,"description":"Delivery media target. macos returns HEVC URLs, windows returns WebM URLs, web returns WebM and HEVC URLs, full returns all selected formats.","name":"target","in":"query"},{"schema":{"type":"string","enum":["selected","manifest"],"description":"Delivery mode. selected returns one variant; manifest includes known variants."},"required":false,"description":"Delivery mode. selected returns one variant; manifest includes known variants.","name":"mode","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Selected delivery size in pixels, if that size variant has already been generated."},"required":false,"description":"Selected delivery size in pixels, if that size variant has already been generated.","name":"size","in":"query"}],"responses":{"200":{"description":"Canvas export data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportConfigResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"deprecated":true,"operationId":"legacyGetCollectionCanvasExport"}},"/v1/canvas-templates":{"get":{"tags":["Canvases"],"summary":"List canvas templates","description":"Returns built-in templates plus any user-owned templates. Templates describe node prompts and edge definitions used to bootstrap canvases (e.g. \"Essential Mascot\", \"Bonzi Buddy\"). No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of canvas templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasTemplateListResponse"},"example":{"data":[{"id":"bonzi-buddy-7state","name":"Bonzi Buddy","description":"7 animated poses with rich interactions: idle, coding, thinking, waving, celebrating, sleeping, and greeting on click. Classic Bonzi Buddy personality with sounds. ~340 credits.","source":"builtin","nodes":[{"key":"idle","name":"Idle","imagePrompt":"Standing casually, looking around curiously with big expressive eyes, slight swaying, hands at sides, friendly relaxed expression","position":{"x":0,"y":0}}],"edges":[]}]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"listCanvasTemplates","parameters":[{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]},"post":{"tags":["Canvases"],"summary":"Create a canvas template","description":"Creates a reusable user-owned canvas template. Templates can later be applied via POST `/v1/mascots/{id}/canvases` with `template_id`. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioCreateTemplateBody"},{"$ref":"#/components/schemas/CreateTemplateBody"}]}}}},"responses":{"201":{"description":"Created template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasTemplateResponse"},"example":{"data":{"id":"a5eba03f-8c29-481b-98b9-5cfc778cfcc7","name":"test-template-tmp","created_at":"2026-04-19T09:42:35.319739+00:00","source":"user","public":false}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"createCanvasTemplate","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/canvas-templates/{id}":{"get":{"tags":["Canvases"],"summary":"Get canvas template details","description":"Returns the full template definition including node prompts, edges, and any declared inputs. Works for both built-in and user-owned templates. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"200":{"description":"Template details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasTemplateResponse"},"example":{"data":{"id":"claude-code-4state-lite","name":"Essential Mascot","description":"All 4 reactions (resting, coding, thinking, waving) at a lower cost. Uses smart routing to keep animations minimal. ~144 credits.","source":"builtin","nodes":[{"key":"idle","name":"Idle","imagePrompt":"Relaxed, calm, sitting on the floor or resting, eyes half-open, peaceful expression, breathing gently","position":{"x":0,"y":0}}],"edges":[],"inputs":[{"name":"claudeCode::isWorking","type":"boolean","default":false,"system":true}]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"getCanvasTemplate"},"patch":{"tags":["Canvases"],"summary":"Update a canvas template","description":"Updates name, description, public flag, or the template graph for a user-owned template. Built-in templates cannot be modified (returns 403). No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateBody"}}}},"responses":{"200":{"description":"Template updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasTemplateResponse"},"example":{"data":{"id":"a5eba03f-8c29-481b-98b9-5cfc778cfcc7","user_id":"fda8417d-8789-4dce-aa64-c553a3de2ac0","name":"test-template-tmp","description":"Updated description","template":{"edges":[{"source":"a","target":"a","duration":4,"description":"A idling"}],"nodes":[{"key":"a","name":"A","position":{"x":0,"y":0},"imagePrompt":"pose A"}],"inputs":[]},"public":false,"created_at":"2026-04-19T09:42:35.319739+00:00","updated_at":"2026-04-19T09:42:35.319739+00:00"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"updateCanvasTemplate"},"delete":{"tags":["Canvases"],"summary":"Delete a canvas template","description":"Deletes a user-owned template. Built-in templates cannot be deleted (returns 403). Returns 204. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"204":{"description":"Template deleted","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"deleteCanvasTemplate"}},"/v1/jobs":{"get":{"tags":["Jobs"],"summary":"List generation jobs","description":"Returns paginated generation jobs owned by the caller, newest first. Use to track recent activity or find a specific job. Filter by status or mascot. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter transitions by the variant of the starting pose."},"required":false,"description":"Filter transitions by the variant of the starting pose.","name":"from_variant_id","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter transitions by the variant of the ending pose."},"required":false,"description":"Filter transitions by the variant of the ending pose.","name":"to_variant_id","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter jobs by their single variant. Cross-variant transitions have no single variant; use from_variant_id or to_variant_id."},"required":false,"description":"Filter jobs by their single variant. Cross-variant transitions have no single variant; use from_variant_id or to_variant_id.","name":"variant_id","in":"query"},{"schema":{"type":"string","description":"Filter by status: pending, processing, completed, failed."},"required":false,"description":"Filter by status: pending, processing, completed, failed.","name":"status","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404."},"required":false,"description":"Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404.","name":"mascot_id","in":"query"},{"schema":{"type":"string","description":"Filter by job type. Values: item_generation, image_generation, logo, animation, video_edit, reverse, size_variant, size_variant_batch, export_animation, scene_generation, interactive_generation, sticker_generation, svg_generation."},"required":false,"description":"Filter by job type. Values: item_generation, image_generation, logo, animation, video_edit, reverse, size_variant, size_variant_batch, export_animation, scene_generation, interactive_generation, sticker_generation, svg_generation.","name":"type","in":"query"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."},{"schema":{"type":"string","format":"uuid","description":"Filter to jobs for a mascot in the credential workspace. A mascot outside that workspace returns 404."},"required":false,"description":"Legacy-only filter. Use mascot_id for new clients; never send both.","name":"collection_id","in":"query","deprecated":true}],"responses":{"200":{"description":"List of jobs","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioJobListResponse"},{"$ref":"#/components/schemas/JobListResponse"}]},"example":{"data":[{"id":"ccc8bbf9-d3b2-4d8b-b21f-c5f91c5fbffa","type":"scene_generation","status":"completed","mascot_id":"21c247da-2359-47b2-97f9-da70bc1af688","output_asset_id":null,"cost_credits":3,"error":null,"created_at":"2026-04-14T11:14:49.18381+00:00","updated_at":"2026-04-14T11:15:47.524116+00:00","op_code":null,"input_data":{"cost":3,"scene":"A misty bamboo forest at dawn with golden sun rays piercing through the leaves","action":"stretching with arms wide and a relaxed grin","item_id":"7defa668-99ec-4f34-afa0-48599889958b","position":"center","aspect_ratio":"4:5","collection_id":"21c247da-2359-47b2-97f9-da70bc1af688"},"output_data":{"width":3712,"height":4608,"image_url":"image/png/5c08e718-acf3-4327-8ef5-895d0beefd4d.coach-ginger"}}],"meta":{"pagination":{"total":29,"limit":5,"offset":0,"has_more":true}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"listJobs"}},"/v1/jobs/{id}":{"get":{"tags":["Jobs"],"summary":"Long-poll a job to completion","description":"Returns job status and output URLs. Pass `?wait=true` to long-poll until the job completes or fails (up to ~60s). Returns 404 if the job does not exist or is not owned by the caller.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"If true, long-poll until the job completes, fails, or timeout is reached. If false or omitted, return the current status immediately."},"required":false,"description":"If true, long-poll until the job completes, fails, or timeout is reached. If false or omitted, return the current status immediately.","name":"wait","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":120,"description":"Long-poll timeout in seconds when wait=true. 1 to 120. Defaults to 120. On timeout the response is 200 with the current (still pending) job state, not 408."},"required":false,"description":"Long-poll timeout in seconds when wait=true. 1 to 120. Defaults to 120. On timeout the response is 200 with the current (still pending) job state, not 408.","name":"timeout","in":"query"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"200":{"description":"Job details","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioJobResponse"},{"$ref":"#/components/schemas/JobResponse"}]},"example":{"data":{"id":"ccc8bbf9-d3b2-4d8b-b21f-c5f91c5fbffa","status":"completed","type":"scene_generation","mascot_id":"21c247da-2359-47b2-97f9-da70bc1af688","cost_credits":3,"created_at":"2026-04-14T11:14:49.18381+00:00","updated_at":"2026-04-14T11:15:47.524116+00:00","item_id":"7defa668-99ec-4f34-afa0-48599889958b","item_name":"loop test - bamboo","urls":{"image":"https://storage.googleapis.com/masco-media/image/png/5c08e718-acf3-4327-8ef5-895d0beefd4d.coach-ginger?GoogleAccessId=...&Expires=...&Signature=..."}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"getJob"}},"/v1/credits":{"get":{"tags":["Credits"],"summary":"Get credit balance","description":"Returns current credits split into `subscription` (monthly allowance) and `topup` (purchased or bonus), plus `total`. Use before kicking off a large generation run to confirm balance. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"},"example":{"data":{"subscription":0,"topup":894,"total":894}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"listCredits","parameters":[{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/styles":{"get":{"tags":["Styles"],"summary":"List available style presets","description":"Returns all built-in style presets (cartoon, flat, pixel, kawaii, etc.) with preview URLs where available. Use `id` in generation prompts or as a style hint. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Available style presets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StylesResponse"},"example":{"data":[{"id":"cartoon","name":"Cartoon","description":"Fun, colorful with bold outlines","category":"classic","preview_url":"https://assets.masko.ai/7fced6/budget-buddy-2702/think-2bb9ff25.png"},{"id":"flat","name":"Flat","description":"Clean, minimal, geometric","category":"classic","preview_url":"https://assets.masko.ai/7fced6/turbo-9bb8/encourage-0791d248.png"},{"id":"pixel","name":"Pixel Art","description":"Retro 8-bit video game style","category":"retro","preview_url":"https://assets.masko.ai/7fced6/pixel-runner-f1fb/flex-06183f7f.png"}]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"listStyles","parameters":[{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/upload":{"post":{"tags":["Upload"],"summary":"Upload an image or video","description":"Accepts an image URL as JSON or an image/video file as multipart form data. Stores an asset owned by the caller and returns `data.asset_id` for use as a reference or `source_asset_id`. Malformed multipart data or a missing file returns 400. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadUrlBody"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"Uploaded asset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponse"},"example":{"data":{"asset_id":"e906ebb5-deb1-4010-82f9-f0182a3812e0"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"upload","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/generate/preview":{"post":{"tags":["Generate"],"summary":"Preview an idea before creating a collection","description":"Synchronous, throwaway image generation for iterating on mascot ideas cheaply before committing to a collection. No collection required. Tweak the prompt, regenerate, compare, then use the winning prompt + a reference image in POST /v1/collections. Also supports `reference_image_urls` to check \"does this prompt resemble my sketch?\". Returns signed URLs with a 1-hour expiry - the images are not stored. Costs 1 credit per image (the `cost` field in the response confirms the amount). Returns 402 if credits are insufficient.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewBody"}}}},"responses":{"200":{"description":"Preview images","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewResponse"},"example":{"data":{"images":[{"url":"https://storage.googleapis.com/masco-media/api-previews/.../3a0d33a8.jpeg?GoogleAccessId=...&Expires=...&Signature=...","expires_in":3600}],"cost":1}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"API version used to build this response.","schema":{"type":"string","example":"2026-09-26"}}}}},"operationId":"createGeneratePreview","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}]}},"/v1/analyze":{"post":{"tags":["Analyze"],"summary":"Analyze an image or website URL","description":"Analyzes an image (by URL) or a public website and returns a description, style hints, a suggested mascot name, and a suggested prompt ready to feed into POST `/v1/mascots`. When `type=url`, the response also includes a screenshot (omitted from example for brevity). No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StudioAnalyzeBody"},{"$ref":"#/components/schemas/AnalyzeBody"}]}}}},"responses":{"200":{"description":"Analysis result (image or url)","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AnalyzeImageResponse"},{"$ref":"#/components/schemas/AnalyzeUrlResponse"}]},"example":{"data":{"description":"A whimsical, wide-eyed ginger cat character designed with a claymation-like aesthetic. The cat features a plump, rounded body, a matte terracotta finish with fine dark speckles, and a charmingly surprised facial expression characterized by large circular eyes and thin, stylized whiskers.","style_hints":["Claymation","Terracotta texture","Matte finish","Rounded minimalist forms","Speckled surface","Soft studio lighting","3D sculpture"],"suggested_name":"Terracotta Tom","suggested_prompt":"A high-quality 3D render of a chubby ginger cat mascot in a claymation style. The cat is sitting, has a surprised expression with wide white eyes, a tiny pink nose, and thin clay whiskers. The material is matte terracotta orange with subtle dark speckles. Soft lighting, white background, clean minimalist aesthetic."}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"analyze","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions","description":"Returns all webhook subscriptions owned by the caller, including `consecutive_failures` and `active` flag. Webhooks are auto-deactivated after repeated delivery failures. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListResponse"},"example":{"data":[{"id":"7c358096-8521-463c-b9c3-fd81bddaffc3","url":"https://example.com","events":["job.completed"],"active":true,"consecutive_failures":3,"created_at":"2026-04-08T03:31:26.284516+00:00"}]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"listWebhooks","parameters":[{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]},"post":{"tags":["Webhooks"],"summary":"Create a webhook subscription","description":"Creates a webhook subscription. Returns 201 with the subscription record including a one-time `secret` used to verify future HMAC signatures - store it immediately, it is never returned again. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookBody"}}}},"responses":{"201":{"description":"Created webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"},"example":{"data":{"id":"5863639e-ad3f-4d4e-9bb3-12d0088d7d52","url":"https://example.com/test-webhook","events":["job.completed","job.failed"],"created_at":"2026-04-19T09:42:34.430422+00:00","secret":"whsec_3abe7a98aab0fcdb5c3b97142cf90dabccca37aa42974a198e7bdedb1148ce93"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"createWebhook","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}]}},"/v1/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete a webhook subscription","description":"Removes the webhook subscription - no further events will be delivered. Returns 204. No credit cost.\n\nSelect Masko-API-Version: 2026-09-26 (or api_version=2026-09-26) for the canonical mascot contract shown first. Existing unversioned clients keep legacy collection fields. A mascot_id query filter also selects the canonical contract. Mixing identifier names returns 400.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"in":"header","name":"Masko-API-Version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Use 2026-09-26 for mascot_id resource fields. Unversioned shared routes retain the legacy contract."},{"in":"query","name":"api_version","required":false,"schema":{"type":"string","enum":["2026-09-26","legacy"]},"description":"Equivalent to the version header, for polling URLs and clients that accept only relative paths. Header and query must agree."}],"responses":{"204":{"description":"Webhook deleted","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26","legacy"]}}}}},"operationId":"deleteWebhook"}},"/v1/canvases/{canvasId}/validate":{"get":{"tags":["Canvases"],"summary":"Validate the stored canvas graph","description":"Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. GET requires read access. A structurally invalid graph still returns 200 with data.valid=false.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"}],"responses":{"200":{"description":"Graph validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"code":{"type":"string"},"message":{"type":"string"},"nodeId":{"type":"string"},"edgeId":{"type":"string"}},"required":["severity","code","message"]}},"summary":{"type":"object","properties":{"errors":{"type":"number"},"warnings":{"type":"number"}},"required":["errors","warnings"]}},"required":["valid","issues","summary"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Missing or invalid credential.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient credential permissions.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot or canvas not found in this workspace.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Validation could not be completed.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"getCanvasValidate","x-masko-api-version":"2026-09-26"},"post":{"tags":["Canvases"],"summary":"Validate the stored canvas graph","description":"Checks graph structure and assigned media references without generating media or changing the graph. Draft edges without videos report missing-video; this is expected before animation generation. POST requires write access and accepts no body; prefer GET for read-only checks. A structurally invalid graph still returns 200 with data.valid=false.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Graph validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"code":{"type":"string"},"message":{"type":"string"},"nodeId":{"type":"string"},"edgeId":{"type":"string"}},"required":["severity","code","message"]}},"summary":{"type":"object","properties":{"errors":{"type":"number"},"warnings":{"type":"number"}},"required":["errors","warnings"]}},"required":["valid","issues","summary"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Missing or invalid credential.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient credential permissions.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot or canvas not found in this workspace.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Validation could not be completed.","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"validateCanvas","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/repair":{"post":{"tags":["Canvases"],"summary":"Repair canvas preview media","description":"Plans or starts a narrow repair for missing base WebM/HEVC derivatives on videos already assigned to this canvas. Agent workflow: first call with `dry_run=true` or omit `dry_run` because it defaults to true. Read `status.media.preview`, `summary`, `repairs`, `in_flight`, and `skipped`. If `status.media.preview.waiting_edges > 0`, wait and poll again instead of repairing. Only call again with `dry_run=false` if the repair plan matches the intended canvas videos. This endpoint is for the specific case where `status.media.generation.ready=true`, `status.media.preview.ready=false`, and `status.media.preview.repairable=true`. It does not regenerate animations, does not run mascot-wide jobs, does not create size variants, does not expose prompt/model controls, does not force regeneration, and does not archive existing assets.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepairCanvasBody"}}}},"responses":{"200":{"description":"Repair plan returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasRepairResponse"},"example":{"data":{"target":"video_derivatives","dry_run":true,"formats":["webm","hevc"],"status":{"generated_ready":true,"preview_ready":false,"media":{"generation":{"ready":true,"nodes":{"total":6,"completed":6,"pending":0,"failed":0},"edges":{"total":42,"completed":42,"pending":0,"failed":0}},"preview":{"ready":false,"repairable":true,"repairable_edges":2,"waiting_edges":0,"missing_edges":2,"missing_formats":["webm","hevc"]},"variants":{"sizes":["360"],"missing":[]}}},"summary":{"edges_checked":42,"videos_checked":38,"videos_ready":36,"videos_to_repair":2,"videos_in_flight":0,"videos_skipped":0},"repairs":[{"video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","edge_ids":["enter-hover-perk"],"missing":["webm","hevc"],"action":"create_derivatives"}],"in_flight":[],"skipped":[]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"202":{"description":"Repair jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasRepairResponse"},"example":{"data":{"target":"video_derivatives","dry_run":false,"formats":["webm","hevc"],"status":{"generated_ready":true,"preview_ready":false,"media":{"generation":{"ready":true,"nodes":{"total":6,"completed":6,"pending":0,"failed":0},"edges":{"total":42,"completed":42,"pending":0,"failed":0}},"preview":{"ready":false,"repairable":true,"repairable_edges":2,"waiting_edges":0,"missing_edges":2,"missing_formats":["webm","hevc"]},"variants":{"sizes":["360"],"missing":[]}}},"summary":{"edges_checked":42,"videos_checked":38,"videos_ready":36,"videos_to_repair":2,"videos_in_flight":0,"videos_skipped":0},"repairs":[{"video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","edge_ids":["enter-hover-perk"],"missing":["webm","hevc"],"action":"create_derivatives"}],"in_flight":[],"skipped":[],"jobs":[{"job_id":"a1b2c3d4-0000-0000-0000-000000000001","poll_url":"/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001?api_version=2026-09-26","video_asset_id":"a98ba960-c1b3-4bf5-9e6f-1d57b43c651d","edge_ids":["enter-hover-perk"],"formats":["webm","hevc"]}]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"repairCanvas","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/presentation/detect-facing":{"post":{"tags":["Canvases"],"summary":"Detect canvas natural facing","description":"Analyzes completed canvas node images and returns a suggested presentation.naturalFacing value plus node-level evidence. This is a synchronous analysis endpoint. It does not write to the canvas graph and has no credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Suggested natural-facing presentation value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasFacingDetectionResponse"},"example":{"data":{"suggestedNaturalFacing":"left","confidence":0.82,"analyzedNodeCount":3,"nodeResults":[{"nodeId":"idle","nodeName":"Idle","facing":"left","confidence":0.88,"reason":"The mascot has a consistent left-facing body angle."}]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"detectFacingCanvasPresentation","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/graph/extend":{"post":{"tags":["Canvases"],"summary":"Legacy partial canvas graph extension","deprecated":true,"description":"Deprecated compatibility endpoint. New authoring clients should read the complete graph and graph_content_hash, reconcile locally, and PATCH the complete graph with expected_graph_hash.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExtendCanvasGraphBody"}}}},"responses":{"200":{"description":"Canvas graph extended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasGraphExtendResponse"},"example":{"data":{"id":"280ceab9-4673-4c78-b37c-3617feb51914","name":"Main canvas","graph":{"nodes":[],"edges":[],"inputs":[],"viewport":{"x":0,"y":0,"zoom":1}},"updated_at":"2026-05-04T12:00:00.000Z","added":{"nodes":1,"edges":2,"inputs":1},"updated":{"edges":1}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"extendCanvasGraph","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/edges/{edgeId}":{"patch":{"tags":["Canvases"],"summary":"Patch a canvas edge","description":"Patches one edge without replacing the graph. Use this for speed tuning after generation: normal transitions use speed 2, snappy interact transitions use 3-4, held/special loops use 2, and calm loops use 1.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"edgeId","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchCanvasEdgeBody"}}}},"responses":{"200":{"description":"Canvas edge patched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEdgePatchResponse"},"example":{"data":{"id":"280ceab9-4673-4c78-b37c-3617feb51914","name":"Main canvas","edge":{"id":"idle-to-interact","source":"idle","target":"interact","duration":4,"speed":3},"graph":{"nodes":[],"edges":[],"inputs":[],"viewport":{"x":0,"y":0,"zoom":1}},"updated_at":"2026-05-04T12:00:00.000Z"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"updateCanvasEdge","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/edges/{edgeId}/generate":{"post":{"tags":["Canvases"],"summary":"Generate a single canvas edge","description":"Dispatches generation for one specific canvas edge by ID. Costs the same as a single edge in generate-all: duration * 2 for animation_model=standard or duration * 6 for premium. Without animation_model, legacy duration * 5 pricing is retained. If the edge already has a video asset, archives the old assets and re-dispatches. Any State edges (source: \"*\") and reverse edges are rejected with 400. Requires the source and target nodes to already have generated images. Loops use the source pose receipt, even on a mixed-variant canvas. Transitions retain both endpoint contexts. For uploads without receipts, the canvas context selects matching references; ambiguous shared uploads return 409 before charging.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"edgeId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateEdgeBody"}}}},"responses":{"202":{"description":"Edge generation started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasEdgeGenerateResponse"},"example":{"data":{"job_id":"a1b2c3d4-0000-0000-0000-000000000001","edge_id":"idle-to-interact","type":"transition","source":"Idle","target":"Interact","cost":20,"urls":{},"poll_url":"/v1/jobs/a1b2c3d4-0000-0000-0000-000000000001?api_version=2026-09-26"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"generateCanvasEdge","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/edges/{edgeId}/refine-mask":{"post":{"tags":["Canvases"],"summary":"Refine a canvas edge video mask","description":"Convenience wrapper around `POST /v1/assets/{id}/refine-mask` for a canvas edge. The route resolves the edge `videoAssetId`, refines that video asset mask, and re-exports the active derived formats/sizes. The canvas graph keeps the same raw video asset; desktop playback updates because the active linked WebM/HEVC/stacked variants are replaced underneath it. Any State and reverse edges are rejected because they do not own an independent video asset.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"edgeId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefineCanvasEdgeMaskBody"}}}},"responses":{"200":{"description":"Canvas edge mask refinement dry-run plan returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioAssetMaskRefinementResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"202":{"description":"Canvas edge mask refinement job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioAssetMaskRefinementResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"refineMaskCanvasEdge","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/generate-all":{"post":{"tags":["Canvases"],"summary":"Generate canvas images, stickers, and animations","description":"Kicks off generation for pending canvas node images, sticker derivatives, and/or edge animations. Pass animation_model=standard (2 credits/sec, 5–15s) or premium (6 credits/sec, 4–30s); both default to 5s. Omit the field for legacy generation (5 credits/sec, 4–10s, default 4s). Model choice is included in plan approval and idempotent replay checks. Requires a write key in the mascot workspace and project access, including for dry runs. Cross-workspace mascots return 404. Use `dry_run=true` first to preview planned work, prompts, skipped items, and estimated credits without creating jobs/assets or spending credits. Dry-run returns `plan_id` and `graph_content_hash`; send them as `approved_plan_id` and `expected_graph_hash` on execution so a changed graph, prompt, option, or selection returns 409 before spending. Use `targets=\"images\"` to generate poses, `targets=\"stickers\"` to backfill transparent sticker derivatives for completed node images, `targets=\"animations\"` for edge videos, or `include_stickers=true` to create stickers alongside newly generated images.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateAllBody"}}}},"responses":{"200":{"description":"Generation plan returned or jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanvasGenerateAllResponse"},"example":{"data":{"jobs":[{"job_id":"58341ab3-80fc-4fca-8a86-f9d2caee9a14","edge_id":"095872b7-c6f6-4f6d-8679-9739436fd16c","type":"transition","source":"Idle","target":"Waving","cost":20,"urls":{"webm":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-a622eb51.webm","video":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-7e5fe2ec.mp4","hevc":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/idle---waving-2880976b.mov"}}],"total_jobs":3,"total_cost":60,"dry_run":false,"generated":[],"skipped":0,"skipped_items":[],"reverse_free":[{"kind":"edge","id":"waving-to-idle","reason":"reverse_edge_free","reverse_of_edge_id":"idle-to-waving"}],"already_complete":[],"estimated_cost":60,"would_charge_credits":60,"actual_cost":60}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"generateAllCanvas","x-masko-api-version":"2026-09-26"}},"/v1/canvases/{canvasId}/export":{"get":{"tags":["Canvases"],"summary":"Export a canvas","description":"Exports the canvas as legacy MaskoAnimationConfig JSON by default, or as a target-specific delivery envelope with delivery=1. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"canvasId","in":"path"},{"schema":{"type":"string","enum":["json"]},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["1"],"description":"Return the delivery envelope instead of legacy MaskoAnimationConfig data."},"required":false,"description":"Return the delivery envelope instead of legacy MaskoAnimationConfig data.","name":"delivery","in":"query"},{"schema":{"type":"string","enum":["macos","windows","web","full"],"description":"Delivery media target. macos returns HEVC URLs, windows returns WebM URLs, web returns WebM and HEVC URLs, full returns all selected formats."},"required":false,"description":"Delivery media target. macos returns HEVC URLs, windows returns WebM URLs, web returns WebM and HEVC URLs, full returns all selected formats.","name":"target","in":"query"},{"schema":{"type":"string","enum":["selected","manifest"],"description":"Delivery mode. selected returns one variant; manifest includes known variants."},"required":false,"description":"Delivery mode. selected returns one variant; manifest includes known variants.","name":"mode","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Selected delivery size in pixels, if that size variant has already been generated."},"required":false,"description":"Selected delivery size in pixels, if that size variant has already been generated.","name":"size","in":"query"}],"responses":{"200":{"description":"Canvas export data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportConfigResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"getCanvasExport","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants":{"get":{"tags":["Mascots"],"summary":"List named mascot variants","description":"Lists the mascot’s named generation contexts. Variant authoring follows mascot project permissions, including authorized teammates; API keys must match the mascot workspace. Create and approve variants through the API or web app, then pass the id as variant_id to /generate. Selecting a generation variant does not change active playback. A null approved_at means the variant is still a draft.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Variants in creation order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MascotVariant"}},"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"has_more":{"type":"boolean"}},"required":["total","limit","offset","has_more"]}},"required":["pagination"]}},"required":["data","meta"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot not found in this workspace","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"listMascotVariants","x-masko-api-version":"2026-09-26"},"post":{"tags":["Mascots"],"summary":"Create a named mascot variant","description":"Creates a draft from Original or source_variant_id. The source context and references are frozen. Supply reference_asset_id to use an existing mascot image or your unassigned /v1/upload image and immediately approve the context, with no generation charge. Otherwise generate and approve a reference next. Reuse id for retries with the same inputs. This does not activate playback.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateMascotVariantBody"}}}},"responses":{"201":{"description":"Created variant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MascotVariant"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"createMascotVariant","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/{variantId}":{"get":{"tags":["Mascots"],"summary":"Read a variant and its reference candidates","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"responses":{"200":{"description":"Variant and candidate previews","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MascotVariantDetail"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"getMascotVariant","description":"Returns one variant with its reference candidates and approval state.","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/{variantId}/reference":{"post":{"tags":["Mascots"],"summary":"Generate a draft variant reference","description":"Costs 1 credit. Uses the frozen source references and the requested variant description. Reuse operation_id to retry the same job. Poll the job, inspect candidates with GET variant, then approve the selected candidate.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateVariantReferenceBody"}}}},"responses":{"202":{"description":"Reference generation queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"candidate_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"estimated_cost":{"type":"number"},"poll_url":{"type":"string"}},"required":["job_id","candidate_id","variant_id","estimated_cost","poll_url"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Not enough credits","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"createMascotVariantReference","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/{variantId}/approve":{"post":{"tags":["Mascots"],"summary":"Approve a generated variant reference","description":"Select a completed candidate belonging to this variant. Creates its canvas and makes variant_id usable for generation. Does not generate poses or change active playback. Repeating approval of the same candidate is safe.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveMascotVariantBody"}}}},"responses":{"200":{"description":"Approved variant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MascotVariant"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request or reference","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Variant creator required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or reference not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Draft source, changed operation inputs, or candidate not ready","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"approveMascotVariant","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/interactive":{"post":{"tags":["Generate"],"summary":"Generate a follow-cursor interaction","description":"Creates nine 1024×1024 transparent gaze directions from one completed image. Requires a completed transparent source or transparent derivative in the same mascot. Preserves the source variant automatically; no variant_id override. Optional name (maximum 60 characters after trimming) labels only the interaction; omitted or blank names use the source image name without renaming the image. Costs 9 credits. Returns an asynchronous job receipt. Send once and poll the returned job URL; repeating POST creates and charges a new set. Hosted mascots automatically publish a JSON manifest and nine lossless WebPs. Retrieve them with GET /v1/mascots/{id}/cdn-export after completion. This interaction is independent of Canvas state machines.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInteractionBody"}}}},"responses":{"202":{"description":"Nine-direction generation queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionGenerationResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Write access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Mascot or completed source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"422":{"description":"Transparent image required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"500":{"description":"Could not queue generation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"createMascotInteractive","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/logos/suggestions":{"get":{"tags":["Suggestions"],"summary":"Suggest logo directions and styles","description":"Five directions, including face portrait and full body, plus three suggested styles. Each direction can include a style. A style can be custom; preset_id is present only when it exactly matches a built-in preset. Returns defaults if generation is unavailable, unless refresh=true, which returns 503. No image credits; does not change the mascot.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"variant_id","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"refresh","in":"query"}],"responses":{"200":{"description":"Logo ideas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"prompt_version":{"type":"number"},"cached":{"type":"boolean"},"descriptions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"style":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"instruction":{"type":"string"},"preset_id":{"type":"string","enum":["graphic-app-icon","cut-paper","soft-depth","geometric","abstract-symbol","monoline-symbol","negative-space","retro-emblem","hand-drawn"]}},"required":["name","instruction"]}},"required":["name","description"]}},"styles":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"instruction":{"type":"string"},"preset_id":{"type":"string","enum":["graphic-app-icon","cut-paper","soft-depth","geometric","abstract-symbol","monoline-symbol","negative-space","retro-emblem","hand-drawn"]}},"required":["name","instruction"]}}},"required":["prompt_version","cached","descriptions","styles"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Write access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Source or mascot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Request ID conflict or variant not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"503":{"description":"Generation unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"listMascotLogoSuggestions","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/voice":{"get":{"tags":["Voice"],"summary":"Get the voice","description":"Returns the voice the mascot speaks with in talking animations, or null. A marketplace copy speaks with its creator's voice (source creator). sample_url is a short recording.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The voice, or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"getMascotVoice","x-masko-api-version":"2026-09-26"},"put":{"tags":["Voice"],"summary":"Keep a voice","description":"Keeps one sample from POST /v1/mascots/{id}/voice/samples as the voice of the mascot. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeepVoiceBody"}}}},"responses":{"200":{"description":"The kept voice","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"updateMascotVoice","x-masko-api-version":"2026-09-26"},"delete":{"tags":["Voice"],"summary":"Remove the voice","description":"Removes the mascot's voice. Talking animations already made keep their sound; new ones need a voice.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removed","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"deleteMascotVoice","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/voice/suggestions":{"get":{"tags":["Voice"],"summary":"Suggest voices","description":"Returns voice ideas written for the mascot from its references and description. Each description is ready for POST /v1/mascots/{id}/voice/samples. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Return other ideas than a plain request would."},"required":false,"description":"Return other ideas than a plain request would.","name":"refresh","in":"query"},{"schema":{"type":"string","maxLength":500,"description":"Comma-separated idea titles not to suggest again."},"required":false,"description":"Comma-separated idea titles not to suggest again.","name":"avoid","in":"query"}],"responses":{"200":{"description":"Voice ideas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"$ref":"#/components/schemas/VoiceIdea"}}},"required":["ideas"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"listMascotVoiceSuggestions","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/voice/adjust":{"post":{"tags":["Voice"],"summary":"Adjust a voice description","description":"Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustVoiceBody"}}}},"responses":{"200":{"description":"The rewritten description","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceAdjustment"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"adjustMascotVoice","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/voice/samples":{"post":{"tags":["Voice"],"summary":"Hear voice samples","description":"Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/mascots/{id}/voice within 24 hours.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceSamplesBody"}}}},"responses":{"201":{"description":"Three samples","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceSamples"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Not enough credits","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"createMascotVoiceSample","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/{variantId}/voice":{"get":{"tags":["Voice"],"summary":"Get the voice of a variant","description":"Returns the voice this variant speaks with: its own (source variant), the Original's until it gets one (source original), or null. sample_url is a short recording.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"responses":{"200":{"description":"The voice, or null","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"getMascotVariantVoice","x-masko-api-version":"2026-09-26"},"put":{"tags":["Voice"],"summary":"Keep a voice of a variant","description":"Keeps one sample from POST /v1/mascots/{id}/variants/{variantId}/voice/samples as the voice of an approved variant. It replaces the voice it had. Samples can be kept for 24 hours. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeepVoiceBody"}}}},"responses":{"200":{"description":"The kept voice","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Voice"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"updateMascotVariantVoice","x-masko-api-version":"2026-09-26"},"delete":{"tags":["Voice"],"summary":"Remove the voice of a variant","description":"Removes the variant's own voice; it speaks with the Original's voice again.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"responses":{"204":{"description":"Removed","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"deleteMascotVariantVoice","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/{variantId}/voice/suggestions":{"get":{"tags":["Voice"],"summary":"Suggest voices of a variant","description":"Returns voice ideas written for an approved variant from its references and description. Each description is ready for POST /v1/mascots/{id}/variants/{variantId}/voice/samples. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Return other ideas than a plain request would."},"required":false,"description":"Return other ideas than a plain request would.","name":"refresh","in":"query"},{"schema":{"type":"string","maxLength":500,"description":"Comma-separated idea titles not to suggest again."},"required":false,"description":"Comma-separated idea titles not to suggest again.","name":"avoid","in":"query"}],"responses":{"200":{"description":"Voice ideas","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ideas":{"type":"array","items":{"$ref":"#/components/schemas/VoiceIdea"}}},"required":["ideas"]}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"listMascotVariantVoiceSuggestions","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/{variantId}/voice/adjust":{"post":{"tags":["Voice"],"summary":"Adjust a voice description of a variant","description":"Rewrites a voice description in one direction, such as \"Older\" or \"Slower\", and returns what changed plus directions that fit the new text. Without direction, returns only directions. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustVoiceBody"}}}},"responses":{"200":{"description":"The rewritten description","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceAdjustment"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"adjustMascotVariantVoice","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/variants/{variantId}/voice/samples":{"post":{"tags":["Voice"],"summary":"Hear voice samples of a variant","description":"Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/mascots/{id}/variants/{variantId}/voice within 24 hours.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceSamplesBody"}}}},"responses":{"201":{"description":"Three samples","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VoiceSamples"}},"required":["data"]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Invalid request","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Not enough credits","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Adding a voice unlocks once the account has spent $50 on Masko (details.reason voice_locked, with paid_cents and required_cents), or the voice belongs to the Marketplace creator","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Mascot, variant or sample not found","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The variant is not approved yet, or the sample expired","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many voice requests; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Masko could not write the ideas or the adjustment; retry","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The voice service is unavailable; retry later","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"operationId":"createMascotVariantVoiceSample","x-masko-api-version":"2026-09-26"}},"/v1/mascots":{"get":{"tags":["Mascots"],"summary":"List mascots","description":"Returns all mascots owned by the authenticated user, paginated. A mascot is a single mascot character with its own style, references, and items. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter to this project."},"required":false,"description":"Filter to this project.","name":"project_id","in":"query"},{"schema":{"type":"string","description":"Filter by type, e.g. \"mascot\"."},"required":false,"description":"Filter by type, e.g. \"mascot\".","name":"type","in":"query"}],"responses":{"200":{"description":"List of mascots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"},"example":{"data":[{"id":"f9503022-a991-46ea-bf8c-d628c921b6b0","name":"v1-api-test-cat-1776591403","type":"mascot","project_id":"04dae799-dd9a-4296-ba86-9e3913c2f8d1","project_name":"test","is_published":true,"public_slug":"v1-api-test-cat-1776591403-rmau1uyd","user_prefix":"fda8417d","created_at":"2026-04-19T09:36:43.46139+00:00"}],"meta":{"pagination":{"total":6,"limit":5,"offset":0,"has_more":true}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"listMascots","x-masko-api-version":"2026-09-26"},"post":{"tags":["Mascots"],"summary":"Create a mascot","description":"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.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateMascotBody"}}}},"responses":{"201":{"description":"Created mascot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"},"example":{"data":{"id":"f9503022-a991-46ea-bf8c-d628c921b6b0","name":"v1-api-test-cat-1776591403","slug":"v1-api-test-cat-1776591403-rmau1uyd","type":"mascot","reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf"],"settings":{"cdn_enabled":true,"animation_sizes":[]}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"createMascot","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}":{"get":{"tags":["Mascots"],"summary":"Get mascot details","description":"Returns the full mascot record including config (prompt, reference_asset_ids, style_card, caution_list) and cdn_status. Returns 404 if the mascot does not exist or is not owned by the caller.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Mascot details with cdn_status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"},"example":{"data":{"id":"f9503022-a991-46ea-bf8c-d628c921b6b0","name":"v1-api-test-cat-1776591403","type":"mascot","project_id":"04dae799-dd9a-4296-ba86-9e3913c2f8d1","config":{"prompt":"terracotta clay cat mascot with big eyes and speckled texture","reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf"],"style_card":null,"caution_list":[]},"is_published":true,"slug":"v1-api-test-cat-1776591403-rmau1uyd","user_prefix":"fda8417d","cdn_status":[],"created_at":"2026-04-19T09:36:43.46139+00:00","updated_at":"2026-04-19T09:36:46.966862+00:00"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"getMascot","x-masko-api-version":"2026-09-26"},"patch":{"tags":["Mascots"],"summary":"Update mascot metadata","description":"Updates a mascot name, prompt, or public slug. Returns { updated: true }. Returns 404 if not found or not owned by the caller. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioUpdateMascotBody"}}}},"responses":{"200":{"description":"Updated mascot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatedFlagResponse"},"example":{"data":{"updated":true}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"updateMascot","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/items":{"get":{"tags":["Items"],"summary":"List items in a mascot","description":"Returns paginated items in a mascot. An item groups related assets (e.g. \"wave\" item may have an image, a transparent image, and animation variants). Filter by `type` to narrow results. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"List of items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemListResponse"},"example":{"data":[],"meta":{"pagination":{"total":0,"limit":5,"offset":0,"has_more":false}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"listMascotItems","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/items/{itemId}":{"get":{"tags":["Items"],"summary":"Get item details","description":"Returns the item record with all its generated assets (images, animations, logos). Returns 404 if the item does not exist or is not in the given mascot. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"responses":{"200":{"description":"Item details with assets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioItemResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"getMascotItem","x-masko-api-version":"2026-09-26"},"patch":{"tags":["Items"],"summary":"Update item name or prompt","description":"Updates the item name (used to derive the public slug) and/or the prompt. Does not re-generate assets. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateItemBody"}}}},"responses":{"200":{"description":"Updated item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioItemResponse"},"example":{"data":{"id":"e8ca0d1b-b445-46f6-862f-26b26ac2c6ff","name":"sitting-calmly","prompt":"sitting on ground with closed eyes peacefully","public_slug":"sitting","created_at":"2026-04-19T09:44:26.659167+00:00"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"updateMascotItem","x-masko-api-version":"2026-09-26"},"delete":{"tags":["Items"],"summary":"Archive an item","description":"Soft-deletes (archives) the item and its assets. Files are retained but filtered from reads. Returns 204 on success. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"itemId","in":"path"}],"responses":{"204":{"description":"Archived","headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"deleteMascotItem","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/assets":{"get":{"tags":["Assets"],"summary":"List assets in a mascot","description":"Returns paginated assets in a mascot (images, videos, transparent variants). Each asset has a signed `file_url` (1-hour expiry) and a `cdn_url` when published. Filter by `type` or `item_id`. Set `include_file_urls=false` for faster metadata-only listings. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Page size. 1 to 100. Defaults to 50."},"required":false,"description":"Page size. 1 to 100. Defaults to 50.","name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0,"description":"Number of records to skip. Defaults to 0."},"required":false,"description":"Number of records to skip. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Opaque next_cursor from the previous page. Use instead of offset."},"required":false,"description":"Opaque next_cursor from the previous page. Use instead of offset.","name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"item_id","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings."},"required":false,"description":"Whether to include signed file_url values. Defaults to true. Set false for faster metadata-only listings.","name":"include_file_urls","in":"query"}],"responses":{"200":{"description":"List of assets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioAssetListResponse"},"example":{"data":[{"id":"5114bec3-b92a-4917-8675-84fce713d3cf","type":"image","status":"completed","metadata":{},"item_id":null,"file_url":"https://storage.googleapis.com/masco-media/references/.../f4bdfb19.png?GoogleAccessId=...&Expires=...&Signature=...","cdn_url":null,"created_at":"2026-04-19T09:36:46.95543+00:00"}],"meta":{"pagination":{"total":2,"limit":5,"offset":0,"has_more":false}}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"listMascotAssets","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/cdn-export":{"get":{"tags":["Mascots"],"summary":"Export published CDN links","description":"Returns the same clean hosted-link JSON shown in the mascot page Get Links export modal. This endpoint is built from published CDN assets, not raw item types, so pose/image items with attached video loops are included. Includes image sticker URL arrays, animated_stickers grouped by sticker ID with telegram, whatsapp, wechat and discord URL keys in formats, and complete cursor-follower interactions with nine WebP frame URLs and a JSON manifest URL. Only completed, non-archived hosted assets are included. Create cursor followers with POST /v1/mascots/{id}/interactive. Use the raw items and assets endpoints for IDs, prompts, metadata, and status checks. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Mascot CDN export JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCdnExportResponse"},"example":{"mascot":"Fox Mascot","items":[{"name":"card-sit","image":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.png","transparent_image":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-transparent.png","animations":[{"video":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mp4","transparent_video_webm":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.webm","transparent_video_mov":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mov","transparent_video_android":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-android.mp4","transparent_video_android_360":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-360.mp4"}],"animated_stickers":[{"id":"22222222-2222-4222-8222-222222222222","source_asset_id":"33333333-3333-4333-8333-333333333333","formats":{"telegram":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webm","whatsapp":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.webp","wechat":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.gif","discord":"https://assets.masko.ai/fda8417d/fox-mascot/card-sit-sticker.png"}}]}]}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"CDN export is not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"getMascotCdnExport","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/references":{"post":{"tags":["References"],"summary":"Add a reference image","description":"Adds an image as a mascot-scoped style reference (up to 6 references). Pass either `url` to download and store a new reference, or `asset_id` to copy an existing uploaded/generated image into this mascot when needed. The returned `reference_asset_ids` are always mascot-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioAddReferenceBody"}}}},"responses":{"201":{"description":"Reference added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceResponse"},"example":{"data":{"reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf","b357dfe9-92ab-4696-beb3-4f36779808f2"]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"createMascotReference","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/references/{assetId}":{"delete":{"tags":["References"],"summary":"Remove a reference image","description":"Removes an asset from the mascot reference list. Returns the updated `reference_asset_ids` array. Invalidates the cached style_card. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"assetId","in":"path"}],"responses":{"200":{"description":"Reference removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceResponse"},"example":{"data":{"reference_asset_ids":["e906ebb5-deb1-4010-82f9-f0182a3812e0","5114bec3-b92a-4917-8675-84fce713d3cf"]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"deleteMascotReference","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/generate":{"post":{"tags":["Generate"],"summary":"Generate image or animation","description":"Starts an async generation job. Returns 202 with `data.job_id` - poll via GET `/v1/jobs/{id}` (or pass `?wait=true` for long-polling). Cost by type: image=1, animation=2/sec with animation_model=standard (5–15s) or 6/sec with animation_model=premium (4–30s), default 5s for either choice (+1 if no source image); omitting animation_model preserves legacy 5/sec, 4–10s, default 4s, logo=5, edit=1 for images, scene=3, reverse=0. For `type: animation`, you can skip providing a source image: pass only `animation_prompt` (and optionally `image_prompt`) and the system generates a fresh source image first, then animates it. To animate an uploaded image directly, pass its POST /v1/upload asset_id as source_image_asset_id with type=animation. The upload is imported into the mascot without changing references; no image-generation credits are charged. Existing mascot assets preserve their saved context. Before video generation, non-square starting and ending images are center-cropped to square; square images are reused unchanged. Optional source_image_crop and end_image_crop specify integer x, y, width and height in pixels after image orientation. Cropped copies preserve the originals and incur no extra credits. Invalid crops return 400 before charging. If you have an existing item, pass `item_id` to animate/edit its current image. For image generation and image edits, pass optional `visual_references` for one-time pose, expression, motion, prop, style, or scene cues; these references do not become mascot mascot references. Scene generation and scene editing also use this endpoint with `type: \"scene\"`. For a new scene, optional `source_asset_id` selects its character reference and saved variant context. For scene edits use `source_image_asset_id` with `edit_instructions`; the two source fields are mutually exclusive. Talking animations: pass `speech` with `type: animation` and the mascot says the line in its voice (see the Voice endpoints). The length follows the speech, 5 seconds to 5 minutes at 2 credits per second; the receipt charges the longest the line could need and unused seconds are refunded once the voice is recorded. Talking adds audio (MP3) and transcript (JSON) assets. With `dry_run: true` it returns 200 with the estimate instead. Returns 409 with details.reason voice_required when the mascot has no voice yet. Returns 402 if credits are insufficient.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioGenerateBody"}}}},"responses":{"200":{"description":"Talking estimate (speech with dry_run)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TalkingDryRunResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"202":{"description":"Generation job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateAsyncResponse"},"example":{"data":{"job_id":"b87c9579-7460-4bd0-aa54-77991615dfef","status":"pending","type":"image","item_id":"e328c567-0965-42fc-90b5-7ff6faa61b25","item_name":"wave","estimated_cost":1,"asset_ids":{"image":"a8b158bb-5698-431a-b0f1-98ee30228b11"},"urls":{"transparent_image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-91a9ac20.png","image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/wave-a8b158bb.png"},"poll_url":"/api/v1/jobs/b87c9579-7460-4bd0-aa54-77991615dfef?api_version=2026-09-26"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"generateMascot","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/animations/reference-video":{"post":{"tags":["Generate"],"summary":"Animate a mascot from a reference video","description":"From Video uses Premium to transfer reference motion to your mascot. Upload a video and its first frame through POST /v1/upload, then provide their asset IDs. Source assets must be completed, active, and accessible to the credential; mascot assets must belong to its workspace. Creates one animation item plus start and end pose items, with MP4, transparent WebM/HEVC, and pose images. Costs 6 credits per output second plus 1 image credit, so the default 5s costs 31 credits. Output duration is 4–30 whole seconds. Standard is not supported for this operation. Returns 202; poll the returned job until completed. Do not resubmit while the job is running.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioReferenceVideoBody"}}}},"responses":{"202":{"description":"Reference video job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceVideoAsyncResponse"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"createMascotAnimationReferenceVideo","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/generate-batch":{"post":{"tags":["Generate"],"summary":"Batch-generate multiple items","description":"Starts multiple generation jobs in one call (up to the per-request cap). Returns 202 with an array of `data.jobs[]`, each with its own `job_id`. Cost is summed across all items. Returns 402 if credits are insufficient for the whole batch.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioGenerateBatchBody"}}}},"responses":{"202":{"description":"Batch generation jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAsyncResponse"},"example":{"data":{"jobs":[{"job_id":"fe21477f-7e46-448f-bfdb-96eac80205b8","item_id":"e8ca0d1b-b445-46f6-862f-26b26ac2c6ff","item_name":"sitting","status":"pending","estimated_cost":1,"asset_ids":{"image":"25dc5edf-bf41-4a7f-ba23-b783ea2718d8"},"urls":{"transparent_image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-fb7bbd6f.png","image":"https://assets.masko.ai/fda8417d/cat-api-test-1776591702/sitting-25dc5edf.png"}}],"total_cost":2,"poll_url":"/api/v1/jobs?api_version=2026-09-26"}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"generateBatchMascot","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/suggestions":{"get":{"tags":["Generate"],"summary":"Suggest action poses","description":"Returns AI-generated action/pose suggestions (e.g. \"waving\", \"thinking\") tailored to the same resolved parent-plus-child mascot context used by generation. Use these as prompts for POST `/v1/mascots/{id}/generate`. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Use this approved mascot variant for suggestions. Omit for Original."},"required":false,"description":"Use this approved mascot variant for suggestions. Omit for Original.","name":"variant_id","in":"query"}],"responses":{"200":{"description":"Suggested actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestionsResponse"},"example":{"data":{"suggestions":["Curious Head Tilt","Wide Eyed Stare","Slow Clay Blink","Gentle Tail Wag","Heavy Paw Waddle","Playful Pounce","Happy Ear Twitch"]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"listMascotSuggestions","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/scenes/suggestions":{"get":{"tags":["Generate"],"summary":"Suggest scenes for a mascot","description":"Returns AI-generated scene ideas (setting + action + recommended position) tailored to the mascot. Use these as payloads for POST `/v1/mascots/{id}/generate` with `type: \"scene\"`. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Use this approved mascot variant for suggestions. Omit for Original."},"required":false,"description":"Use this approved mascot variant for suggestions. Omit for Original.","name":"variant_id","in":"query"},{"schema":{"type":"string","enum":["4:3","1:1","21:9","4:5","3:4","9:16"],"default":"4:5","description":"Aspect ratio to optimize the suggestions for. Defaults to 4:5."},"required":false,"description":"Aspect ratio to optimize the suggestions for. Defaults to 4:5.","name":"aspect_ratio","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":6,"description":"Number of scene suggestions to return. Defaults to 6, max 10."},"required":false,"description":"Number of scene suggestions to return. Defaults to 6, max 10.","name":"count","in":"query"}],"responses":{"200":{"description":"AI-suggested scenes for the mascot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SceneSuggestionsResponse"},"example":{"data":{"suggestions":[{"name":"Sunlit Terrace","emoji":"☀️","scene":"A sun-drenched Mediterranean stone balcony overlooking a sparkling blue coastline, decorated with potted succulents and blooming bougainvillea in earthen jars.","action":"Sitting contentedly among the flower pots and soaking up the afternoon warmth.","position":"center"}]}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"listMascotSceneSuggestions","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/settings":{"patch":{"tags":["Settings"],"summary":"Update mascot settings","description":"Updates mascot export settings. image_exports configures future PNG/WebP derivatives of original, transparent and sticker images; it does not backfill existing images. animation_sizes preserves existing behavior: changed settings may queue exports for existing animations as well as future outputs. Use POST /v1/mascots/{id}/exports for explicit image/video backfill, or the legacy size-variants endpoint for video-only repair. Returns settings_applied, size_variant_jobs and sizes_enabled. No credit cost.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSettingsBody"}}}},"responses":{"200":{"description":"Settings updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatedFlagResponse"},"example":{"data":{"updated":true}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"updateMascotSettings","x-masko-api-version":"2026-09-26"}},"/v1/mascots/{id}/size-variants":{"post":{"tags":["Settings"],"summary":"Backfill animation size variants","description":"Starts idempotent jobs for missing animation size variants on completed videos in this mascot. Normal pipeline usage sends `{}`: it uses the mascot configured `animation_sizes`, or `[360]` when no sizes are configured, and only creates missing variants. `force=true` is an explicit admin recovery option that regenerates existing variants too; do not use it for normal marketplace/canvas backfills or while relevant jobs are in flight. This endpoint does not regenerate source animations and does not toggle mascot settings.","security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":false,"description":"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.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioGenerateSizeVariantsBody"}}}},"responses":{"200":{"description":"Size variant jobs started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SizeVariantsResponse"},"example":{"data":{"size_variant_jobs":3,"sizes":[360],"force":false}}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Request-Id":{"description":"Unique ID of this request. Include it when contacting support.","schema":{"type":"string","example":"req_3f9c2a71d0b84e6a9c1f5e22"}},"Masko-API-Version":{"description":"Effective resource naming contract.","schema":{"type":"string","enum":["2026-09-26"]}}}}},"operationId":"createMascotSizeVariant","x-masko-api-version":"2026-09-26"}}},"x-tagGroups":[{"name":"Mascot","tags":["Mascots","Collections","Items","Assets","References","Voice","Settings"]},{"name":"Creating content","tags":["Generate","Canvases"]},{"name":"Platform","tags":["Projects","Applications","Jobs","Webhooks","Credits","Styles","Upload","Analyze"]}]}