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.

Each tool call incurs an additional charge. See pricing.

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