Create and manage AI generations—characters, scenes, music, sprites, and more. Poll status or stream progress via SSE.

Generations Subclient

The client.generations subclient lets you create and manage AI generation jobs—characters, scenes, 3D splats, music, sprites, voices, images, and videos. Submit a prompt (and optional reference image), receive a generation ID, then poll or stream progress until the asset is ready.

Methods

Method	Signature	Description
`create`	`(params) => Promise<string>`	Start a generation; returns ID
`get`	`(id: string) => Promise<GenerationRecord>`	Fetch a generation by ID
`list`	`() => Promise<GenerationRecord[]>`	List all your generations
`delete`	`(id: string) => Promise<void>`	Delete a generation
`listen`	`(id: string) => ListenResult`	SSE stream for a single generation's progress

create(params)

create(params: {
  type: GenerationType;
  input: Record<string, unknown>;
  refType?: string;
  refId?: string;
}): Promise<string>

Starts a new generation job. Returns the generation ID immediately. The job runs asynchronously.

get(id)

get(id: string): Promise<GenerationRecord>

Fetches the current state of a generation. Use this to poll until state is 'done' or 'error'.

list()

list(): Promise<GenerationRecord[]>

Returns all generations for the authenticated user.

delete(id)

delete(id: string): Promise<void>

Deletes a generation by ID.

listen(id)

listen(id: string): { events: EventTarget; unsubscribe: () => void }

Subscribes to Server-Sent Events for a single generation's progress. Call unsubscribe() when done.

const { events, unsubscribe } = client.generations.listen(id);

events.addEventListener('change', (e: MessageEvent) => {
  const detail = e.data;
  console.log('Progress:', detail);
});

events.addEventListener('error', (e: MessageEvent) => {
  console.error('Stream error:', e.data);
});

// When done
unsubscribe();

Generation Types

Type	Description
`character`	AI-generated character from prompt or image
`sceneImage`	2D scene/background image
`sceneImageSplat`	Scene image → splat pipeline
`scene360`	360° panoramic scene
`sceneSplat`	3D Gaussian splat from reference
`sceneMarble`	Marble-style scene
`characterRender`	Rendered character from preview + spritesheet
`item`	In-world item asset
`sprite`	2D sprite asset
`mob`	Mobile entity sprite
`music`	AI-generated music track
`soundEffect`	Short audio clip
`image`	Generic image generation
`video`	AI-generated video clip
`object`	3D object
`code`	Code generation

Input Parameters

Input varies by type. Common fields:

Field	Type	Description
`prompt`	`string`	Text prompt for the generation
`imageUrl`	`string`	URL of input/reference image
`smartPrompt`	`boolean`	Use AI to enhance the prompt
`splatUrl`	`string`	(sceneSplat) URL of reference splat
`musicLengthMs`	`number`	(music) Length in milliseconds
`durationSeconds`	`number`	(soundEffect) Clip duration
`model`	`string`	(image/video) Model identifier

Enable smartPrompt: true to let the platform enhance short or vague prompts before sending them to the pipeline.

Streaming Events via listen()

The listen() method returns an EventTarget that emits change events as the generation progresses. Each event's data contains the latest state or log entry.

import { PUClient } from 'pu-client';

const client = new PUClient({ apiKey: process.env.PU_API_KEY! });

const id = await client.generations.create({
  type: 'character',
  input: { prompt: 'A wise owl wizard', smartPrompt: true },
});

// Poll until done
let gen = await client.generations.get(id);
while (gen.state !== 'done' && gen.state !== 'error') {
  await new Promise(r => setTimeout(r, 2000));
  gen = await client.generations.get(id);
}

if (gen.state === 'done') {
  console.log('Output:', gen.output);
}

import { PUClient } from 'pu-client';

const client = new PUClient({ apiKey: process.env.PU_API_KEY! });

const id = await client.generations.create({
  type: 'sceneImage',
  input: { prompt: 'Cozy cabin in snow', smartPrompt: true },
});

const { events, unsubscribe } = client.generations.listen(id);

events.addEventListener('change', (e: MessageEvent) => {
  console.log('Progress:', e.data);
});

events.addEventListener('error', (e: MessageEvent) => {
  console.error('Stream error:', e.data);
  unsubscribe();
});

// Unsubscribe when you're done (e.g. on unmount)
// unsubscribe();

Full Code Examples

Create a character

const id = await client.generations.create({
  type: 'character',
  input: {
    prompt: 'A steampunk fox inventor with goggles',
    smartPrompt: true,
  },
});

Create a scene from an image

const id = await client.generations.create({
  type: 'sceneSplat',
  input: {
    splatUrl: 'https://example.com/reference-room.jpg',
  },
});

Create music

const id = await client.generations.create({
  type: 'music',
  input: {
    prompt: 'Ambient forest with soft piano',
    musicLengthMs: 120000,
  },
});

List and delete failed generations

const generations = await client.generations.list();
const failed = generations.filter(g => g.state === 'error');

for (const g of failed) {
  await client.generations.delete(g.id);
  console.log(`Deleted ${g.id}`);
}

GenerationRecord

Field	Type	Description
`id`	`string`	Generation ID
`type`	`GenerationType`	Generation type
`state`	`'pending' \| 'done' \| 'error'`	Current state
`input`	`Record<string, GenerationParam>`	Input parameters
`output`	`Record<string, GenerationParam>`	Output assets (when done)
`error`	`string \| null`	Error message (when failed)
`created_at`	`string`	Creation timestamp
`refType`	`string \| null`	Optional reference type
`refId`	`string \| null`	Optional reference ID