API ReferenceAICloud Clientgenerate

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	-
`pageData`	`{ root: {}, content: [] }`	Data	-
`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.",
});

`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",
});

`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: [] }

`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",
          },
        ];
      },
    }),
  },
});

chat

puckHandler