AI Inspiration

Present-mode AI Inspiration APIs. Accessed via snaptrude.presentation.aiInspiration.

These APIs operate on Present canvas shape IDs and create outputs on the Present canvas. Pure backend generation without canvas output is out of scope. AI usage inherits the current user's AI quota.

Types

PluginAIInspirationShapeRef

Property	Type	Description
shapeId	string	Present canvas shape ID
assetId	string	Optional tldraw asset ID
kind	"image" | "view" | "video"	Shape kind
outputType	"source" | "image" | "video"	Whether the shape is an original source or AI output
sourceUrl	string	Optional resolved source URL when requested

PluginAIInspirationRecipe

Versioned recipe object extracted from AI workflow lineage or saved into project metadata. Recipes contain slots, ordered steps, output kind, thumbnail, timestamps, and a duplicate-detection fingerprint.

Functions

listModels()

List supported AI Inspiration models.

• Returns: Promise<{ defaultModelId: string; models: PluginAIInspirationModel[] }>

const { defaultModelId, models } = await snaptrude.presentation.aiInspiration.listModels();

---

getModelCapabilities(args)

Get capability flags for a model.

• Parameters:
  • args.modelId: string — Model ID from listModels
• Returns: Promise<{ capability: PluginAIInspirationModelCapability }>

const { capability } = await snaptrude.presentation.aiInspiration.getModelCapabilities({
  modelId: "nano-banana-pro-2k"
});

---

listSources(args)

List AI Inspiration-compatible shapes on the current Present page.

• Parameters:
  • args.includeGenerated: boolean — Include generated AI outputs. Defaults to true
  • args.includeSourceUrl: boolean — Resolve source URLs. Defaults to false
• Returns: Promise<{ sources: PluginAIInspirationShapeRef[] }>
• Throws: If Present mode is not open

const { sources } = await snaptrude.presentation.aiInspiration.listSources({
  includeGenerated: true
});

---

getSelection()

Get selected Present canvas shapes that can be used as AI Inspiration sources.

• Returns: Promise<{ selectedShapeIds: string[]; sources: PluginAIInspirationShapeRef[] }>
• Throws: If Present mode is not open

---

getPresetCatalog()

Get curated AI Inspiration preset categories and presets.

• Returns: Promise<{ categories: PluginAIInspirationPresetCategory[]; presets: PluginAIInspirationPreset[] }>

---

generate(args)

Generate an image or video from a Present canvas source.

• Parameters:
  • args.sourceShapeId: string — Source image or view shape ID
  • args.prompt: string — User prompt
  • args.modelId: string — Optional model ID
  • args.referenceShapeIds: string[] — Optional reference image/view shape IDs
  • args.appliedPreset: PluginAIInspirationAppliedPreset — Optional preset
  • args.site: PluginAIInspirationSiteOptions — Optional site context
  • args.regionHint: { x; y; w; h } — Optional image-region guidance
  • args.sketchGuidance: PluginAIInspirationSketchGuidance — Optional shape/text guidance
  • args.video: PluginAIInspirationVideoOptions — Optional video settings
  • args.runMode: "blocking" \| "job" — Defaults to blocking
• Returns: Promise<PluginAIInspirationRunResult>
• Throws: For unsupported model/input combinations, missing sources, or AI/backend failures

const { sources } = await snaptrude.presentation.aiInspiration.listSources({});
const result = await snaptrude.presentation.aiInspiration.generate({
  sourceShapeId: sources[0].shapeId,
  prompt: "Make this a warm dusk exterior render",
  modelId: "nano-banana-pro-2k",
  referenceShapeIds: sources.slice(1, 3).map((source) => source.shapeId)
});

Use job mode for long-running video, recipe, or branch rerun workflows:

const { jobId } = await snaptrude.presentation.aiInspiration.generate({
  sourceShapeId: "shape:source",
  prompt: "Animate a slow dolly into the entrance",
  modelId: "veo3",
  video: { mode: "animate", motion: "slow-dolly", duration: "6s" },
  runMode: "job"
});

const { job } = await snaptrude.presentation.aiInspiration.getJob({ jobId: jobId! });

---

refine(args)

Upscale/refine an AI Inspiration source image using the native Topaz CGI path.

• Parameters:
  • args.sourceShapeId: string
  • args.upscaleFactor: 1.5 | 2 | 4 — Defaults to 2
  • args.runMode: "blocking" \| "job" — Defaults to blocking
• Returns: Promise<PluginAIInspirationRunResult>

---

getJob(args), cancelJob(args), listJobs()

Inspect and cancel transient AI Inspiration jobs in the current host session.

Cancellation is best-effort for recipe and branch rerun jobs because the native recipe runner does not yet accept an abort signal. Generation and refine jobs use the native abortable paths.

---

getWorkflowForShape(args)

Get the sanitized AI workflow graph containing a Present shape.

• Parameters:
  • args.shapeId: string
• Returns: Promise<{ workflow: PluginAIInspirationWorkflow | null; node: PluginAIInspirationWorkflowNode | null }>

---

getSelectedBranchRerunPlan(args)

Build a rerun plan for the workflow branch ending at a generated shape.

• Parameters:
  • args.shapeId: string
• Returns: Ready plan data or an unavailable reason

---

rerunSelectedBranch(args)

Rerun a workflow branch and supersede the old branch metadata.

• Parameters:
  • args.shapeId: string
  • args.endFrameShapeId: string — Optional keyframe end frame
  • args.runMode: "blocking" \| "job" — Defaults to blocking
• Returns: Promise<PluginAIInspirationRunResult>

---

extractRecipeFromShape(args)

Extract a reusable recipe draft from the workflow path ending at a generated shape.

• Parameters:
  • args.shapeId: string
• Returns: { status: "ready"; draft } or { status: "unavailable"; reason }

---

listRecipes(), saveRecipe(args), deleteRecipe(args)

Manage project-level AI Inspiration recipes stored in Present document metadata.

const extraction = await snaptrude.presentation.aiInspiration.extractRecipeFromShape({
  shapeId: "shape:generated-output"
});

if (extraction.status === "ready") {
  await snaptrude.presentation.aiInspiration.saveRecipe({
    draft: extraction.draft,
    name: "Warm exterior workflow"
  });
}

---

runRecipe(args)

Run a saved or inline recipe against Present canvas slot shapes.

• Parameters:
  • args.recipeId: string — Saved recipe ID, required when recipe is omitted
  • args.recipe: PluginAIInspirationRecipe — Inline recipe, required when recipeId is omitted
  • args.slotShapeIds: Record<string, string> — Slot ID to Present shape ID, including source-image
  • args.runMode: "blocking" \| "job" — Defaults to blocking
• Returns: Promise<PluginAIInspirationRunResult>

const { recipes } = await snaptrude.presentation.aiInspiration.listRecipes();
await snaptrude.presentation.aiInspiration.runRecipe({
  recipeId: recipes[0].id,
  slotShapeIds: {
    "source-image": "shape:source"
  },
  runMode: "job"
});