videoclaw 3.0.0-alpha.1

package/references/video/seedance-transport-payloads.md

@@ -0,0 +1,144 @@
+# Seedance 2.0 Transport Payloads — videoclaw reference
+
+> **One model, three gateways.** `seedance-direct`, `runway-useapi`, and `dreamina-useapi`
+> all generate with the **Seedance 2.0** model — they differ only in the API gateway in
+> front of it. So the same prompt grammar, the same multi-reference identity-lock, the same
+> content moderation, and the same 9/3/3 reference budget apply to **all three**. This file
+> is the canonical, agent-readable reference for how to build the request to each.
+>
+> Confirmed 2026-05-30 from the live UseAPI docs (`useapi.net/docs/api-runwayml-v1`,
+> `useapi.net/docs/api-dreamina-v1`), the skill client `skills/video-replicator/scripts/seedance_client.py`,
+> and the production xskill/ARK payloads. Related: `ark-multireference-payload-contract` (memory),
+> `references/video/multi-shot-framework.md`, `references/video/seedance-ugc-formulas.md`.
+
+---
+
+## The canonical contract (what makes Seedance lock identity)
+
+Every Seedance submission, on any gateway, should follow this:
+
+1. **Multi-reference — one image reference per character.** Use the gateway's per-character
+   reference field (below), pointing at **managed asset references** (ARK `Asset://` avatars /
+   UseAPI uploaded asset ids), never raw photoreal face URLs (those trip the real-person filter
+   and don't lock identity).
+2. **Positional, visual-descriptor text — never proper names.** Describe each character by what
+   they look like and where they are: *"Center: long dark braid + dark coat (dual pistols). Left:
+   hooded olive jacket + sniper rifle. Right: tank top + twin knives."* The **order of the
+   reference fields matches the positional mapping** (ARK/UseAPI honor reference order).
+3. **No-face-morph line:** *"Keep each character identical to her reference image, no face morphing."*
+4. **Single-full-frame guard:** *"single continuous full-frame cinematic shot, no on-screen text."*
+   (Prevents grid/split-screen leakage when a storyboard grid is among the refs.)
+5. **The look in the text:** grade + grain + lighting + register
+   (e.g. *"desaturated earth tones, hard backlight, heavy 35mm film grain, Aditya Dhar war-thriller realism"*).
+
+**Output-dependent variables (parameters, NOT hardcoded — vary by the shot you need):**
+- `resolution` — 720p draft vs 1080p final (and the reference-asset resolution).
+- `duration` — e.g. 8s.
+- **scene-timing / TIMELINE** — a single kinetic shot has **no** timeline; a multi-beat sequence
+  includes one. Include it conditionally.
+- **audio** — off → omit; on → the text carries an explicit **diegetic soundscape**
+  (*"Diegetic sound only: wind, distant fire, embers, footsteps on grit. No music."*).
+
+---
+
+## Gateway A — `seedance-direct` (xskill / ARK)
+
+- **Host:** `https://api.xskill.ai` (env `VCLAW_SEEDANCE_BASE_URL`; auth `SUTUI_API_KEY`).
+- **Create:** `POST /api/v3/tasks/create` · **Poll:** `POST /api/v3/tasks/query` ·
+  **Cancel:** `POST /api/v3/tasks/cancel` · **Assets:** `POST /api/v3/assets` (+ `/assets/groups`).
+- **Body shape (flat task-create wrapper):**
+  ```json
+  {
+    "model": "ark/seedance-2.0",
+    "params": {
+      "prompt": "<full text>",
+      "ratio": "16:9",
+      "duration": "8",                // STRING for ARK
+      "model": "seedance_2.0",         // or "seedance_2.0_fast" (quality vs fast)
+      "resolution": "1080p",
+      "generate_audio": false,
+      "watermark": false,
+      "reference_images": ["Asset://...1", "Asset://...2", "Asset://...3"]
+    },
+    "channel": null
+  }
+  ```
+- **Reference rule** (`image_url` and `reference_images` are MUTUALLY EXCLUSIVE):
+  - 1 image → `image_url` (first-frame I2V).
+  - multiple images, all `Asset://` → `reference_images: [...]` (multi-character lock).
+  - mixed raw-HTTP + `Asset://` → use `image_url` only (drop sheets — raw faces trip the filter).
+  - also `reference_videos` (≤3), `reference_audios` (≤3).
+- **Asset Library:** register character images as avatars (`vclaw video seedance-register-assets`
+  → `artifacts/seedance-assets.json` → `Asset://` URIs) — this is the identity-lock mechanism.
+- **Newer "ARK passthrough" shape** (the production payload some accounts use; different endpoint):
+  `{ model:"ep-...", content:[{type:"text",text},{type:"image_url",image_url:{url:"asset://..."},role:"reference_image"}...], ratio, resolution, duration, generate_audio, watermark, _sub_model:"seedance_2.0", _ark_profile:"intl", _content_filter:"on", _api_key_id }`.
+  This is the OpenAI-style multimodal content-array form; `seedance_client.py` and videoclaw
+  currently use the flat `params` form above.
+
+## Gateway B — `runway-useapi` (Seedance 2.0 via UseAPI's Runway proxy)
+
+- **Host:** `https://api.useapi.net/v1` (auth `USEAPI_API_TOKEN` bearer).
+- **Create:** `POST /runwayml/videos/create` (unified endpoint; `model:"seedance-2"`).
+  **Assets:** `POST /runwayml/assets` → returns UUID `assetId`. Poll: `GET /runwayml/tasks/{taskId}`.
+- **Multi-reference (up to 11 mixed images+videos):** individual fields, **NOT an array**:
+  - `imageAssetId1` … `imageAssetId11` (UUID `assetId` each).
+  - `videoAssetId`, `videoAssetId2`, `videoAssetId3` (≤3 videos, ≤15s/≤720p each).
+  - prompt references them as `@IMG_1`…`@IMG_11`, `@VID_1`…`@VID_3`.
+- **Keyframe mode (mutually exclusive with multi-ref):** `startFrameAssetId`, `endFrameAssetId`.
+- **Core fields:** `model:"seedance-2"`, `text_prompt` (≤3500 chars), `duration` 4–15,
+  `aspect_ratio` (16:9/9:16/1:1/4:3/3:4/21:9), `resolution` 480p/720p/1080p, `audio` bool (default true),
+  `seed`, `exploreMode` bool (default false — explore = free/queued/low-res).
+- **videoclaw today (`native-runway.ts` / `providers/runway-useapi.ts`):** sends only ONE
+  keyframe (`startFrameAssetId`) — **does NOT yet use `imageAssetId1..N` multi-reference.** ⚠️
+
+## Gateway C — `dreamina-useapi` (Seedance 2.0 via UseAPI's Dreamina proxy)
+
+- **Host:** `https://api.useapi.net/v1` (auth `USEAPI_API_TOKEN`; account `VCLAW_DREAMINA_ACCOUNT`,
+  e.g. `CA:ai@example.com`).
+- **Create:** `POST /dreamina/videos` · **Poll:** `GET /dreamina/videos/{jobid}` ·
+  **Assets:** `POST /dreamina/assets/{account}` → returns an `assetRef`.
+- **Omni Reference (multi-character; up to 9 img + 3 video + 3 audio):** individual fields:
+  - `omni_1_imageRef` … `omni_9_imageRef` (each an `assetRef`).
+  - `omni_1_videoRef`…`omni_3_videoRef`, `omni_1_audioRef`…`omni_3_audioRef`.
+  - prompt references them as `@imageN` / `@videoN` / `@audioN`.
+- **Frame modes:** `firstFrameRef`, `endFrameRef` (needs firstFrameRef), `frame_N_imageRef` (N=1–10).
+- **Core fields:** `model:"seedance-2.0"` (or `-fast`), `prompt` (≤5000 chars), `ratio` (default 16:9,
+  auto-detected from refs), `resolution` 720p/1080p (1080p = CA accounts), `duration` (default 5),
+  `account`, `replyUrl`/`replyRef` (webhooks). **Input mode auto-detected** from which fields are present.
+  No documented `generate_audio` field.
+- **videoclaw today (`native-dreamina.ts`):** sends only ONE `firstFrameRef` — **does NOT yet use
+  `omni_N_imageRef` multi-reference.** ⚠️
+
+---
+
+## Reference-field cheat sheet (per character → field)
+
+| Gateway | Endpoint | Per-character image field | Prompt placeholder | Cap | Asset source |
+|---|---|---|---|---|---|
+| seedance-direct (ARK) | `xskill /api/v3/tasks/create` | `reference_images: [a,b,c]` (array) | (positional in text) | 9 img / 3 vid / 3 aud | `Asset://` avatar (Asset Library) |
+| runway-useapi | `useapi /runwayml/videos/create` | `imageAssetId1..11` (individual) | `@IMG_1..@IMG_11` | 11 mixed (≤3 vid) | `assetId` from `POST /runwayml/assets` |
+| dreamina-useapi | `useapi /dreamina/videos` | `omni_N_imageRef` N=1..9 (individual) | `@imageN` | 9 img / 3 vid / 3 aud | `assetRef` from `POST /dreamina/assets/{account}` |
+
+---
+
+## Content moderation (Seedance, all gateways)
+
+Server-side filters (tightened Feb 2026). Port in `src/video/seedance-content-filter.ts`
+(from `seedance_client.py`): `preValidatePrompt` (HIGH = celebrity/IP, minors, NSFW, political;
+MEDIUM = photoreal portrait, violence, brands), `sanitizePrompt(level 1|2)` (preserves `@image/@video/@audio`
+refs), `isContentViolation` (error code **2038** + Chinese 违规 patterns) → **retry-with-sanitization**.
+HIGH-risk → almost always blocked: real human faces as refs (use Asset/avatar refs), minors,
+celebrity/IP, NSFW, political. SAFE: stylized characters by visual descriptor, camera/motion language,
+own AI-generated stylized refs.
+
+## Consistency status (2026-05-30)
+
+| Item | seedance-direct | runway-useapi | dreamina-useapi |
+|---|---|---|---|
+| Multi-reference identity-lock | ✅ `reference_images` | ❌ single keyframe (target: `imageAssetId1..N`) | ❌ single keyframe (target: `omni_N_imageRef`) |
+| Content-filter / 2038 retry | being wired (`seedance-content-filter.ts`) | target: reuse same module | target: reuse same module |
+| Text discipline (descriptor/no-morph/single-frame) | shared `filmmaking-prompts.ts` packet builder → all routes | ✓ via shared builder | ✓ via shared builder |
+| Resolution / duration params | ✅ | ✅ | ✅ |
+| Scene-timing as parameter | target | target | target |
+
+Tracking branch: `feat/transport-skill-consistency`.

package/references/video/seedance-ugc-formulas.md

@@ -0,0 +1,104 @@
+# Seedance UGC Formulas
+
+## When to use
+
+Use for:
+
+1. character-led product ads
+2. UGC-style hooks
+3. stylized social clips
+4. short promotional scenes where motion and performance matter more than strict realism
+
+## Prompt formula
+
+1. subject identity
+2. environment
+3. primary action
+4. camera movement
+5. emotional tone
+6. lighting and texture
+7. audio cues if relevant
+8. negative constraints
+
+## UGC layer stack
+
+For ad-style or creator-style scenes, keep the prompt grounded in production layers:
+
+1. subject or presenter identity
+2. product or offer context
+3. first-second hook action
+4. proof, demo, or reaction beat
+5. hand, face, or product motion
+6. camera move and shot size
+7. lighting and practical texture
+8. spoken line or caption intent when audio is enabled
+9. transition or CTA beat
+
+Use only the layers that matter for the shot. A short Seedance clip should not carry a full script, multiple locations, and multiple camera moves at once.
+
+## Seedance-specific guidance
+
+1. Prefer concise, concrete prompts.
+2. Put the key action early.
+3. Keep one main camera move per shot.
+4. Use explicit continuity wording for recurring characters.
+5. For character continuity, prefer reference images over purely textual reminders.
+
+## Storyboard Image -> Seedance Motion
+
+Use separate prompts for the still storyboard frame and the Seedance animation pass:
+
+1. Storyboard image prompts describe static composition, character design, wardrobe, props, lighting, and framing.
+2. Seedance image-to-video prompts describe only the motion to add to that source image.
+3. Do not restate a full image-generation prompt in the Seedance prompt. Treat the imported frame as the source of truth.
+4. Keep the Seedance prompt to one visible action and one camera move for a short clip.
+5. Use natural motion and physics cues instead of abstract mood language.
+
+### Image-import prompt template
+
+```text
+Use the imported source image as the exact visual reference. Preserve the composition, framing, character appearance, outfit, props, environment, lighting direction, and color palette. Animate only: [one visible action]. Camera: [one move]. Keep movement natural and physically plausible for a [duration]-second clip. Do not change identity, wardrobe, scene layout, or object placement.
+```
+
+Recommended duration wording:
+
+1. `4-second clip` for a single gesture, reveal, product action, or facial reaction.
+2. `5-second clip` for a short walk, turn, handoff, or simple camera move.
+3. Avoid asking for scene changes, new locations, or multi-beat action in one Seedance pass.
+
+Dialogue guidance:
+
+1. Fit spoken dialogue to the clip length before execution.
+2. Treat 15 seconds as roughly 35-38 comfortable spoken words.
+3. Prefer one memorable line plus a visual proof beat.
+4. Move disclaimers, dense explanation, and multi-sentence objections into separate scenes.
+
+### Camera move vocabulary
+
+Use one of these per shot:
+
+1. `push-in` / `dolly in` - move closer to intensify attention on the subject.
+2. `pull-out` / `dolly out` - move away to reveal context or product placement.
+3. `tracking` - follow the subject laterally or forward through the frame.
+4. `orbit` - move around the subject while keeping them centered.
+5. `static` / `locked-off` - no camera travel; let performance or product motion carry the clip.
+6. `crane reveal` - rise or descend to reveal scale, environment, or a product detail.
+
+Shot-size terms are framing, not movement. `wide shot`, `medium shot`, and `close-up` can pair with one camera move, such as `wide shot, slow push-in`.
+
+## Adaptation checklist
+
+1. Does the prompt name one main subject?
+2. Is the camera direction singular and readable?
+3. Is the desired tone visible, not abstract?
+4. Are unsafe brand/IP references removed?
+5. Are continuity anchors stated when scenes are linked?
+
+## Failure patterns
+
+1. multiple unrelated actions in one prompt
+2. too many adjectives without a concrete action
+3. switching camera intent mid-prompt
+4. implicit continuity with no reference asset
+5. mixing static image-composition instructions with motion-only Seedance instructions
+6. using both a moving camera and `static` / `locked-off` in the same prompt

package/references/video/stage-directors.md

@@ -0,0 +1,47 @@
+# Video Stage Directors
+
+## Brief Director
+
+Must define:
+
+1. production mode
+2. target platform
+3. backend intent
+4. duration target
+5. success definition
+
+## Storyboard Director
+
+Must define:
+
+1. scene order
+2. beat pacing
+3. continuity requirements
+4. dialogue intent
+
+## Asset Director
+
+Must record:
+
+1. scene-to-asset mapping
+2. backend used
+3. failed assets
+4. retry reasons
+
+## Review Director
+
+Must check:
+
+1. visual quality
+2. character consistency
+3. artifact completeness
+4. subtitle or text contamination
+
+## Publish Director
+
+Must record:
+
+1. final output path
+2. variants
+3. unresolved issues
+4. publish readiness

package/references/video/style-template-schema.md

@@ -0,0 +1,40 @@
+# Style Template Schema
+
+## Purpose
+
+Store reusable style knowledge separately from one-off project execution.
+
+## Required fields
+
+1. `name`
+2. `sourceProject`
+3. `summary`
+4. `pacing`
+5. `structure`
+6. `motionClassification`
+7. `keep`
+8. `change`
+9. `reusableVariables`
+
+## Recommended additions
+
+1. primary provider
+2. preferred ratio
+3. continuity notes
+4. winning prompts
+5. failed prompt patterns
+6. benchmark runtime/cost notes
+
+## Reuse rule
+
+Templates should capture:
+
+1. what to preserve
+2. what to vary
+3. what to avoid
+
+They should not capture:
+
+1. provider-specific credentials
+2. one-off filesystem paths
+3. billing/account assumptions

package/references/video/veo-prompting-guide.md

@@ -0,0 +1,42 @@
+# Veo Prompting Guide
+
+## When to use
+
+Use for:
+
+1. direct local `veo-cli` execution
+2. text-to-video shots
+3. image-to-video shots where the first frame matters
+4. cleaner cinematic motion with straightforward prompt structure
+
+## Prompt formula
+
+1. shot tag
+2. optional image or frame reference
+3. core scene description
+4. visible action
+5. camera movement
+6. output framing or ratio intent
+
+## Veo-specific guidance
+
+1. Keep prompts literal and compact.
+2. Prefer one scene and one main action per call.
+3. Use the `image:` prefix for image-to-video.
+4. Use the `frames:` prefix only when start/end frame control is explicit.
+5. Avoid placeholder paths in real execution prompts.
+
+## Adaptation checklist
+
+1. Is the call text-to-video or image-to-video?
+2. Does the prompt describe visible motion instead of brand strategy language?
+3. Is the local `veo-cli` workspace present?
+4. Does `cookie.json` exist for direct mode?
+5. Is the expected output directory known before execution?
+
+## Failure patterns
+
+1. vague “make it cinematic” prompts without a visible action
+2. long concept paragraphs passed straight to `google.ts`
+3. mixed input modes in one prompt
+4. missing first-frame image for i2v calls

package/schemas/video/artifacts/analyze-output.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "vclaw-video-core/video/artifacts/analyze-output",
+  "type": "object",
+  "required": ["reference", "pacing", "structure", "motionClassification", "keep", "change", "reusableVariables", "generatedAt"],
+  "properties": {
+    "reference": {
+      "type": "object",
+      "required": ["source"],
+      "properties": {
+        "source": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "pacing": {
+      "type": "object",
+      "required": ["label", "notes"],
+      "properties": {
+        "label": { "type": "string", "enum": ["slow", "medium", "fast", "mixed"] },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "structure": {
+      "type": "object",
+      "required": ["beats"],
+      "properties": {
+        "beats": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "motionClassification": {
+      "type": "object",
+      "required": ["primaryMode", "notes"],
+      "properties": {
+        "primaryMode": { "type": "string", "enum": ["motion-clips", "animated-stills", "mixed", "unknown"] },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "keep": { "type": "array", "items": { "type": "string" } },
+    "change": { "type": "array", "items": { "type": "string" } },
+    "reusableVariables": { "type": "array", "items": { "type": "string" } },
+    "styleLayers": { "type": "array", "items": { "type": "string" } },
+    "beatCompression": {
+      "type": "object",
+      "properties": {
+        "targetDurationSeconds": { "type": "number" },
+        "maxBeats": { "type": "number" },
+        "dialogueWordBudget": { "type": "number" },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": true
+    },
+    "technicalNotes": { "type": "array", "items": { "type": "string" } },
+    "dialogueNotes": { "type": "array", "items": { "type": "string" } },
+    "generatedAt": { "type": "string" }
+  },
+  "additionalProperties": true
+}

package/schemas/video/artifacts/assemble-report.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "assemble-report",
+  "description": "Per-project report from `vclaw video assemble` — manifest of generated assets + final stitched output.",
+  "type": "object",
+  "required": ["projectSlug", "generatedAt", "status", "manifest"],
+  "properties": {
+    "projectSlug": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "status": { "type": "string", "enum": ["complete", "partial", "dry-run", "failed"] },
+    "brandProfile": { "type": ["string", "null"], "description": "Path to the brand-profile.json used for this run." },
+    "outputPath": { "type": "string", "description": "Path to the final stitched MP4." },
+    "manifest": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "path", "durationMs", "sizeBytes", "generator"],
+        "properties": {
+          "kind": { "type": "string", "enum": ["narration", "music", "title-card", "slide-animation", "rendered-clip", "final-video"] },
+          "path": { "type": "string" },
+          "durationMs": { "type": "number" },
+          "sceneIndex": { "type": "integer" },
+          "sizeBytes": { "type": "integer" },
+          "generator": { "type": "string", "description": "Which assemble/*.ts module produced this entry." }
+        }
+      }
+    },
+    "warnings": { "type": "array", "items": { "type": "string" } },
+    "events": { "type": "array", "items": { "type": "string" } },
+    "qc": {
+      "type": "object",
+      "description": "Structured media-quality audit over assembled scene clips and final master.",
+      "required": ["status", "clips", "issues"],
+      "properties": {
+        "status": { "type": "string", "enum": ["pass", "warning", "fail", "skipped"] },
+        "clips": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/qcClip" }
+        },
+        "master": { "$ref": "#/definitions/qcMaster" },
+        "issues": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/qcIssue" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "mediaProbe": {
+      "type": "object",
+      "properties": {
+        "durationSeconds": { "type": "number" },
+        "sizeBytes": { "type": "number" },
+        "videoCodec": { "type": "string" },
+        "width": { "type": "number" },
+        "height": { "type": "number" },
+        "frameRate": { "type": "string" },
+        "audioPresent": { "type": "boolean" },
+        "audioCodec": { "type": "string" },
+        "audioSampleRate": { "type": "number" },
+        "audioChannels": { "type": "number" }
+      }
+    },
+    "qcIssue": {
+      "type": "object",
+      "required": ["severity", "code", "scope", "message"],
+      "properties": {
+        "severity": { "type": "string", "enum": ["warning", "error"] },
+        "code": {
+          "type": "string",
+          "enum": [
+            "probe-failed",
+            "missing-audio",
+            "nonstandard-audio-codec",
+            "nonstandard-audio-sample-rate",
+            "nonstandard-video-codec",
+            "duration-drift"
+          ]
+        },
+        "scope": { "type": "string" },
+        "message": { "type": "string" }
+      }
+    },
+    "qcClip": {
+      "type": "object",
+      "required": ["path", "status", "issues"],
+      "properties": {
+        "path": { "type": "string" },
+        "sceneIndex": { "type": "integer" },
+        "status": { "type": "string", "enum": ["pass", "warning", "fail"] },
+        "durationMs": { "type": "number" },
+        "probe": { "$ref": "#/definitions/mediaProbe" },
+        "issues": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/qcIssue" }
+        }
+      }
+    },
+    "qcMaster": {
+      "type": "object",
+      "required": ["path", "status", "issues"],
+      "properties": {
+        "path": { "type": "string" },
+        "status": { "type": "string", "enum": ["pass", "warning", "fail"] },
+        "durationMs": { "type": "number" },
+        "expectedDurationMs": { "type": "number" },
+        "driftMs": { "type": "number" },
+        "probe": { "$ref": "#/definitions/mediaProbe" },
+        "issues": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/qcIssue" }
+        }
+      }
+    }
+  }
+}

package/schemas/video/artifacts/asset-manifest.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "vclaw-video-core/video/artifacts/asset-manifest",
+  "type": "object",
+  "required": ["projectSlug", "assets"],
+  "properties": {
+    "projectSlug": { "type": "string" },
+    "assets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "path"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "type": "string" },
+          "path": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/video/artifacts/batch-queue-manifest.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://vclaw.dev/schemas/video/artifacts/batch-queue-manifest.schema.json",
+  "title": "BatchQueueManifest",
+  "description": "Operator-authored manifest listing many independent video jobs to queue against a native route (default runway-useapi explore, which is free). Compiled into a single VideoExecutionPayload by buildBatchPayload().",
+  "type": "object",
+  "required": ["schemaVersion", "jobs"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "route": {
+      "type": "string",
+      "enum": ["runway-useapi", "dreamina-useapi", "seedance-direct"],
+      "description": "Native route to submit against. Defaults to runway-useapi (free explore mode) when omitted."
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "seconds": { "type": "number" },
+        "aspectRatio": { "type": "string", "enum": ["16:9", "9:16", "1:1"] },
+        "resolution": { "type": "string", "enum": ["720p", "1080p"] }
+      }
+    },
+    "jobs": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/BatchQueueJob" }
+    }
+  },
+  "definitions": {
+    "BatchQueueJob": {
+      "type": "object",
+      "required": ["id", "prompt"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "prompt": { "type": "string", "minLength": 1 },
+        "keyframe": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional first-frame reference; a local path or a public http(s) URL."
+        },
+        "endKeyframe": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional END-frame reference (local path or public http(s) URL). With 'keyframe' set, the clip animates from keyframe (first frame) to endKeyframe (last frame) via Seedance-2 keyframe interpolation, turning two stills into one continuous shot. Requires 'keyframe'; mutually exclusive with 'characterRefs'."
+        },
+        "characterRefs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Optional character reference images (local paths or public http(s) URLs), one per character. Delivered to the provider reference slot (never the first frame), so a lone character sheet does not open the clip on the character grid. Mutually exclusive with keyframe."
+        },
+        "seconds": { "type": "number" },
+        "aspectRatio": { "type": "string" }
+      }
+    }
+  }
+}