# Parameters

Every model keeps its native parameter names, and every model page lists them. On top of that, the API accepts
**canonical names** for the parameters that mean the same thing on every model, so code written for one model works
for the next one with fewer changes.

## Canonical names

| Canonical name | Meaning | Typical native names |
|---|---|---|
| `image` | The input or first-frame image | `image_url`, `start_image_url`, `first_frame_url`, `first_image_url`, `source_image_url` |
| `end_image` | The last-frame image | `end_image_url`, `last_frame_url`, `tail_image_url` |
| `images` | A list of reference images | `image_urls`, `reference_image_urls` |
| `video` | The input video | `video_url` |
| `videos` | A list of reference videos | `video_urls` |
| `audio` | The input audio | `audio_url` |
| `audios` | A list of reference audio clips | `audio_urls` |
| `mask` | A mask image | `mask_url` |
| `num_outputs` | How many results to generate | `num_images` |
| `generate_audio` | Generate sound with the video | `generate_audio_switch`, `enable_audio` |

Which native field a canonical name maps to on each current model:

| Canonical name | Native field (models using it) |
|---|---|
| `audio` | `audio_url` (models: 126) |
| `audios` | `audio_urls` (models: 7), `reference_audio_urls` (models: 1) |
| `end_image` | `end_image_url` (models: 76), `last_frame_url` (models: 12), `tail_image_url` (models: 1) |
| `generate_audio` | `generate_audio_switch` (models: 16), `audio` (models: 3) |
| `image` | `image_url` (models: 529), `start_image_url` (models: 20), `first_frame_url` (models: 12), `first_image_url` (models: 7), `source_image_url` (models: 2) |
| `images` | `image_urls` (models: 148), `reference_image_urls` (models: 31) |
| `mask` | `mask_url` (models: 46) |
| `num_outputs` | `num_images` (models: 337) |
| `video` | `video_url` (models: 197) |
| `videos` | `video_urls` (models: 13), `reference_video_urls` (models: 1) |

Rules:

- Send either the canonical name or the native one. If you send both with different values, the call fails with
  `422 invalid_input` on the canonical name.
- A parameter that is neither a native nor a canonical name of the model is rejected with `422 invalid_input`
  ("Unknown parameter"), with the closest valid name as a suggestion. Typos never pass silently.
- Each model page shows both names side by side.

## Type coercion

Values are converted to the type the model expects, so these all work:

| You send | Model expects | Becomes |
|---|---|---|
| `5`, `"5"`, `"5s"` | `duration` as a string such as `"5"` | `"5"` |
| `"8"` | an integer | `8` |
| `"1080P"`, `"4K"` | `resolution` such as `"1080p"`, `"4k"` | the exact allowed spelling |
| `"true"`, `"false"`, `1`, `0` | a boolean | `true`, `false` |
| `"https://…/a.jpg"` | a list of URLs | `["https://…/a.jpg"]` |
| `42` | a string | `"42"` |

Allowed values are matched exactly first, then ignoring case, then as numbers (`5` matches `"5"`, `"5s"` and
`"5 s"` style values).

## Defaults

Parameters you leave out use the model's default, which is listed in the model's parameter table. The price is
computed with the same defaults (for example, a video model whose `generate_audio` defaults to `true` is priced with
sound unless you send `"generate_audio": false`).

## File parameters

Image, video and audio parameters take a public URL, a `data:` URI up to 10 MB, or the `file_url` of an upload.
See [Files](https://doitong.com/developers/docs/files).