---
name: video-story-hermes-automation
description: Run the Video Story app end-to-end from Hermes via the local automation API, monitor YOLO progress, and deliver the final video back to the user.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [video-story, automation, telegram, yolo, api]
---

# Video Story Hermes Automation

Use when a user wants Hermes to create and run a Video Story project directly, especially from Telegram.

## Preconditions
- App repo: `/home/avalon/apps/video-story`
- Server runs locally on port `4015`
- Automation auth uses header `x-hermes-token`
- Token fallback is `VIDEO_STORY_HERMES_TOKEN` or `VIDEO_STORY_PIN` or app PIN `3693`

## Create and run a project

POST `/api/hermes/projects/create-and-run`

Example:
```bash
curl -s http://127.0.0.1:4015/api/hermes/projects/create-and-run \
  -H 'Content-Type: application/json' \
  -H 'x-hermes-token: 3693' \
  -d '{
    "prompt": "A mythic fantasy about...",
    "duration_target": 120,
    "style": "cinematic",
    "aspect_ratio": "9:16",
    "reference_image_model": "qwen",
    "frame_image_model": "qwen",
    "auto_yolo": true
  }'
```

## Poll status

GET `/api/hermes/projects/:id/status`

The response includes:
- `project.status`
- `project.yolo_step`
- `yolo.recentLogs`
- `export.exists`
- `export.video_url`
- `export.download_url`

## Get final export

GET `/api/hermes/projects/:id/export`

## Telegram workflow
1. Create project via automation endpoint.
2. Poll `/status` every 20-30s until either:
   - `export.exists=true`, or
   - the project reaches a terminal failure state.
3. Summarize latest `recentLogs` to the user while waiting.
4. When `export.exists=true`, call `/api/hermes/projects/:id/export`.
5. Prefer sending the returned `local_path` back to Telegram as native media.
6. Do NOT stop after reporting completion status — the workflow is not complete until the video has actually been delivered back to the chat.

## Recommended defaults
- `aspect_ratio`: `16:9` unless user asks vertical
- `reference_image_model`: `qwen`
- `frame_image_model`: `qwen`

## Important delivery lesson
A completed Video Story project is not the same as a completed Hermes task.
If the user asked Hermes to make a story in Telegram, Hermes must:
- wait for export completion,
- fetch the export metadata,
- send the finished video back into Telegram,
- and only then consider the request done.

## Portrait video / Telegram display lesson
Telegram can display 9:16 correctly, but portrait exports may appear squeezed if the MP4 lacks explicit display metadata.
For portrait-safe delivery, final exports should explicitly encode:
- `sample_aspect_ratio = 1:1`
- `display_aspect_ratio = 9:16`

In ffmpeg terms, harden portrait exports with:
- `setsar=1`
- `setdar=9/16`

And landscape exports with:
- `setsar=1`
- `setdar=16/9`

Also keep the final delivery format Telegram-friendly:
- H.264 video
- yuv420p pixel format
- AAC audio
- `-movflags +faststart`
- fixed dimensions such as `720x1280` for portrait or `1280x720` for landscape

## Notes
- Qwen is the safest default for both references and frames.
- The API is intended for Hermes/local automation on the VPS.
- Auth currently uses `x-hermes-token` and falls back to `VIDEO_STORY_HERMES_TOKEN`, `VIDEO_STORY_PIN`, or app PIN `3693` if no dedicated token is set.
- If the app is redeployed, verify endpoints with curl before using in production.