Skip to main content
ralphy models exposes the live OpenRouter video-generation catalog with per-model constraints — supported durations, resolutions, aspect ratios, frame-anchor support, price tiers. Surfacing those before submit means the agent (and the human) doesn’t burn $0.70 and 2 minutes on a request the provider was going to reject. Per AGENTS.md invariant #6, agents read MODELS.md before every model call — this verb is the machine-readable mirror.

​
ralphy models list

Lists every OR video-generation model with per-model whitelist data and a 5-second price estimate. 
ralphy models list
ralphy models list --refresh    # bust the 24h cache
The pretty form is a sortable table; the JSON form is { fetchedAt, count, models: [...] }. 
ralphy models list --json | jq '.models[] | select(.frames | contains("last_frame"))'
# → every model that supports first/last frame i2v
Full surface: /reference/cli/models.

​
ralphy models show <id>

Full schema for one model — description, supported params, price at 1s / 5s / 10s. 
ralphy models show kwaivgi/kling-v3.0-pro
ralphy models show bytedance/seedance-2.0 --refresh
Sample shape: 
{
  "id": "kwaivgi/kling-v3.0-pro",
  "name": "Kling v3.0 Pro",
  "description": "Kuaishou's premium video model.",
  "supported_durations": [5, 10],
  "supported_resolutions": ["720p"],
  "supported_aspect_ratios": ["9:16", "16:9", "1:1"],
  "supported_frame_images": ["first_frame"],
  "supported_input_references": ["url", "data_uri"],
  "priceUsdPerSec": 0.14,
  "priceUsd5s": 0.7,
  "priceUsd10s": 1.4
}
Full surface: /reference/cli/models.

​
ralphy models alias

Resolve a shorthand (kling, nano banana pro, gpt image 2, …) to its canonical OpenRouter slug. Useful when the user says “use Kling” and you need the exact id for --model. 
ralphy models alias kling
# → { shorthand, canonical, matched, siblings }

ralphy models alias              # no arg → dump the full alias map
Full surface: /reference/cli/models.

​
When to run these by hand

  • Cost comparison before a batch: ralphy models list --json | jq '.models[] | {id, priceUsd5s}'.
  • Whitelist check before --no-validate: confirm the duration / aspect you want is supported.
  • Frame-anchor support for an i2v pipeline that needs start+end refs.
  • Catalog refresh after OpenRouter ships a new model — pass --refresh once and the 24h cache picks up the addition.
The agent doesn’t typically run these — ralphy generate video validates against the same catalog before submit and rejects mismatched flags with E_VALIDATION_FAILED. Run them when debugging a rejection or planning a manual swap.

​
Cache + offline behavior

The catalog caches for 24h at workspace/.ralph/or-catalog.json. The fetcher in cli/lib/or-catalog.ts falls back to the stale cache when OpenRouter is unreachable — generation verbs still validate against the last-known catalog rather than failing closed. --refresh on any of the verbs forces a fresh fetch. Wipe the cache by deleting the file (or wait 24h).

​
Why this verb exists

The agent reads MODELS.md for the picks (which model to use for which job, with the postmortem-derived rationale). It reads ralphy models show <id> for the constraints (what params will be accepted). The two are deliberately separate: text + opinion in MODELS.md, structured data + cost in the catalog.