hermes-skills/ltx-video-pipeline/references/api-submission-pattern.md

# ComfyUI API Submission & TrueNAS Upload Pattern

## Problem
Submitting complex workflow JSONs via shell heredocs often fails due to quote escaping issues. Additionally, smbclient is NOT installed on the ComfyUI LXC (10.0.0.202), so TrueNAS uploads must be done from the Hermes host.

## Solution: File-Based API Submission

### Step 1: Write Workflow to File
```bash
cat > /tmp/submit_ltx_render.sh << 'EOF'
#!/bin/bash
curl -s -X POST http://10.0.0.202:8188/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": {
      "35": {"class_type": "UNETLoader", "inputs": {"unet_name": "ltx-2.3-22b-distilled_transformer_only_fp8_scaled.safetensors", "weight_dtype": "default"}},
      "131": {"class_type": "LTXDirector", "inputs": {
        "model": ["200", 0],
        "clip": ["12", 0],
        "audio_vae": ["8", 0],
        "start_second": 0,
        "end_second": 5.0,
        "duration_seconds": 5.0,
        "start_frame": 0,
        "end_frame": 120,
        "duration_frames": 120,
        "timeline_data": "{\"mainTrackEnabled\": true, \"audioTrackEnabled\": false, \"motionTrackEnabled\": false, \"global_prompt\": \"<PROMPT>\", \"segments\": [{\"type\": \"image\", \"start\": 0.0, \"length\": 120, \"prompt\": \"<DETAILED_PROMPT>\", \"imageFile\": \"<START_FRAME>\", \"guide_strength\": 1.0, \"audioFile\": \"\", \"end\": 5.0}]}",
        "guide_strength": 1.0
      }},
      "200": {"class_type": "LTX2LoraLoaderAdvanced", "inputs": {"lora_name": "ltx-2.3-22b-distilled-lora-1.1_fro90_ceil72_condsafe.safetensors", "model": ["35", 0], "strength_model": 1.0, "video": 1.0, "video_to_audio": 0.0, "audio": 0.0, "audio_to_video": 0.0, "other": 0.0}}
      // ... rest of workflow nodes
    }
  }'
EOF
chmod +x /tmp/submit_ltx_render.sh
```

### Step 2: Submit and Capture Prompt ID
```bash
RESULT=$(bash /tmp/submit_ltx_render.sh)
PROMPT_ID=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['prompt_id'])")
echo "Submitted: $PROMPT_ID"
```

### Step 3: Poll for Completion
```bash
while true; do
  STATUS=$(curl -s "http://10.0.0.202:8188/history/$PROMPT_ID")
  echo "$STATUS" | grep -q '"status_str":"success"' && echo "COMPLETE" && break
  echo "$STATUS" | grep -q '"status_str":"error"' && echo "ERROR" && echo "$STATUS" && break
  echo "Running..."
  sleep 10
done
```

### Step 4: Verify Output
```bash
# Check duration
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 ~/comfy-ui/output/<filename>.mp4

# Check frames
ffprobe -v error -select_streams v:0 -show_entries stream=nb_frames -of default=noprint_wrappers=1:nokey=1 ~/comfy-ui/output/<filename>.mp4

# Check resolution
ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of default=noprint_wrappers=1:nokey=1 ~/comfy-ui/output/<filename>.mp4
```

## TrueNAS Upload (From Hermes Host)

### Prerequisites
- smbclient is NOT on .202 (LXC)
- Copy files to Hermes host first (10.0.0.42)
- Upload from Hermes host using smbclient

### Upload Command
```bash
# Copy from LXC to Hermes host
sshpass -p 'passw0rd' scp [email protected]:~/comfy-ui/output/<filename>.mp4 ~/comfy-ui/output/

# Upload to TrueNAS
smbclient //10.0.0.117/proxmoxBackup -U n8n -c "cd ai_vid_stock_material\\\\outputs; put <local_filename>.mp4"
```

### Alternative: Mount and Copy
```bash
# Mount TrueNAS share (if cifs kernel module available)
sudo mount -t cifs //10.0.0.117/proxmoxBackup/ai_vid_stock_material/outputs /mnt/truenas_outputs -o user=n8n,vers=3.0

# Copy file
cp <local_filename>.mp4 /mnt/truenas_outputs/

# Unmount
sudo umount /mnt/truenas_outputs
```

## Verification Checklist
- [ ] Prompt ID captured from API response
- [ ] Queue status shows `queue_running: []` and `queue_pending: []`
- [ ] History shows `"status_str":"success"`
- [ ] ffprobe confirms expected duration (5s = 121 frames at 24fps, 10s = 241 frames)
- [ ] ffprobe confirms resolution (768×512 for 6-fix baseline)
- [ ] File uploaded to TrueNAS at `//10.0.0.117/proxmoxBackup/ai_vid_stock_material/outputs/`
- [ ] Filename follows naming convention: `LTX_YYYY-MM-DD_<what>_<sampler>_<duration>.mp4`

## Common Errors

### "no_prompt" Error
- **Cause:** Submitted bare workflow JSON instead of `{\"prompt\": <workflow>}` envelope
- **Fix:** Wrap workflow in `{"prompt": ...}` before sending to `/prompt` endpoint

### "tree connect failed: NT_STATUS_BAD_NETWORK_NAME"
- **Cause:** Wrong SMB path or missing credentials
- **Fix:** Use `//10.0.0.117/proxmoxBackup` (not the full path), then `cd` into subdirectory

### Quote Escaping Failures
- **Cause:** Inline JSON with quotes breaks shell parsing
- **Fix:** Write JSON to file first, then read with `-d @/path/to/file.json`

### VRAM Stuck at Idle
- **Cause:** Job never started (error during parsing)
- **Fix:** Check `curl -s http://localhost:8188/queue` for empty `queue_running`, then check `curl -s http://localhost:8188/history/<prompt_id>` for error messages

## Related Files
- `/tmp/submit_ltx_render.sh` — Example submission script
- `~/comfy-ui/output/` — ComfyUI output directory on .202
- `//10.0.0.117/proxmoxBackup/ai_vid_stock_material/outputs/` — TrueNAS destination