videoinu-skill

Videoinu platform skill — manage projects via Graphs (canvases), upload/download files, chat with AI Agents, and run Workflows.

Important: How to Use

You MUST use the Python scripts provided by this skill to interact with Videoinu. Do NOT use mcporter, MCP, curl, or any other method to call the API directly.

All scripts are located in the scripts/ directory of this skill. Tokens are stored in ~/.videoinu/credentials.json and scripts read them automatically.

Example: to list projects, run python3 <skill_scripts_dir>/list_graphs.py — do not construct HTTP requests manually.

Overview

videoinu-skill provides a set of Python scripts for interacting with the Videoinu platform. It covers the following core capabilities:

1. Graph Management — Create, list, and view Graphs (project canvases) along with their ViewNodes / CoreNodes
2. File Upload/Download — Upload local files to the platform (creating CoreNodes) or download files from a Graph
3. Agent Chat — Create Agent sessions and chat with AI Agents via WebSocket
4. Workflow Execution — Run Workflow definitions and query execution status

Requirements

• Binary: python3 (3.9+)
• Environment variable: VIDEOINU_ACCESS_KEY (required)
• Optional environment variable: VIDEOINU_API_BASE (defaults to https://videoinu.com)
• No third-party dependencies: all scripts use only the Python standard library

Authentication

All requests use Cookie-based authentication: Cookie: token=<VIDEOINU_ACCESS_KEY>

Obtaining and Saving the Access Key

How to obtain your Access Key:

1. Log in at https://videoinu.com
2. Go to Profile page → click Copy Access Key

Saving the Access Key (choose one):

Option A: Save locally with auth.py (recommended)

python3 auth.py save "your-access-key"
# Token saved to ~/.videoinu/credentials.json (owner read/write only)
# All scripts will auto-read it — no environment variable needed

Option B: Environment variable

export VIDEOINU_ACCESS_KEY="your-access-key"

Token resolution priority: environment variable > ~/.videoinu/credentials.json

Verify and manage:

python3 auth.py status   # Show current auth status
python3 auth.py verify   # Verify token validity
python3 auth.py logout   # Remove saved token

If the user is not yet logged in, direct them to https://videoinu.com/login to sign up / log in and obtain their key.

Security warning: Never hardcode the Access Key into script files. The Access Key is a JWT token containing user identity information — leaking it could lead to account compromise. Use auth.py save or environment variables.

Script Reference

Core Concepts

Graph (Canvas / Project)

A Graph is Videoinu's project container. It contains:

• ViewNode: A visual node on the canvas with position, labels, and connections
• CoreNode: An underlying data node representing an actual asset (image, video, audio, text) or operation (Workflow output)
• Connection: A link between ViewNodes representing data flow
• Group: A grouping of ViewNodes

Each ViewNode can reference one or more CoreNodes (core_refs), with selected_core_id indicating the currently selected version.

CoreNode Types

• asset: Asset node
  • asset_type: image | video | audio | text | json | file
  • source_type: upload | import | generated
  • Has url (media file) or content (text content)
• operation: Operation node (Workflow execution output)
  • status: pending | completed | failed

Agent Sessions

An Agent is an AI assistant bound to a Graph. It communicates via WebSocket in real time.

• One Graph maps to one Agent Project
• One Project can have multiple Sessions
• Agents can invoke Tools to operate on nodes within the Graph

Workflow

A predefined automation pipeline that accepts inputs (CoreNode references) and produces new CoreNodes.

Typical Workflows

Scenario 1: Browse User Projects

# 1. List all Graphs
python3 list_graphs.py

# 2. View details of a specific Graph
python3 get_graph.py GRAPH_ID

Scenario 2: Create a New Project and Upload Files

# 1. Create a new Graph (auto-tagged with free-mode so it appears in the UI)
python3 create_graph.py "My New Project"
# → returns graph_id

# 2. Upload a reference file
python3 upload_file.py /path/to/reference.png
# → returns core_node_id, file_url

# 3. Verify the Graph
python3 get_graph.py GRAPH_ID

Scenario 3: Chat with an Agent

# 1. Create a session
python3 create_session.py GRAPH_ID
# → returns session_id

# 2. Send a message
python3 agent_chat.py SESSION_ID "Analyze the structure of this project"

# 3. Send a message with a file reference
python3 agent_chat.py SESSION_ID "Check this image {{@core_node:CORE_NODE_ID:image.png}}"

# 4. List existing sessions
python3 create_session.py GRAPH_ID --list

Scenario 4: Upload a File and Have the Agent Process It

# 1. Upload the file
python3 upload_file.py /path/to/video.mp4
# → core_node_id = "abc123"

# 2. Create a session (if you don't have one yet)
python3 create_session.py GRAPH_ID
# → session_id = "sess456"

# 3. Ask the Agent to process the file
python3 agent_chat.py sess456 "Please edit this video {{@core_node:abc123:video.mp4}}" --auto-approve

Scenario 5: Run a Workflow

# 1. List available Workflow definitions
python3 run_workflow.py --list

# 2. Run within an existing Graph
python3 run_workflow.py DEF_ID --graph-id GRAPH_ID \
  --inputs '{"input_image": {"type": "core_node_refs", "core_node_ids": ["NODE_ID"]}}'
# → returns instance_id

# 3. Poll execution status until complete
python3 query_workflow.py INSTANCE_ID --poll

Scenario 6: Download Generated Results from a Graph

# Download all images from the Graph
python3 download_file.py GRAPH_ID --type image --output-dir ./results

# Download all videos
python3 download_file.py GRAPH_ID --type video

# Download specific URLs directly
python3 download_file.py --urls "https://..." "https://..." --output-dir ./output

Agent Reference Format

You can reference nodes in a Graph within messages sent to the Agent:

{{@core_node:CORE_NODE_ID:display_name}}
{{@view_node:VIEW_NODE_ID:display_name}}

Example:

Please analyze this image {{@core_node:a1b2c3d4:sunset.png}}

The Agent will fetch the corresponding CoreNode content based on the reference.

Output Format

All scripts output JSON to stdout and errors to stderr.

Success:

{
  "graphs": [...],
  "has_more": false
}

Error:

{
  "error": "VIDEOINU_ACCESS_KEY is not set. Run: export VIDEOINU_ACCESS_KEY=\"your-access-key\""
}

Core Principles

1. Faithfully convey user intent: Pass the user's request to the Agent as-is — do not embellish, translate, or rewrite the prompt
2. Look before you leap: Use get_graph.py to understand the current state of a Graph before performing operations
3. Reference, don't describe: When referring to existing files, use {{@core_node:ID:name}} references instead of text descriptions
4. Upload first: If the user provides a local file, upload it with upload_file.py first, then reference it in messages
5. Poll responsibly: Both Workflow and Agent responses have timeout limits — do not poll indefinitely

API Endpoint Reference

All HTTP endpoints are based on VIDEOINU_API_BASE (defaults to https://videoinu.com).

Go Backend (/api/backend/)

Agent Service (/api/agent/)

WebSocket Message Format (JSON-RPC 2.0)

Send prompt:

{"jsonrpc": "2.0", "method": "prompt", "id": "uuid", "params": {"user_input": "message"}}

Heartbeat:

{"jsonrpc": "2.0", "method": "heartbeat", "id": "hb-uuid", "params": {"heartbeat_id": "uuid"}}

Approve tool call:

{"jsonrpc": "2.0", "id": "rpc-id-from-request", "result": {"request_id": "req-id", "response": "approve"}}

Received event types: TurnBegin, ContentPart, ToolCall, ToolCallPart, ToolResult, ApprovalRequest, StatusUpdate, SessionNotice, ReplayComplete