@amaster.ai/pi-video-gen 0.1.2-beta.48

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared types for pi-video-gen.
+ *
+ * The provider layer mirrors pi-image-gen's three-level split:
+ * wire format (`VideoApiStyle`) → model registry (`BuiltInVideoModel`) →
+ * resolved provider/model at runtime. Unlike image generation, vendor video
+ * APIs are async task APIs, so the adapter seam exposes the remote task
+ * lifecycle (`submit` / `inspect` / `downloadTo` / `cancel?`) instead of a
+ * single `generate()` — the remote task handle is what makes crash resume
+ * possible without double-billing.
+ */
+/** Wire format, NOT vendor — the same model via official or proxy endpoints differs only in baseUrl. */
+export type VideoApiStyle = 'ark' | 'kling' | 'dashscope' | 'openrouter' | 'newapi';
+export type VideoModelCapabilities = {
+    /** Max reference images a request may carry (0 = text-to-video only). */
+    maxReferenceImages: number;
+    /** Inclusive [min, max] clip duration in seconds. */
+    durations: [number, number];
+    resolutions: string[];
+    aspectRatios: string[];
+    /** Model generates synchronized speech/SFX/BGM natively (e.g. Seedance 2.0 `generate_audio`). */
+    nativeAudio: boolean;
+    /** First+last frame interpolation is actually honored by this endpoint. */
+    supportsFirstLastFrame: boolean;
+};
+export type BuiltInVideoModel = {
+    id: string;
+    aliases: string[];
+    provider: VideoApiStyle;
+    /** Remote model id sent to the provider (defaults to id). */
+    remoteId?: string;
+    capabilities: VideoModelCapabilities;
+    defaultResolution: string;
+    defaultAspectRatio: string;
+    defaultDurationSec: number;
+};
+export type ProviderSettings = {
+    apiKey?: string | undefined;
+    baseUrl?: string | undefined;
+};
+export type RateLimitSettings = {
+    maxRequestsPerMinute?: number | undefined;
+    maxRequestsPerDay?: number | undefined;
+};
+/** A user-defined video model routed through a custom (or built-in) provider. */
+export type CustomVideoModel = {
+    /** Remote model id sent to the provider. */
+    id: string;
+    /** Optional alias the agent / user can refer to. */
+    alias?: string | undefined;
+    /** Optional display name. */
+    name?: string | undefined;
+    /**
+     * Capability declaration driving tool schema and preflight. Omitted fields
+     * fall back to conservative defaults (no audio, no last-frame, 720p, 16:9).
+     */
+    capabilities?: VideoModelCapabilities | undefined;
+    defaultResolution?: string | undefined;
+    defaultAspectRatio?: string | undefined;
+    defaultDurationSec?: number | undefined;
+};
+/** A user-defined video-generation provider reusing a built-in wire format. */
+export type CustomVideoProvider = {
+    /**
+     * Wire shape this provider speaks. Determines which adapter calls it.
+     * Values are video-generation API shapes (e.g. the Ark task API), NOT pi.dev
+     * LLM streaming formats.
+     */
+    api: VideoApiStyle;
+    /**
+     * Override the API base URL. Optional for apis with a public default
+     * endpoint; REQUIRED for `newapi` (self-hosted relay — resolution fails
+     * without it).
+     */
+    baseUrl?: string | undefined;
+    /** API key. User/agent-dir settings support `$ENV_VAR` and `${ENV_VAR}` syntax. */
+    apiKey?: string | undefined;
+    /** Optional display name. */
+    name?: string | undefined;
+    /** Models routed through this provider. */
+    models?: Array<string | CustomVideoModel>;
+};
+export type VideoGenSettings = {
+    /** Job root directory. Defaults to `<cwd>/.video-gen`. */
+    outputDir?: string;
+    /** Model id or alias resolved against the built-in registry. */
+    defaultModel?: string;
+    /** Sensitive: honored from global/agent-dir settings layers only. */
+    providers?: Partial<Record<VideoApiStyle, ProviderSettings>>;
+    /** Sensitive: honored from global/agent-dir settings layers only. */
+    ffmpegPath?: string;
+    rateLimit?: RateLimitSettings;
+    concurrency?: {
+        clips?: number;
+    };
+    /**
+     * User-defined custom providers keyed by provider name (mirrors
+     * pi-image-gen's customProviders). Sensitive: global/agent-dir layers only.
+     */
+    customProviders?: Record<string, CustomVideoProvider>;
+};
+export type ResolvedProvider = {
+    style: VideoApiStyle;
+    apiKey?: string | undefined;
+    apiKeyPath?: string | undefined;
+    baseUrl: string;
+};
+export type ResolvedModel = {
+    entry: BuiltInVideoModel;
+    remoteId: string;
+    provider: ResolvedProvider;
+};
+export type GenerateVideoParams = {
+    prompt: string;
+    /** Stable orchestration identity for provider idempotency/recovery keys. */
+    requestId?: string | undefined;
+    firstFramePath?: string | undefined;
+    lastFramePath?: string | undefined;
+    /** Additional reference images (subject/style), roles mapped per provider. */
+    referenceImagePaths?: string[] | undefined;
+    durationSec?: number | undefined;
+    aspectRatio?: string | undefined;
+    resolution?: string | undefined;
+    /** Caller-side decision from capabilities.nativeAudio; adapter forwards it. */
+    generateAudio?: boolean | undefined;
+};
+export type RemoteTaskHandle = {
+    taskId: string;
+    /** ISO-8601 submission time. */
+    submittedAt: string;
+    /** Hash of model+prompt+frames+params, used to match a handle to its request on resume. */
+    requestFingerprint: string;
+    /** Adapter-specific resume data (e.g. Kling's task kind for the poll URL). */
+    meta?: Record<string, string> | undefined;
+};
+export type RemoteTaskStatus = {
+    phase: 'pending' | 'running';
+} | {
+    phase: 'succeeded';
+    videoUrl: string;
+} | {
+    phase: 'failed';
+    message: string;
+};
+export type VideoFileMeta = {
+    path: string;
+    bytes: number;
+};
+export type VideoProviderAdapter = {
+    /** Create the remote task. Caller persists the returned handle immediately. */
+    submit(provider: ResolvedProvider, remoteModelId: string, params: GenerateVideoParams, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<RemoteTaskHandle>;
+    /** Query task state. Resume entry point: with a handle, never re-submit. */
+    inspect(provider: ResolvedProvider, handle: RemoteTaskHandle, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<RemoteTaskStatus>;
+    /** Stream the finished video to destPath (temp file → limits → magic bytes → atomic rename). */
+    downloadTo(provider: ResolvedProvider, handle: RemoteTaskHandle, videoUrl: string, destPath: string, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<VideoFileMeta>;
+    /** Only implemented when the vendor exposes a cancel API; absent ⇒ local stop is `polling_stopped`. */
+    cancel?(provider: ResolvedProvider, handle: RemoteTaskHandle, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<{
+        cancelled: boolean;
+    }>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Shared types for pi-video-gen.
+ *
+ * The provider layer mirrors pi-image-gen's three-level split:
+ * wire format (`VideoApiStyle`) → model registry (`BuiltInVideoModel`) →
+ * resolved provider/model at runtime. Unlike image generation, vendor video
+ * APIs are async task APIs, so the adapter seam exposes the remote task
+ * lifecycle (`submit` / `inspect` / `downloadTo` / `cancel?`) instead of a
+ * single `generate()` — the remote task handle is what makes crash resume
+ * possible without double-billing.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@amaster.ai/pi-video-gen",
+  "version": "0.1.2-beta.48",
+  "description": "Pi extension for AI video generation plus local video composition: lossless clip concat and mixed image/video timelines with overlays, TTS, soft or burned subtitles, source audio, BGM, and bundled LGPL/GPL FFmpeg runtimes.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "video-generation",
+    "seedance",
+    "volcengine",
+    "ark",
+    "kling",
+    "agentic-video"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "preview.png"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/TGYD-helige/pi/master/packages/pi-video-gen/preview.png"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TGYD-helige/pi.git",
+    "directory": "packages/pi-video-gen"
+  },
+  "dependencies": {
+    "sharp": "^0.34.0",
+    "msedge-tts": "^2.0.7",
+    "@amaster.ai/pi-shared": "0.1.2-beta.48"
+  },
+  "optionalDependencies": {
+    "@amaster.ai/pi-video-gen-ffmpeg-darwin-x64": "0.1.2-beta.48",
+    "@amaster.ai/pi-video-gen-ffmpeg-linux-arm64": "0.1.2-beta.48",
+    "@amaster.ai/pi-video-gen-ffmpeg-darwin-arm64": "0.1.2-beta.48",
+    "@amaster.ai/pi-video-gen-ffmpeg-linux-x64": "0.1.2-beta.48",
+    "@amaster.ai/pi-video-gen-ffmpeg-win32-x64": "0.1.2-beta.48"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.80.10",
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.80.10",
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "typebox": "*",
+    "vitest": "^4.0.0",
+    "ffmpeg-static": "^5.2.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty false",
+    "test": "vitest run src"
+  }
+}

package/skills/video-gen/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: video-gen
+description: "Video creation and local composition: join existing clips or render mixed image/video timelines with video_compose, generate one AI clip with video_generate, or make a multi-shot AI film with video_render. Use when the deliverable is a video. Do NOT use for still images (use pi-image-gen directly)."
+---
+
+# Video generation
+
+This skill orchestrates four published flows:
+
+- **C0 local concat** — `video_compose` joins compatible existing MP4 clips.
+- **Timeline local render** — `video_compose` turns images/screenshots and
+  existing video clips into a video with overlays, TTS, motion, transitions,
+  soft or burned subtitles, source audio, and optional BGM.
+- **Single AI clip** — one paid `video_generate` call.
+- **Shot-book AI film** — author a shot book, generate frames with
+  `image_generate`, then ONE paid `video_render` call renders and stitches.
+
+The AI video model is fixed by `pi-video-gen.defaultModel`; generated images use
+pi-image-gen's active model.
+
+## A. Workflow rules
+
+0. **Route first.** Choose the right flow before anything:
+
+   | User goal | Flow |
+   |---|---|
+   | Existing local mp4 clips to join | `video_compose` (C0 — lossless, local, no paid models) |
+   | One AI-generated moving shot | `video_generate` |
+   | Multi-shot film with keyframes | `video_render` |
+   | Promo/explainer from images, screenshots & clips | `video_compose` (TimelineSpec — mixed media + overlays + TTS + transitions, local render, near-zero cost) |
+
+1. **Local flows stop here.** For C0 follow §A0; for Timeline follow §A1. Do not
+   run the AI preflight, shot-book steps, or paid confirmation gates below.
+   Timeline only needs `image_generate` when its source images do not already
+   exist.
+2. **AI preflight only.** For `video_generate` or `video_render`, call
+   `video_capabilities` and respect the active model's duration range and audio
+   support. Confirm `image_generate` is available only when source frames need
+   to be generated (`/video-gen doctor` checks; config health is
+   `/image-gen list`).
+3. **Pick the AI flow.** A vague idea or a script that needs multiple shots →
+   shot-book flow. One moving shot → `video_generate`. A still → pi-image-gen.
+4. **Write the shot book in conversation** (schema in §B). If the user only has a
+   vague idea, first be the screenwriter: three-act structure, filmable actions
+   ("show, don't tell"), concrete visual detail. Iterate with the user in chat.
+5. **Confirmation gate 1 (shot-book only).** Show the shot-book summary — shot count,
+   character list, estimated image calls (~2N+3C) and video calls (N) — and get an
+   explicit go-ahead. **Default small: 1 scene, 3–5 shots** unless the user asks
+   for more.
+6. **Image stage (shot-book only, via `image_generate`, per §C).** Character portraits →
+   per-shot first frame (and last frame when needed). Show each batch to the user.
+7. **Paid confirmation.** Before `video_generate`, confirm its one paid call.
+   For a shot book, once frames are ready, state "about to make N paid
+   video calls" and get an explicit render order. Then assemble the render spec
+   and call `video_render` ONCE.
+8. **Cost honesty.** AI video calls are paid and take minutes each. Never state
+   amounts (prices change); state call counts and durations.
+9. **Revisions.** The render spec is immutable per job directory. Text-stage
+   revisions happen in chat (regenerate frames as needed); a revised film goes in
+   a NEW job directory. NEVER suggest "delete shots/<id>/ and rerender" — that
+   breaks downstream dependencies. Rerunning the SAME spec path resumes an
+   interrupted job (finished shots don't re-bill).
+10. **Degradation negotiation.** If `video_render` preflight fails (e.g. last
+   frame unsupported), present the options (switch model / edit spec /
+   `allowDegradations`) and let the user choose. Never degrade silently. When the
+   model's `nativeAudio` is false, don't write audio cues into video prompts
+   unless the user accepted silence.
+11. **Cancellation honesty.** Interrupting stops local polling only — remote
+    tasks may keep running and billable (Ark cancellation is unverified). Say so.
+
+## A0. C0 — composing existing clips (`video_compose`)
+
+1. **Tell the user first**: clip count, order, output location
+   (`<jobDir>/final_video.mp4`), `mode: "copy"`. This is LOCAL compute — do
+   not use the paid-model confirmation script for it.
+2. Write `<jobDir>/compose-input.json`
+   (`{"clips":[{"id":"c1","path":"/abs/a.mp4"},…],"output":{"mode":"copy"}}`)
+   under the video-gen output dir, then call `video_compose` ONCE. Keep source
+   clips outside `<jobDir>/clips/`; that directory and `final_video.mp4` are
+   reserved pipeline outputs, and a fresh job refuses either conflict.
+3. **Only promise** lossless concat of compatible MP4s (C0). **Never promise**
+   trimming, transitions, overlays, subtitles, TTS, BGM, or re-encoding **for
+   the C0 path** — those live in the Timeline path (A1 below), not here; do
+   not hint at them for `compose-input.json`.
+4. On any ordered stream incompatibility across all tracks
+   (codec/resolution/fps/timebase/pix_fmt/sample-rate/audio layout), hand the
+   exact ffprobe differences back to the user/agent:
+   re-encode the odd clips first. NEVER silently transcode, and NEVER fall
+   back to `video_generate`/`video_render` as a workaround.
+5. Interrupted? Rerun the SAME path (fingerprint-verified resume / cached).
+   Changed clips or order? NEW job directory. A completed final video is
+   hash-bound; if it is missing or changed, restore the exact artifact or start
+   a NEW job.
+
+## A1. Timeline compose (`video_compose` with `timeline-input.json`)
+
+Use for promos/explainers from still images and existing clips. Costs ~0
+(Edge TTS is free, render is local) — prefer it over AI video for this job type.
+
+1. **Collect existing images/screenshots/clips first**, and use `image_generate`
+   only for missing visual material. Keep all source media outside the job
+   directory, then author `<jobDir>/timeline-input.json`.
+   `assets/`, `overlays/`, `audio/`, `segments/`, `qc/`, generated tracks,
+   subtitles, and `final_video.mp4` are reserved pipeline outputs; a fresh job
+   refuses any conflicts rather than deleting them.
+   ```jsonc
+   {
+     "title": "产品宣传片",
+     "output": { "resolution": "1920x1080", "fps": 25, "codec": "h264" },
+     "voice": "edge-tts:zh-CN-YunyangNeural",   // default; free, no key
+     "ttsFailureMode": "fail",                  // or "silent-subtitles" only after the user accepts that degradation
+     "subtitles": { "mode": "burn", "fontSize": 36,
+       "textColor": "#ffffff", "backgroundColor": "#000000", "backgroundOpacity": 0.55 },
+     "segments": [
+       {
+         "id": "intro",
+         "image": "/abs/frame-1.png",
+         "durationSec": 5,                      // image only: may be "auto" from narration
+         "motion": "kenburns-in",               // image only
+         "transitionTo": { "type": "xfade", "style": "fade", "durationSec": 0.8 },
+         "overlay": { "title": "标题", "subtitle": "副标题", "position": "bottom-left" },
+         "narration": "这一段的中文旁白文本"
+       },
+       {
+         "id": "demo",
+         "video": "/abs/demo.mp4",
+         "trimStartSec": 2.5,
+         "durationSec": 6,                      // video always uses a numeric duration
+         "fit": "contain",                      // contain | cover
+         "sourceAudio": { "muted": false, "volume": 0.25 }
+       }
+     ]
+   }
+   ```
+2. **Chinese text NEVER comes from an image model** — titles/subtitles go in
+   `overlay` and are rendered locally via SVG (no garbled CJK).
+3. **Cost confirmation is unnecessary** (local compute), but still show the
+   segment count and total planned duration before calling `video_compose`.
+4. Every segment contains exactly one of `image` or `video`. Video segments
+   are normalized to the output resolution/fps, may be trimmed/scaled, and
+   mix their source audio with narration before optional BGM. Video source
+   audio without a stream degrades to silence; `sourceAudio.muted: true` or
+   `volume: 0` disables it. A video's numeric `durationSec` is its fixed trim
+   window; narration that does not fit is rejected instead of extending it.
+5. Narration uses Edge TTS (free). Measured audio duration drives image
+   `durationSec: "auto"`; subtitles use each segment's actual video timing.
+   `subtitles.mode` defaults to `"soft"` (`mov_text`); `"burn"` renders the
+   configured font/color/background directly into each narrated segment.
+   TTS failures stop the job by default. Use `ttsFailureMode:
+   "silent-subtitles"` only as an explicit degradation choice; it keeps the
+   subtitle track and fills that segment with silence. Once accepted, that
+   degradation is cached for the immutable job; create a NEW job to retry
+   real narration.
+6. On completion, review the QC frames in `<jobDir>/qc/` yourself (Read the
+   PNGs) before showing the result — flipped/overlapping text only shows up
+   visually. Soft `mov_text` subtitles are not burned into those PNGs; the
+   pipeline separately verifies that the subtitle stream exists and that the
+   SRT cues match the resolved segment timeline.
+7. The spec is immutable per job: rerunning the same path resumes only
+   regular job-local artifacts whose manifest hashes still match; changes
+   require a NEW job directory. A committed artifact that is missing or
+   changed is rejected rather than regenerated underneath cached downstream
+   outputs. A completed manifest with any missing artifact hash is rejected;
+   an interrupted manifest invalidates unverified downstream hashes before
+   rebuilding an uncommitted upstream artifact.
+
+## B. Shot book (VideoProject) — authoring reference
+
+Author as JSON in conversation; save to `<jobDir>/project.json` for the record.
+
+```jsonc
+{
+  "title": "...", "style": "Cartoon",
+  "characters": [{ "id": "alice", "visible": true,
+    "appearance": "long blonde hair, blue eyes, slender",   // static features
+    "outfit": "red scarf, black leather jacket" }],          // dynamic features
+  "shots": [{
+    "id": "s1",
+    "intent": "Wide shot, rainy alley. <Alice> enters from the left, stops under the streetlamp…",
+    "firstFrame": "…pure static description of the FIRST frame…",
+    "lastFrame": "…(optional) pure static description of the LAST frame…",
+    "motion": "Static camera. A woman with long blonde hair and a red scarf walks in from the left…",
+    "audio": "[Sound Effect] rain, distant traffic. [Speaker] Alice (soft): \"We're here.\"",
+    "visibleCharacters": ["alice"],
+    "durationSec": 5,
+    "continuityGroup": "alley",
+    "startFrameFromShotId": "s0",   // optional: this shot's frame builds on s0's frame
+    "continuityNote": "In s0's frame Alice faces away; front view missing"
+  }]
+}
+```
+
+Field rules:
+
+- **Every shot needs a narrative purpose** (establish / emotion / reaction). First
+  shot: widest view of the scene. Close-ups for emotion, wide shots for context.
+- **At most one dialogue line per shot.** Character names in `intent` are wrapped
+  in angle brackets: `<Alice>`.
+- **firstFrame / lastFrame are pure static snapshots** — no ongoing actions
+  ("he is sitting, leaning forward", NOT "he is about to stand"). Include shot
+  size, angle, composition, who is where and facing which way.
+- **motion = camera movement + in-frame movement**, named separately. Refer to
+  characters by visible traits ("the woman in the red scarf"), never by name.
+- **lastFrame needed when**: composition/focus changes drastically, a character
+  enters or turns to face camera, a major reveal happens. Otherwise omit it.
+- **Few camera positions.** Default: one `continuityGroup` for everything. New
+  group only when shot size/angle/focus differs significantly.
+- **continuityGroup** = shots sharing a space/base image; **startFrameFromShotId**
+  pins a specific parent frame for composition; **continuityNote** says what the
+  parent frame lacks (the frame prompt must then keep the background and replace
+  those elements). Self-check: parent shot EXISTS, comes EARLIER, same
+  continuityGroup, no cycles.
+- **audio** uses `[Sound Effect] …` / `[Speaker] Name (Emotion): "line"` format.
+- **durationSec and all capability values come from `video_capabilities`** —
+  never from memory or this document. Durations, resolutions, ratios, audio and
+  frame support differ per model and change over time.
+- **Behavioral quirks worth knowing** (still verify with `video_capabilities`):
+  some models have no native audio (omit audio cues or the render is silent);
+  some cannot do last-frame interpolation (never pass lastFrame to them);
+  HappyHorse takes a first frame OR reference images in one call, not both —
+  cite references in the prompt as `[Image 1]`, `[Image 2]`, …
+
+## C. Image operation manual (via `image_generate`)
+
+Generic `image_generate` usage (params, sizes, `n`, edit labeling) follows the
+**pi-image-gen skill** — it is the single authority; do not deviate. Two
+video-specific handoff rules:
+
+- **Never assume a saved filename**: the actual extension follows the MIME type
+  and collisions get `-v2`. **The returned absolute path is the only truth** —
+  record it immediately in `assets.json` (see below) and reference it in the
+  render spec.
+- `assets.json` in the job dir: `{ "assets": { "<shotId>/<part>": { "sourcePath": "…" } } }`
+  mapping semantic assets (e.g. `s1/firstFrame`, `alice/front`) to real paths.
+
+**Character portraits (3 views per visible character)**:
+
+- front (text-to-image): `Generate a full-body, front-view portrait of character {identifier} based on the following description, with a pure white background. Use a wide 16:9 landscape canvas, not a vertical portrait canvas. The character should be centered in the image, occupying the middle of the wide frame with enough horizontal empty space. Gazing straight ahead. Standing with arms relaxed at sides. Natural expression. Features: {appearance}; {outfit}. Style: {style}`
+- side (edit with front as reference): `Generate a full-body, side-view portrait of character {identifier} based on the provided front-view portrait, with a pure white background. Use a wide 16:9 landscape canvas, not a vertical portrait canvas. The character should be centered in the image, occupying the middle of the wide frame with enough horizontal empty space. Facing left. Standing with arms relaxed at sides.`
+- back (edit with front as reference): `Generate a full-body, back-view portrait of character {identifier} based on the provided front-view portrait, with a pure white background. Use a wide 16:9 landscape canvas, not a vertical portrait canvas. The character should be centered in the image, occupying the middle of the wide frame with enough horizontal empty space. No facial features should be visible.`
+
+If side/back fails after one retry, reuse front. Characters with `visible: false`
+get no portraits.
+
+**Reference selection for frames**:
+candidates = portraits of visible characters (ONE view each, chosen by facing) +
+continuity frames. Pick a SMALL set of the most relevant ones — same
+camera/group first, most recent frames first, drop redundant near-duplicates,
+prefer the portrait when a character newly appears. How many images a call
+accepts is pi-image-gen's authority (its skill/tool description), not this
+document's.
+
+**Frame prompt assembly**: prefix each reference image with its role, then the
+frame description mapping elements to images:
+
+```
+Image 0: A front view portrait of Alice.
+Image 1: [alley] Wide shot of the rainy alley from shot s1.
+Create an image based on the following description: <firstFrame text>. The alley
+background should reference Image 1; Alice's appearance should reference Image 0.
+```
+
+## D. Assemble the render spec and render
+
+Write `<outputDir>/<jobId>/render-input.json` (jobId: letters/digits/dash/underscore):
+
+```jsonc
+{
+  "title": "…", "aspectRatio": "16:9",
+  "shots": [{
+    "id": "s1",
+    "videoPrompt": "<motion> + <audio cues>",
+    "firstFramePath": "/abs/path/from/assets.json.png",
+    "lastFramePath": "/abs/optional.png",
+    "durationSec": 5
+  }]
+}
+```
+
+Then call `video_render` with that path. Interrupted? Call it again with the
+same path — it resumes. If an ambiguous submit is reported, do not delete a
+shot or call render again blindly: run `/video-gen recover <jobId>`, check the
+provider console, then explicitly `reset` a confirmed-absent task or `adopt`
+its task id. Revisions? New job directory.