# Puppetto Asset Generation Guide For Agents

Use this file when generating images, speech, music, sound effects, video, lipsync, 3D assets, source-asset edits, or narration files through Puppetto MCP.

## Core Flow

1. Call `puppetto_list_asset_generation_integrations`.
2. Filter with `assetType` when known: `image`, `speech`, `music`, `sound_effect`, `video`, `lipsync`, or `3d`.
3. Choose a connected provider and model from the returned `models`, `controls`, and `assetTypes`.
4. Call `puppetto_estimate_asset_generation`.
5. Call `puppetto_generate_asset`.
6. Poll `puppetto_list_in_progress_assets`.
7. Read the completed asset with `puppetto_get_asset`.
8. Attach it to a post with `puppetto_add_post_assets` if needed.

## Generate Narration Or Vocal Files

Use `assetType: "speech"` for spoken narration.

```json
{
  "assetType": "speech",
  "integration": "elevenlabs",
  "prompt": "Narration script goes here.",
  "options": {
    "voiceId": "<voice id from provider controls or prior selection>",
    "modelId": "<provider model id>"
  },
  "postId": "<optional post id>",
  "characterId": "<optional character id>"
}
```

If the voice provider metadata returns different control keys, use those keys in `options`. Keep the narration script in `prompt`.

## Source-Asset Edits

Use `sourceAssetIds` when generating from existing assets:

```json
{
  "assetType": "image",
  "integration": "openai",
  "prompt": "Edit this campaign image into a square social ad.",
  "sourceAssetIds": ["<asset id>"],
  "options": {
    "size": "1024x1024"
  }
}
```

## Linking Rules

- Include `characterId` when the asset belongs to a character.
- Include `postId` when the asset belongs to a campaign post.
- Include both when creating character-led post media.
- Include `sourceAssetIds` for derivative generation or edits.

## Common Asset Types

- `image`: campaign hero images, social visuals, transparent PNGs.
- `speech`: spoken narration or character voice lines.
- `music`: background music or instrumental beds.
- `sound_effect`: short SFX assets.
- `video`: generated or rendered video assets.
- `lipsync`: generated talking-head or synced performance assets.
- `3d`: generated 3D model assets.