generate
Generate a page, or update an existing one.
import { generate } from "@puckeditor/cloud-client";
const page = await 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 Puck Data object.
Params
| Param | Example | Type | Status |
|---|---|---|---|
prompt | "Create a page about dogs | String | Required |
config | { components: {} } | Config | Required |
context | "We are Google" | String | - |
designMode | { instructions: "..." } | Object | - |
mode | "design" | "assembly" | "design" | - |
model | "openai/gpt-4.1" | String | - |
pageData | { root: {}, content: [] } | Data | - |
providerApiKey | "SECRET" | String | - |
providerOptions | { openai: {} } | Object | - |
tools | {} | Object | - |
Required params
prompt
A natural language prompt for the generation.
import { generate } from "@puckeditor/cloud-client";
const page = await 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 { generate } from "@puckeditor/cloud-client";
const page = await generate({
prompt: "Create a page about dogs",
config: {
components: {
HeadingBlock: {
fields: {
title: { type: "text" },
},
render: ({ title }) => title,
},
},
},
});Optional params
apiKey
Set your API key. Will use the PUCK_API_KEY environment variable by default.
import { generate } from "@puckeditor/cloud-client";
const page = await generate({
prompt: "Create a new homepage",
config: {
components: {
HeadingBlock: {
fields: {
title: { type: "text" },
},
render: ({ title }) => title,
},
},
},
apiKey: process.env.MY_PUCK_KEY,
});context
Provide system context and instructions to the agent.
import { generate } from "@puckeditor/cloud-client";
const page = await 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.
| Param | Example | Type | Default | Description |
|---|---|---|---|---|
instructions | "..." | String | - | Custom instructions injected into the design mode prompt |
scripts | true | Boolean | false | Set to true to allow generated components to include scripts |
import { generate } from "@puckeditor/cloud-client";
const page = await 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.
host
Set a custom Puck Cloud host.
import { generate } from "@puckeditor/cloud-client";
const page = await generate({
prompt: "Create a new homepage",
config: {
components: {
HeadingBlock: {
fields: {
title: { type: "text" },
},
render: ({ title }) => title,
},
},
},
host: "https://www.example.com/api",
});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 { generate } from "@puckeditor/cloud-client";
const page = await 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 will use a managed model.
We currently support Open AI models, which should be prefixed with openai/.
import { generate } from "@puckeditor/cloud-client";
const page = await generate({
prompt: "Create a new homepage",
config: {
components: {
HeadingBlock: {
fields: {
title: { type: "text" },
},
render: ({ title }) => title,
},
},
},
model: "openai/gpt-4.1",
});When providing your own model, you must provide a providerApiKey.
onFinish
A callback triggered when the request is complete. Provides usage information.
import { generate } from "@puckeditor/cloud-client";
const page = await generate({
prompt: "Create a new homepage",
config: {
components: {
HeadingBlock: {
fields: {
title: { type: "text" },
},
render: ({ title }) => title,
},
},
},
onFinish: ({ totalCost, tokenUsage }) => {
console.log(`Used ${totalCost} credit`);
},
});OnFinish Params
| Param | Example | Type |
|---|---|---|
totalCost | 0.2 | number |
tokenUsage | {} | Object |
totalCost
A number representing the total cost of the request.
tokenUsage
An object containing a breakdown of token consumption:
- inputTokens
- outputTokens
- totalTokens
- reasoningTokens
- cachedInputTokens
pageData
Optional Data to consider when actioning the prompt.
import { generate } from "@puckeditor/cloud-client";
const page = await 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. Will use the OPENAI_API_KEY environment variable by default.
import { generate } from "@puckeditor/cloud-client";
const page = await 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 when using model.
| Param | Example | Type |
|---|---|---|
openai.reasoningEffort | "low" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" |
openai.serviceTier | "priority" | "auto" | "default" | "flex" | "priority" |
openai.textVerbosity | "low" | "low" | "medium" | "high" |
import { generate } from "@puckeditor/cloud-client";
const page = await 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: {
openai: {
serviceTier: "priority", // Enable faster responses
},
},
});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 { generate, tool } from "@puckeditor/cloud-client";
const page = await 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",
},
];
},
}),
},
});