# Schema

Generated by `php artisan aidir:export-specs`. Do not edit by hand — the next run overwrites it.

## Files

| File | Grain | Notes |
|---|---|---|
| `index.json` | whole dataset | `_meta` plus every model. The canonical machine copy. |
| `models/<slug>.json` | one model family | Same object as an element of `index.json`'s `models`. Stable path — cite this one. |
| `values.csv` | model × version × field | Long format. Carries provenance on every row, and one row per ABSENT field too. |
| `constraints.csv` | model × version × rule | Rules that couple two or more fields. Referenced from `values.csv`.`constrained_by`. |

## The three states

This is the distinction the dataset exists to preserve. A value is never merely present or missing.

| State | In JSON | In `values.csv` | Means |
|---|---|---|---|
| `known` | `state: "known"`, a non-null `value` | `state=known` | Read off a vendor page on `verified_on`. |
| `unpublished` | `state: "unpublished"`, `value: null`, a `note` | `state=unpublished`, empty `value` | Somebody checked and the vendor publishes no figure. `source_url` is the page that was read. **This is a finding, not a gap.** |
| `absent` | the key is listed in `absent_fields` | `state=absent`, every provenance column empty | Nobody has researched this field for this version. **Not "no". Not "0".** |

There is no fourth state for "we think it is about ten seconds".

## Every value object

```json
{
  "state": "known",
  "value": 15,
  "scope": "qualification that makes the value honest, or null",
  "note": "what the vendor does not publish, when state is unpublished",
  "source_url": "https://vendor.example/docs/api",
  "source_title": "Create video — Vendor API reference",
  "verified_on": "2026-08-20"
}
```

`scope` is not decoration. It is what stops a technically-sourced value from being misleading: a model whose 2K output comes from a separately-priced regeneration module is recorded at its base resolution with the module named in `scope`, because recording 2K bare would be sourced and wrong in effect.

## Constraints

Every value on a row can be individually correct while the **row** asserts something the vendor does not sell. One family takes exactly 6 or 10 seconds and offers 1080P at 6 seconds only — so a row reading "max 10s" beside "max 1080P" claims a clip that cannot be generated. Neither cell is wrong; the row is.

`scope` cannot express that, because it qualifies one value while this couples several. A constraint names the coupled fields in `affects` so a renderer can mark **those cells** rather than footnote the table. It carries the same provenance as a value, and it counts toward freshness — a claim about the vendor rots exactly like a number does.

## Prices

`price` and `price_cn` are **separate values, never converted into one another.** The same model is sold on a vendor's international platform and on its mainland-China platform at separately set prices. There is no exchange rate that makes those two numbers the same number, and publishing one would imply a conversion the vendor never made.

A price is `{amount, currency, per}`. `per` is load-bearing: some families bill per second and others per clip at fixed tiers, and a bare per-second figure silently misstates half of them.

## Fields — `video/v1`

| Field | Type | Unit | Meaning |
|---|---|---|---|
| `max_duration_s` | int | s | Longest single generation, in seconds. Not a stitched sequence. |
| `min_duration_s` | int | s | Min clip length |
| `duration_choices` | list | s | Only when the vendor offers a fixed set (6 or 10 and nothing between). Absent means free-form within the range. |
| `max_resolution` | string | — | Of the BASE model. A paid upscale module belongs in scope, not here. |
| `fps` | int | fps | Frame rate |
| `native_audio` | bool | — | The model itself emits synchronised audio — not a separate TTS pass bolted on after. |
| `modes` | list | — | t2v text-to-video, i2v image-to-video, fl2v first/last frame, ref2v subject reference, s2v speech-driven, v2v video-to-video, ref2va reference to video+audio. Known members: `t2v`, `i2v`, `fl2v`, `ref2v`, `s2v`, `v2v`, `ref2va` — the list is advisory, not closed. |
| `api_available` | bool | — | Self-serve. An enterprise contact form is not an API. |
| `price` | money | — | Vendor billing currency kept as billed — CNY stays CNY (entry standard, pricing section). The `per` member is load-bearing, not decoration: MiniMax H3 bills PER SECOND while its own 2.x line bills PER CLIP at fixed tiers, so a bare per-second number silently misstates half the family. |
| `price_cn` | money | — | The SAME product sold on a separate mainland-China platform at a separately-set price — MiniMax's platform.minimax.io (USD) against platform.minimaxi.com (CNY), Zhipu's z.ai against bigmodel.cn. A second field rather than a converted figure, because these are two price lists, not one price in two currencies: there is no exchange rate that makes $0.13/s and ¥0.80/s the same number, and writing one implies a conversion the vendor never published. |
| `open_weights` | bool | — | Open weights |
| `license` | string | — | Licence |
| `watermark` | enum | — | An AIGC label is legally mandatory for CN-mainland services; say so in scope rather than reading it as a vendor choice. One of: `always`, `free-tier`, `optional`, `none`. |
| `region_availability` | string | — | Availability |
| `negative_prompt` | bool | — | The VENDOR's own API. A wrapper service that pre-processes one does not count — that is the wrapper's feature. |
| `max_input_images` | int | — | Max input images |

## Version status

| Status | Means |
|---|---|
| `current` | Generally available and the vendor's live recommendation. |
| `preview` | Shipped and callable, labelled preview/beta by the vendor. |
| `legacy` | Still callable, superseded or scheduled for removal. |

A version is the unit of comparison, never a product. One family routinely runs several versions with incompatible specs at the same time, and collapsing them into one row produces a number that is true of no shipped model. `is_flagship` marks the one a single-row-per-product table should show: the first `current` version, else the first `preview` one, else the first listed.