Generate experiences with Puck AI
Read docs
CloudAPI referencecloud-clientServer APIsai.generate

ai.generate

Generate a page, or update an existing one.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a page about dogs",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
});
// { root: { props: { title: "Pawesome Friends" } }, content: [ { type: "HeadingBlock", props: { id: "Heading-12345", title: "Discover Man's Best Friend" } } ] }

Returns a Generation.

Args

ParamExampleTypeStatus
params{ prompt: "", config: {} }ObjectRequired
options{ apiKey: "SECRET" }Object-

options

Set the request options for this call.

Params

What to generate, and how.

ParamExampleTypeStatus
promptprompt: "Create a page about dogs"StringRequired
configconfig: { components: {} }ConfigRequired
contextcontext: "We are Google"String-
designModedesignMode: { instructions: "..." }Object-
fieldTypesfieldTypes: { cta: {} }Object-
maxIterationsmaxIterations: 3Number-
modemode: "design""assembly" | "design"-
modelmodel: "openai/gpt-5.5"String-
onPartonPart: (part, respond) => {}Function-
pageDatapageData: { root: {}, content: [] }Data-
providerApiKeyproviderApiKey: "SECRET"String-
providerOptionsproviderOptions: { openai: {} }Object-
toolstools: {}Object-

Required params

prompt

A natural language prompt for the generation.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a page about dogs",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
});

config

The Puck config for the page.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a page about dogs",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
});

Optional params

context

Provide system context and instructions to the agent.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  context: "We are Google. Your job is to create Google landing pages.",
});

designMode

Customize design mode behaviour. Design mode is enabled via mode; these options tune how the agent designs components.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a pricing section with three tiers",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  mode: "design",
  designMode: {
    instructions: "Use our brand colors: #4285F4 for primary.",
    scripts: true,
  },
});

Designed components are stored on the returned data’s root under _dynamicConfig; render them with withDynamicConfig.

DesignModeOptions

ParamExampleTypeStatus
designMode.instructionsinstructions: "..."String-
designMode.modelmodel: "openai/gpt-6-sol"String-
designMode.providerOptionsproviderOptions: { openai: {} }Object-
designMode.scriptsscripts: trueBoolean-

designMode.instructions

Custom instructions injected into the design mode prompt.

designMode.model

Model override for design-mode requests. Defaults to model, or "openai/gpt-5.6-luna" if that’s unset.

designMode.providerOptions

Override providerOptions for design-mode requests.

designMode.scripts

Set to true to allow generated components to include scripts. Defaults to false.

fieldTypes

Describe AI behavior for your own field types as an object of AiGenerateFieldTypes.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a page about our products",
  config: {
    components: {
      Hero: {
        fields: {
          cta: { type: "cta" }, // Registered via overrides.fieldTypes
        },
        render: ({ cta }) => cta,
      },
    },
  },
  fieldTypes: {
    cta: {
      description: "Renders a branded call-to-action button",
      schema: {
        type: "object",
        properties: {
          label: { type: "string" },
        },
      },
    },
  },
});

In design mode, the agent can also declare these types on the components it generates.

maxIterations

How many times the agent can iterate. Defaults to 1. Capped at 50.

For values above 1, you must configure onPart and reply to data-client-request parts with the respond method.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  maxIterations: 3,
  onPart: (part) => handlePart(part),
});

mode

Set the mode used for generating the page. Can be:

  • "assembly" (default) — generate pages using the components in your config
  • "design" — generate new custom components to fulfil the prompt, incorporating existing components where possible

See design mode for more.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a pricing section with three tiers",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  mode: "design",
});

model

Select the model to use. By default, Puck uses openai/gpt-5.6-luna in both assembly and design modes. See model configuration for supported models.

We currently support Open AI models, which should be prefixed with openai/.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  model: "openai/gpt-5.5",
});

Without a providerApiKey, the request uses Puck AI credits and the model must be one of the supported models. Provide a key to run any OpenAI model on your own provider account.

Use designMode.model to override the model for design-mode requests.

onPart

A callback triggered for each AI Part as it’s generated.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  onPart: (part) => {
    // ...
  },
});

Args

ParamExampleType
part{ type: "data-page", data: {} }AIPart
respond() => {}Function
part

The current AIPart.

respond

A method for responding to data-client-request parts. You must do this when maxIterations is greater than 1.

const { data } = await puck.ai.generate({
  // ...
  onPart: async (part, respond) => {
    if (part.type === "data-client-request") {
      if (part.data.action === "getPageData") {
        return respond(pageData); // Provide latest page data
      } else {
        // Handle all other data-client-request types
      }
    }
    // ...
  },
});

pageData

Optional Data to consider when actioning the prompt.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Replace all mentions of Dog with Cat",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  pageData: {
    root: { props: { title: "Dogs: Man's Best Friend" } },
    content: [],
  },
});
// { root: { props: { title: "Cats: Man's Best Friend" } }, content: [] }

providerApiKey

Set the API key for the provider named in model to run Puck AI on your own provider account.

import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  model: "openai/gpt-4.1",
  providerApiKey: process.env.MY_OPENAI_KEY,
});

providerOptions

Pass configuration options through to the model call.

ParamExampleTypeStatus
openai.reasoningEffortopenai: { reasoningEffort: "low" }"none" | "minimal" | "low" | "medium" | "high" | "xhigh"-
openai.serviceTieropenai: { serviceTier: "priority" }"auto" | "default" | "flex" | "fast" | "priority"-
openai.textVerbosityopenai: { textVerbosity: "low" }"low" | "medium" | "high"-
import puckCloud from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a new homepage",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  providerOptions: {
    openai: {
      serviceTier: "priority", // Enable faster responses
    },
  },
});

Use designMode.providerOptions to override these options for design-mode requests.

tools

Define tools that enable the agent to execute functions on your server and retrieve data. The result of the tool will be factored into the request.

import puckCloud, { tool } from "@puckeditor/cloud-client";
 
const puck = puckCloud();
 
const { data } = await puck.ai.generate({
  prompt: "Create a page about our products",
  config: {
    components: {
      HeadingBlock: {
        fields: {
          title: { type: "text" },
        },
        render: ({ title }) => title,
      },
    },
  },
  tools: {
    getProducts: tool({
      description: "Get a list of product codes",
      inputSchema: z.object(),
      execute: async () => {
        return [
          {
            name: "Google Maps",
            product_code: "maps",
          },
          {
            name: "Google Calendar",
            product_code: "calendar",
          },
        ];
      },
    }),
  },
});

Returns

Returns an object with the shape:

ParamExampleType
datadata: { root: {}, content: [] }Data
tokenUsagetokenUsage: {}Object
totalCosttotalCost: 0.2Number

data

The generated page, as Puck Data.

tokenUsage

An object containing a breakdown of token consumption:

  • inputTokens
  • outputTokens
  • totalTokens
  • reasoningTokens
  • cachedInputTokens
  • cacheWriteTokens

totalCost

A number representing the total cost of the request.