veogent 1.5.1 → 1.6.0

package/README.md

@@ -98,20 +98,23 @@ veogent create-scene --project <projectId> --chapter <chapterId> \
   --lang English --material CINEMATIC --scenes 5 --wait
 ```
 
-#### Phase 3: Generate Images + Videos
+#### Phase 3: Generate Images + Videos (Async Polling)
 
 ```bash
-# Generate all images
+# 1. Trigger generation (without --wait) to avoid locking your terminal
 veogent batch-request --type GENERATE_IMAGES \
-  --project <projectId> --chapter <chapterId> --all \
-  --orientation VERTICAL --wait
+  --project <projectId> --chapter <chapterId> --all --orientation VERTICAL
 
-# Generate all videos
-veogent batch-request --type GENERATE_VIDEO \
-  --project <projectId> --chapter <chapterId> --all \
-  --orientation VERTICAL --wait
+# 2. Extract `requestId` from the output
+# 3. Poll status asynchronously:
+veogent request-status --id <requestId>
+# ... loop until requestStatus === "COMPLETED"
+
+# Repeat for GENERATE_VIDEO once images are ready
 ```
 
+> **Tip for Agents:** While the `--wait` flag exists, using `request-status` is recommended so you don't lock your main process for the 5-10 minutes it takes to render a video.
+
 #### Phase 4: QA + Fix Loop
 
 ```bash
@@ -187,13 +190,15 @@ veogent request --type GENERATE_VIDEO \
 
 | Command | Description |
 |---------|-------------|
-| `request` | Create a single generation job (`GENERATE_IMAGES` / `GENERATE_VIDEO`) |
+| `request` | Create a single generation job (`GENERATE_IMAGES` / `GENERATE_VIDEO` / `UPSCALE_VIDEO`) |
 | `batch-request` | Batch generation for multiple/all scenes (`--all`) |
 | `requests` | List existing generation jobs |
+| `request-status` | Check a specific job by request ID (includes asset URL) |
 | `failed-requests` | List failed requests for a chapter |
 | `wait-images` | Poll until all image jobs finish |
 | `wait-videos` | Poll until all video jobs finish |
 | `queue-status` | Current queue/concurrency status |
+| `download-upscale` | Download 4K upscaled video as `.mp4` (decodes base64 from flow-media) |
 
 ### Monitoring
 
@@ -201,6 +206,7 @@ veogent request --type GENERATE_VIDEO \
 |---------|-------------|
 | `scene-status` | Scene-level image+video status with asset URLs |
 | `workflow-status` | Full snapshot: scenes + requests + assets (best for agents) |
+| `request-status` | Check a specific job by request ID |
 
 ### YouTube
 
@@ -245,6 +251,27 @@ Uses sceneA's image as start frame, sceneB's image as end frame. Both scenes mus
 
 ---
 
+## Video Upscale (4K)
+
+```bash
+# 1. Trigger upscale
+veogent request --type UPSCALE_VIDEO \
+  --project X --chapter Y --scene Z \
+  --orientation VERTICAL --resolution VIDEO_RESOLUTION_4K
+
+# 2. Poll status by request ID
+veogent request-status --id <requestId>
+
+# 3. Download the upscaled video
+veogent download-upscale \
+  --project X --chapter Y --scene Z \
+  --orientation VERTICAL --out ./scene_4k.mp4
+```
+
+> `download-upscale` calls `/app/scene/flow-media`, decodes the base64 `encodedVideo`, and writes a `.mp4` file.
+
+---
+
 ## Concurrency
 
 Maximum **5** concurrent requests. If queue is full (E10071), CLI auto-retries once after 30s.

package/index.js

@@ -747,8 +747,8 @@ program
 // --- Execution Request (Generate Image / Video) ---
 program
     .command('request')
-    .description('Create a job request (GENERATE_IMAGES, GENERATE_VIDEO)')
-    .requiredOption('--type <type>', 'Request type (e.g., GENERATE_IMAGES, GENERATE_VIDEO)')
+    .description('Create a job request (GENERATE_IMAGES, GENERATE_VIDEO, UPSCALE_VIDEO). Use UPSCALE_VIDEO to upscale a rendered video to 4K resolution.')
+    .requiredOption('--type <type>', 'Request type (e.g., GENERATE_IMAGES, GENERATE_VIDEO, UPSCALE_VIDEO)')
     .requiredOption('--project <project>', 'Project ID')
     .requiredOption('--chapter <chapter>', 'Chapter ID')
     .requiredOption('--scene <scene>', 'Scene ID')
