> ## Documentation Index
> Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> ralphy models list, show, alias — inspect the OpenRouter video catalog ralphy ships against.

`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](https://github.com/alecs5am/ralphy/blob/main/AGENTS.md), agents read [MODELS.md](https://github.com/alecs5am/ralphy/blob/main/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.

```bash theme={"dark"}
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: [...] }`.

```bash theme={"dark"}
ralphy models list --json | jq '.models[] | select(.frames | contains("last_frame"))'
# → every model that supports first/last frame i2v
```

Full surface: [`/reference/cli/models`](/reference/cli/models).

## ralphy models show \<id>

Full schema for one model — description, supported params, price at 1s / 5s / 10s.

```bash theme={"dark"}
ralphy models show kwaivgi/kling-v3.0-pro
ralphy models show bytedance/seedance-2.0 --refresh
```

Sample shape:

```json theme={"dark"}
{
  "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`](/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`.

```bash theme={"dark"}
ralphy models alias kling
# → { shorthand, canonical, matched, siblings }

ralphy models alias              # no arg → dump the full alias map
```

Full surface: [`/reference/cli/models`](/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 `.ralphy/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.

## Related

* [Generation verbs](/cli/generation-verbs) — `--model` flag and the validation gate
* [MODELS.md](https://github.com/alecs5am/ralphy/blob/main/MODELS.md) — picks + rationale
* [Models registry](/advanced/models-registry) — deeper conceptual notes
* [cli/commands/models.ts](https://github.com/alecs5am/ralphy/blob/main/cli/commands/models.ts), [cli/lib/or-catalog.ts](https://github.com/alecs5am/ralphy/blob/main/cli/lib/or-catalog.ts)