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_inputon 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.