@@ -757,6 +757,7 @@ program
     .option('--videomodel <videomodel>', 'Video Model (veo_3_1_fast, veo_3_1_fast_r2v). Default: veo_3_1_fast', 'veo_3_1_fast')
     .option('--speed <speed>', 'Video Speed (normal, timelapse, slowmotion)', 'normal')
     .option('--endscene <endscene>', 'End Scene ID for continuous video generation')
+    .option('--resolution <resolution>', 'Resolution for UPSCALE_VIDEO (e.g. VIDEO_RESOLUTION_4K)', 'VIDEO_RESOLUTION_4K')
     .option('--wait', 'Wait for request to complete before returning')
     .action(async (options) => {
         try {
@@ -804,8 +805,9 @@ program
                 payload.orientation = options.orientation || 'HORIZONTAL';
                 payload.imageModel = options.imagemodel;
             }
-            if (['VIDEO_UPSCALE'].includes(options.type)) {
-                payload.orientation = options.orientation || 'HORIZONTAL'; // Provide fallback
+            if (['UPSCALE_VIDEO'].includes(options.type)) {
+                payload.orientation = options.orientation || 'VERTICAL'; // Upscale defaults to VERTICAL
+                payload.resolution = options.resolution || 'VIDEO_RESOLUTION_4K';
             }
 
             const data = await api.post('/app/request', payload);
@@ -1057,35 +1059,64 @@ program
 
 program
     .command('request-status')
-    .description('Get status of a specific request by ID')
+    .description('Get status of a specific request by ID. For GENERATE_VIDEO/GENERATE_IMAGES, falls back to assets endpoint for output URL. UPSCALE_VIDEO output URL is read directly from the request object.')
     .requiredOption('--id <requestId>', 'Request ID to check')
     .action(async (options) => {
         try {
-            const data = await api.get('/app/requests');
-            let items = unwrapData(data);
-            items = Array.isArray(items) ? items : (items?.items || []);
+            const data = await api.get(`/app/standalone/request/${options.id}`);
+            const found = unwrapData(data);
 
-            const found = items.find((r) => r?.id === options.id || r?.requestId === options.id);
             if (!found) {
                 emitJson({ status: 'error', code: 'REQUEST_NOT_FOUND', message: `No request found with ID: ${options.id}` });
                 return;
             }
 
-            const status = String(found?.status || '').toUpperCase();
+            const requestStatus = String(found?.status || '').toUpperCase();
+            const type = found?.type || null;
+            const projectId = found?.projectId || found?.project_id || null;
+            const chapterId = found?.chapterId || found?.chapter_id || null;
+            const sceneId = found?.sceneId || found?.scene_id || null;
+
+            let imageAsset = { url: found?.imageVerticalUri || found?.imageHorizontalUri || found?.imageUrl || null };
+            // UPSCALE_VIDEO: output URL lives directly on the request object (not in assets endpoint)
+            let videoAsset = { url: found?.videoVerticalUri || found?.videoHorizontalUri || found?.videoUrl || found?.outputUrl || null };
+
+            // For GENERATE_VIDEO only: fallback to assets endpoint if URL not on request object
+            if (type === 'GENERATE_VIDEO' && projectId && chapterId && sceneId && !videoAsset.url) {
+                try {
+                    const assetData = unwrapData(await api.get(`/app/request/assets/${projectId}/${chapterId}/${sceneId}?type=GENERATE_VIDEO`));
+                    const assetItems = Array.isArray(assetData) ? assetData : (assetData?.items || []);
+                    const matched = assetItems.find((a) => a?.id === options.id || a?.requestId === options.id)
+                        || assetItems.find((a) => String(a?.status || '').toUpperCase() === 'COMPLETED');
+                    if (matched) {
+                        videoAsset = { url: matched?.videoVerticalUri || matched?.videoHorizontalUri || matched?.videoUrl || matched?.outputUrl || null };
+                    }
+                } catch { /* asset fetch optional */ }
+            }
+
+            // For image type: fetch asset URL if not present
+            if (type === 'GENERATE_IMAGES' && projectId && chapterId && sceneId && !imageAsset.url) {
+                try {
+                    const assetData = unwrapData(await api.get(`/app/request/assets/${projectId}/${chapterId}/${sceneId}?type=GENERATE_IMAGES`));
+                    const assetItems = Array.isArray(assetData) ? assetData : (assetData?.items || []);
+                    const matched = assetItems.find((a) => a?.id === options.id || a?.requestId === options.id)
+                        || assetItems.find((a) => String(a?.status || '').toUpperCase() === 'COMPLETED');
+                    if (matched) {
+                        imageAsset = { url: matched?.imageVerticalUri || matched?.imageHorizontalUri || matched?.imageUrl || matched?.outputUrl || null };
+                    }
+                } catch { /* asset fetch optional */ }
+            }
+
             const result = {
                 status: 'success',
                 requestId: found?.id || found?.requestId,
-                type: found?.type || null,
-                requestStatus: status,
-                sceneId: found?.sceneId || found?.scene_id || null,
-                chapterId: found?.chapterId || found?.chapter_id || null,
-                projectId: found?.projectId || found?.project_id || null,
-                image: {
-                    url: found?.imageVerticalUri || found?.imageHorizontalUri || found?.imageUrl || found?.outputUrl || null,
-                },
-                video: {
-                    url: found?.videoVerticalUri || found?.videoHorizontalUri || found?.videoUrl || found?.outputUrl || null,
-                },
+                type,
+                requestStatus,
+                sceneId,
+                chapterId,
+                projectId,
+                image: imageAsset,
+                video: videoAsset,
                 createdAt: found?.createdAt || found?.created_at || null,
                 completedAt: found?.completedAt || found?.updatedAt || null,
                 raw: found,
@@ -1109,6 +1140,41 @@ program
         }
     });
 
+program
+    .command('download-upscale')
+    .description('Download the 4K upscaled video for a scene. Calls /app/scene/flow-media to retrieve the base64-encoded video and saves it as an .mp4 file.')
+    .requiredOption('--project <project>', 'Project ID')
+    .requiredOption('--chapter <chapter>', 'Chapter ID')
+    .requiredOption('--scene <scene>', 'Scene ID')
+    .option('--orientation <orientation>', 'Orientation to download (VERTICAL, HORIZONTAL)', 'VERTICAL')
+    .option('--out <path>', 'Output file path (default: ./<sceneId>_upscale.mp4)')
+    .action(async (options) => {
+        try {
+            const orientation = options.orientation.toLowerCase(); // Backend expects lowercase (e.g. 'vertical')
+            humanLog(`⏳ Fetching upscaled video from flow-media...`);
+
+            const data = await api.get(`/app/scene/flow-media/${options.project}/${options.chapter}/${options.scene}/${orientation}`);
+            const raw = unwrapData(data);
+
+            // Backend returns { video: { encodedVideo, ... } } or flat { encodedVideo }
+            const encodedVideo = raw?.video?.encodedVideo || raw?.encodedVideo || null;
+
+            if (!encodedVideo) {
+                emitJson({ status: 'error', code: 'NO_VIDEO_DATA', message: 'No encodedVideo in response. The upscale may not be ready yet.', raw });
+                return;
+            }
+
+            const outPath = options.out || `./${options.scene}_upscale.mp4`;
+            const { writeFileSync } = await import('fs');
+            writeFileSync(outPath, Buffer.from(encodedVideo, 'base64'));
+
+            humanLog(`✅ Saved upscaled video to: ${outPath}`);
+            emitJson({ status: 'success', file: outPath, sceneId: options.scene, orientation });
+        } catch (error) {
+            emitJson({ status: 'error', ...formatCliError(error) });
+        }
+    });
+
 program
     .command('failed-requests')
     .description('List failed requests for a project/chapter (agent helper)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veogent",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "The official CLI to interact with the VEOGENT API - AI Video and Image generation platform",
   "main": "index.js",
   "bin": {

package/skills/SKILL.md

@@ -57,15 +57,20 @@ veogent characters <projectId>   # poll until allReady === true
 
 NEVER skip `create-chapter-content` — always let VEOGENT AI generate the storyboard.
 
-### Phase 3: Generate Images + Videos
+### Phase 3: Generate Images + Videos (Async)
 
 ```bash
-veogent batch-request --type GENERATE_IMAGES \
-  --project X --chapter Y --all --orientation VERTICAL --wait
-veogent batch-request --type GENERATE_VIDEO \
-  --project X --chapter Y --all --orientation VERTICAL --wait
+# 1. Trigger batch generation (without --wait)
+veogent batch-request --type GENERATE_IMAGES --project X --chapter Y --all --orientation VERTICAL
+
+# 2. Extract the request IDs from the output
+# 3. Poll their status asynchronously without blocking your main process
+veogent request-status --id <requestId>
+# ... loop until requestStatus === "COMPLETED"
 ```
 
+*Note: You CAN use the `--wait` flag to make the CLI block until finished, but using `request-status` is better for true asynchronous agent pipelines so you don't lock your process.*
+
 ### Phase 4: QA + Fix Loop
 
 ```bash
@@ -196,6 +201,25 @@ veogent request --type GENERATE_VIDEO --project X --chapter Y --scene sceneA \
 ```
 Uses sceneA image → sceneB image as start/end frames. Both must have successful images. Only `veo_3_1_fast`.
 
+### Video Upscale (4K)
+
+```bash
+# 1. Trigger upscale
+veogent request --type UPSCALE_VIDEO \
+  --project X --chapter Y --scene Z \
+  --orientation VERTICAL --resolution VIDEO_RESOLUTION_4K
+
+# 2. Poll until COMPLETED
+veogent request-status --id <requestId>
+
+# 3. Download the upscaled .mp4 (reads from flow-media, decodes base64)
+veogent download-upscale \
+  --project X --chapter Y --scene Z \
+  --orientation VERTICAL --out ./scene_4k.mp4
+```
+
+> `download-upscale` calls `GET /app/scene/flow-media/{project}/{chapter}/{scene}/{orientation}`, decodes the base64 `encodedVideo` response, and saves it as an `.mp4` file.
+
 ---
 
 ## Monitoring & Status
@@ -205,6 +229,7 @@ Uses sceneA image → sceneB image as start/end frames. Both must have successfu
 | `workflow-status --project X --chapter Y` | Full snapshot: scenes + requests + assets (best for agents) |
 | `scene-status --project X --chapter Y` | Quick image/video status per scene |
 | `requests --project X --limit 10` | Check recent generation jobs |
+| `request-status --id <requestId>` | Check a specific job by request ID (with asset URL) |
 | `failed-requests --project X --chapter Y` | Debug why gen failed |
 | `wait-images --project X --chapter Y --require-success` | Block until all images done |
 | `wait-videos --project X --chapter Y --require-success` | Block until all videos done |
@@ -217,7 +242,7 @@ Uses sceneA image → sceneB image as start/end frames. Both must have successfu
 
 1. Verify auth before any command (`veogent status`).
 2. Wait for character readiness (`allReady`) before requesting images.
-3. Use `--wait` flag on `request`/`batch-request`/`edit-scene` to block until completion.
+3. **Polling vs Blocking:** For true asynchronous workflows, trigger jobs *without* `--wait`, capture the `requestId`, and poll `request-status --id <requestId>`. Only use `--wait` if you are okay with the CLI locking the process for 5-10 minutes.
 4. Use `workflow-status` as the main status view.
 5. Respect queue limits (max 5 concurrent). `queue-status` to check.
 6. **QA image BEFORE video** — bad image = bad video. Each video gen costs 8-10 min.
@@ -359,8 +384,9 @@ veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z \
 
 | Command | Description | Key Options |
 |---------|-------------|-------------|
-| `request` | Single generation job | `--type`, `--project`, `--chapter`, `--scene`, `--orientation`, `--speed`, `--endscene`, `--wait` |
+| `request` | Single generation job | `--type` (GENERATE_IMAGES, GENERATE_VIDEO, UPSCALE_VIDEO), `--project`, `--chapter`, `--scene`, `--orientation`, `--speed`, `--endscene`, `--resolution` (upscale), `--wait` |
 | `batch-request` | Batch generation | `--type`, `--project`, `--chapter`, `--all`/`--scenes`, `--orientation`, `--speed`, `--wait` |
+| `download-upscale` | Download 4K upscaled video as .mp4 | `--project`, `--chapter`, `--scene`, `--orientation`, `--out` |
 
 ### Monitoring Commands
 
@@ -369,6 +395,7 @@ veogent request --type GENERATE_VIDEO --project X --chapter Y --scene Z \
 | `workflow-status` | Full snapshot (best for agents) | `--project`, `--chapter` |
 | `scene-status` | Per-scene image/video status | `--project`, `--chapter` |
 | `requests` | List generation jobs | `--project`, `--chapter`, `--status`, `--limit` |
+| `request-status` | Check a specific job by ID (with asset URL) | `--id` |
 | `failed-requests` | Failed jobs only | `--project`, `--chapter` |
 | `wait-images` | Poll until images done | `--project`, `--chapter`, `--require-success` |
 | `wait-videos` | Poll until videos done | `--project`, `--chapter`, `--require-success` |