Step-by-step tutorial to generate characters, scenes, 3D models, and music. Includes streaming progress and both SDK and CLI approaches.

Generate Assets

This tutorial shows you how to create AI-generated assets—characters, scene images, 3D models from images, and music. You'll learn to poll for completion, stream progress via SSE, and view your generation history.

Prerequisites

Install pu-client and get your API key from Account > Developer. Set PU_API_KEY in your environment.

Step-by-Step: Generate Multiple Asset Types

1. Generate a character from a prompt

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

puc character create -p "A steampunk inventor with goggles" --smartPrompt

2. Generate a scene image

const sceneId = await client.generations.create({
  type: 'sceneImage',
  input: {
    prompt: 'Cozy cabin in a snowy forest at dusk',
    smartPrompt: true,
  },
});

puc scene-image create -p "Cozy cabin in a snowy forest at dusk" --smartPrompt

3. Generate a 3D model from an image

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

puc scene-splat create --splatUrl "https://example.com/your-room-photo.jpg"

4. Generate music

const musicId = await client.generations.create({
  type: 'music',
  input: {
    prompt: 'Ambient forest with soft piano',
    musicLengthMs: 60000,  // 1 minute
  },
});

puc generations create music --input '{"prompt":"Ambient forest with soft piano","musicLengthMs":60000}'

5. View all generations in history

const generations = await client.generations.list();
generations.forEach(g => {
  console.log(`${g.type}: ${g.state} (${g.id})`);
});

puc generations list --json

Streaming Progress

For longer-running generations, stream progress via Server-Sent Events instead of polling:

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

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

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

const id = await client.generations.create({
  type: 'sceneImage',
  input: { prompt: 'Mystical cave with crystals', 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();
});

// When done processing, call unsubscribe()

Full Example: Character + Scene + Poll

import { PUClient } from 'pu-client';

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

  // 1. Character
  const charId = await client.generations.create({
    type: 'character',
    input: { prompt: 'A cyberpunk hacker', smartPrompt: true },
  });

  // 2. Scene
  const sceneId = await client.generations.create({
    type: 'sceneImage',
    input: { prompt: 'Neon-lit city alley', smartPrompt: true },
  });

  // Poll both
  async function waitUntilDone(id: string) {
    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);
    }
    return gen;
  }

  const [char, scene] = await Promise.all([
    waitUntilDone(charId),
    waitUntilDone(sceneId),
  ]);

  console.log('Character:', char.output);
  console.log('Scene:', scene.output);
}

Next Steps

Generations Reference

All generation types, parameters, and streaming API.

Assets

Fetch and download generated assets (characters, scenes, music).

CLI Commands

Full reference for puc character, puc scene-image, and more.

Generations Reference

Assets

CLI Commands

On this page