openrouter-video-generator

OpenRouter Video Generator

Create a short browser-playable video asset for AwesomeWebpageMetaSkill.

This is an adapter around the configured OpenRouter video model, not a place to

choose providers or invent model ids.

Meta-Skill Entrypoint

Meta-skills should run this skill as skill_exec. The entrypoint is a

deterministic Python adapter around OpenRouter's async video endpoint. During a

MetaSkill run it receives a short-lived connection from ordinary Provider

Settings in the child process only; the credential, endpoint, and proxy never

enter with, argv, the plan, or persisted run data. It writes the MP4 under

the supplied output directory and prints either VIDEO_READY: or a failure

label. Do not spawn an LLM sub-agent just to generate video.

Contract

• Use the code-owned OpenRouter capability candidate and the volatile provider

lease resolved from ordinary Provider Settings after explicit approval.

• Use only awesome_webpage.openrouter.models.video_generation as the model.
• Use only awesome_webpage.output_dir as the output root.
• Save generated files under project/assets/video/.
• Return a media manifest with local path, MIME type, duration if known,

provenance, and replacement notes.

OpenRouter Video API Contract (hard rule)

OpenRouter video models are exposed through an async job endpoint, not

the chat-completions endpoint. Hitting /chat/completions with a video

model id returns HTTP 500 and burns the full per-attempt budget. Do not

attempt it.

• Submit: POST {base_url}/videos with JSON body

{"model": "<video_generation>", "prompt": "<text>", "duration": <int>}.

Optional fields: resolution, aspect_ratio, frame_images,

input_references, provider, callback_url. Do NOT send messages or

modalities — those are chat-only and will be rejected.

• Response (immediate): `{"id": "...", "polling_url": "...",

"status": "pending"}`.

• Poll: GET the polling_url with the same Authorization: Bearer ...

header every 8-15 seconds until status becomes one of

completed | failed | cancelled | expired. Cap the loop at ~5 minutes per

clip; treat anything beyond that as VIDEO_GENERATION_FAILED.

• Download (only on completed): take the first URL from

unsigned_urls, GET it with the same bearer token, and save the body to

<output_dir>/project/assets/video/<slug>.mp4. Set MIME to video/mp4.

• Terminal-failure statuses map to VIDEO_GENERATION_FAILED; include

the job id and a replacement-slot path so the page can render a clean

placeholder.

Typical successful job completes in 60-120 s for short clips; do not abort

before that window.

Failure Labels

Return one of these labels instead of silently skipping video:

• VIDEO_CONFIG_NEEDED: model, API key, base URL, or output directory is

missing.

• VIDEO_MODEL_UNSUPPORTED: the configured model cannot return a local

browser-playable asset in this environment.

• VIDEO_GENERATION_FAILED: the provider call failed after a concrete attempt.

A missing/invalid required MetaSkill lease emits VIDEO_CONFIG_NEEDED and exits

78 before submit. Failures after a concrete submit stay an exit-0 degradation

so downstream packaging can bind a replacement slot without automatic replay.

When returning a failure label, also return a replacement slot such as

project/assets/video/replace-with-topic-intro.mp4 and enough prompt/context

for a later repair pass.

Output Requirements

• Prefer .mp4 with video/mp4; .webm is acceptable when browser playable.
• Keep clips short, usually 8-20 seconds.
• Do not use remote embeds unless config explicitly allows them.
• Do not hardcode OpenRouter model names, API keys, or output directories.

On success: VIDEO_READY manifest line (required)

After every successful download, end your reply with one single-line JSON

record per file so AwesomeWebpageMetaSkill can collect and bind the asset:

VIDEO_READY: {"local_path": "project/assets/video/<slug>.mp4", "mime": "video/mp4", "duration_s": <int_or_null>, "resolution": "<WxH_or_null>", "prompt_preview": "<first 80 chars>"}

• One VIDEO_READY: line per video file. No trailing prose on that line.
• local_path MUST be the relative path project/assets/video/.... Do NOT

emit an absolute path here.

• On failure, emit one of VIDEO_CONFIG_NEEDED, VIDEO_MODEL_UNSUPPORTED, or

VIDEO_GENERATION_FAILED as a single-line label with the replacement-slot

path so the page can render a placeholder.