Wan video API: text, image, reference and editing
Connect to Wan with a BetterToken API Key and choose fields, media and generation methods by Model ID and operation.
Generate videos from text, a first frame or reference media, or edit an existing video. 3.0 and Prime support three generation operations. For 2.7, choose separate Model IDs for text-to-video, image-to-video, reference generation and editing.
Prepare your BetterToken API Key. The Base URL is https://bettertoken.ai/v1, with Authorization: Bearer YOUR_API_KEY for authentication. Copy the Model ID exactly, including capitalization.
Every request.json below follows the same workflow: quote, confirm creation, poll and download. A quote does not start generation; creating a task submits a paid request. See current costs in the model plaza.
Models and operations
The table below lists available values by operation. See each subsection for field defaults, media counts and combination constraints. Media sizes use 1 MB = 1048576 bytes.
| Model ID | Operation | Duration (seconds) | Output level | Aspect ratio | Audio | Media roles |
|---|---|---|---|---|---|---|
wan2.7-i2v | image_to_video | 2–15, step 1 | 720p, 1080p | omit | provider_default | first_frame, last_frame, driving_audio |
wan2.7-r2v | reference_to_video | 2–15, step 1 | 720p, 1080p | 16:9, 9:16, 1:1, 4:3, 3:4 | provider_default | reference_image, reference_video |
wan2.7-t2v | text_to_video | 2–15, step 1 | 720p, 1080p | 16:9, 9:16, 1:1, 4:3, 3:4 | provider_default | driving_audio |
wan2.7-videoedit | video_edit | 2–15, step 1; supports auto | 720p, 1080p | omit | provider_default | base_video |
wan3.0-video-prime | image_to_video | 2–30, step 1; supports auto | 480p, 720p, 1080p | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | on, off | first_frame, last_frame |
wan3.0-video-prime | reference_to_video | 2–30, step 1; supports auto | 480p, 720p, 1080p | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | on, off | reference_image, reference_video, reference_audio |
wan3.0-video-prime | text_to_video | 2–30, step 1; supports auto | 480p, 720p, 1080p | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | on, off | None |
wan3.0-video | image_to_video | 2–30, step 1; supports auto | 480p, 720p, 1080p | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | on, off | first_frame, last_frame |
wan3.0-video | reference_to_video | 2–30, step 1; supports auto | 480p, 720p, 1080p | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | on, off | reference_image, reference_video, reference_audio |
wan3.0-video | text_to_video | 2–30, step 1; supports auto | 480p, 720p, 1080p | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | on, off | None |
For image-to-video (wan2.7-i2v, and wan3.0-video / wan3.0-video-prime with adaptive) and reference-to-video with adaptive, the output follows the input image’s aspect ratio; the output tier sets the total pixel count, not fixed dimensions. With this page’s 1:1 sample image, 720p returned 960×960 and 480p returned 640×640 in our tests. To get a fixed landscape or portrait frame, set output.aspect_ratio explicitly (wan2.7-i2v does not accept this field; use an input image with the ratio you need).
Sample media
The image-to-video and image-reference examples use a blue ceramic mug on a white table. Keep the sample image to try them, or first replace it with public HTTPS media that you have the right to use and that meets this page’s limits.

The editing example uses a video of a boy in a city square, about 5.04 seconds, 1280 × 720, at 24 fps. It is supplied as base_video, not as a reference image.
Text-to-video
wan2.7-t2v
Use this operation when you have only a text description.
Set model to this subsection’s Model ID and operation to text_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | provider_default | provider_default |
duration.mode | string | No | fixed | fixed |
duration.seconds | integer | No | 2–15, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | 16:9, 9:16, 1:1, 4:3, 3:4 | 16:9 |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
driving_audio | audio, optional, at most 1 | wav, mp3 | size at most 15 MB; duration 2–30 s |
Whether media is required also depends on the combination constraints below.
The optional driving_audio role supplies driving audio and uses type="audio". It is a different media role from reference_audio in reference generation.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan2.7-t2v", "operation": "text_to_video", "prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "16:9" }}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
wan3.0-video-prime
Use this operation when you have only a text description.
Set model to this subsection’s Model ID and operation to text_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | on, off | on |
duration.mode | string | No | fixed, auto | fixed |
duration.seconds | integer | No | 2–30, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 480p, 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
This operation does not accept media.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- Do not send
duration.secondswhen usingduration.mode="auto".
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan3.0-video-prime", "operation": "text_to_video", "prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "16:9" }}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
excludes | Remove fields that conflict with automatic duration or the last frame. |
wan3.0-video
Use this operation when you have only a text description.
Set model to this subsection’s Model ID and operation to text_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | on, off | on |
duration.mode | string | No | fixed, auto | fixed |
duration.seconds | integer | No | 2–30, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 480p, 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
This operation does not accept media.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- Do not send
duration.secondswhen usingduration.mode="auto".
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan3.0-video", "operation": "text_to_video", "prompt": "A blue ceramic mug on a white table. Slowly move the camera closer in soft daylight.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "16:9" }}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
excludes | Remove fields that conflict with automatic duration or the last frame. |
Image-to-video
wan2.7-i2v
Use this operation to set the opening frame or both the first and last frames with images.
Set model to this subsection’s Model ID and operation to image_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | provider_default | provider_default |
duration.mode | string | No | fixed | fixed |
duration.seconds | integer | No | 2–15, step 1 s; only for fixed duration | 5 |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
first_frame | image, 1 (required) | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
last_frame | image, optional, at most 1 | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
driving_audio | audio, optional, at most 1 | wav, mp3 | size at most 15 MB; duration 2–30 s |
Whether media is required also depends on the combination constraints below.
The optional driving_audio role supplies driving audio and uses type="audio". It is a different media role from reference_audio in reference generation.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- You must provide
first_frame.
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan2.7-i2v", "operation": "image_to_video", "prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p" }, "media": [ { "id": "first", "type": "image", "role": "first_frame", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
wan3.0-video-prime
Use this operation to set the opening frame or both the first and last frames with images.
Set model to this subsection’s Model ID and operation to image_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | on, off | on |
duration.mode | string | No | fixed, auto | fixed |
duration.seconds | integer | No | 2–30, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 480p, 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
first_frame | image, 1 (required) | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
last_frame | image, optional, at most 1 | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
Whether media is required also depends on the combination constraints below.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- Do not send
duration.secondswhen usingduration.mode="auto". - Provide at least one of these roles:
first_frame,last_frame.
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan3.0-video-prime", "operation": "image_to_video", "prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "adaptive" }, "media": [ { "id": "first", "type": "image", "role": "first_frame", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
excludes | Remove fields that conflict with automatic duration or the last frame. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
wan3.0-video
Use this operation to set the opening frame or both the first and last frames with images.
Set model to this subsection’s Model ID and operation to image_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | on, off | on |
duration.mode | string | No | fixed, auto | fixed |
duration.seconds | integer | No | 2–30, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 480p, 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
first_frame | image, 1 (required) | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
last_frame | image, optional, at most 1 | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
Whether media is required also depends on the combination constraints below.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- Do not send
duration.secondswhen usingduration.mode="auto". - Provide at least one of these roles:
first_frame,last_frame.
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan3.0-video", "operation": "image_to_video", "prompt": "Slowly move the camera closer to the blue ceramic mug. Preserve its shape and the white table.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "adaptive" }, "media": [ { "id": "first", "type": "image", "role": "first_frame", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
excludes | Remove fields that conflict with automatic duration or the last frame. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
Reference generation
wan2.7-r2v
Use this operation to preserve subject or motion characteristics from reference media.
Set model to this subsection’s Model ID and operation to reference_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | provider_default | provider_default |
duration.mode | string | No | fixed | fixed |
duration.seconds | integer | No | 2–15, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | 16:9, 9:16, 1:1, 4:3, 3:4 | 16:9 |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
reference_image | image, optional, at most 10 | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
reference_video | video, optional, at most 5 | mp4, mov | size at most 100 MB; width 240–4096 px; height 240–4096 px; duration 1–15 s; frame rate at least 16 fps; total for this role at most 15 s |
Whether media is required also depends on the combination constraints below.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- Provide at least one of these roles:
reference_image,reference_video.
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan2.7-r2v", "operation": "reference_to_video", "prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "16:9" }, "media": [ { "id": "reference", "type": "image", "role": "reference_image", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
wan3.0-video-prime
Use this operation to preserve subject or motion characteristics from reference media.
Set model to this subsection’s Model ID and operation to reference_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | on, off | on |
duration.mode | string | No | fixed, auto | fixed |
duration.seconds | integer | No | 2–30, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 480p, 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
reference_image | image, optional, at most 10 | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
reference_video | video, optional, at most 5 | mp4, mov | size at most 100 MB; width 240–4096 px; height 240–4096 px; duration 1–15 s; frame rate at least 16 fps; total for this role at most 15 s |
reference_audio | audio, optional, at most 5 | wav, mp3 | size at most 15 MB; duration 1–15 s; total for this role at most 15 s |
Whether media is required also depends on the combination constraints below.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- Do not send
duration.secondswhen usingduration.mode="auto". - Provide at least one of these roles:
reference_image,reference_video,reference_audio. - With reference video, the total input-video duration plus output duration must not exceed 30 seconds. Automatic output duration is also capped by this remaining allowance.
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan3.0-video-prime", "operation": "reference_to_video", "prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "adaptive" }, "media": [ { "id": "reference", "type": "image", "role": "reference_image", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
excludes | Remove fields that conflict with automatic duration or the last frame. |
sum_lte | Shorten the total reference-video duration or output duration so their sum does not exceed 30 seconds. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
wan3.0-video
Use this operation to preserve subject or motion characteristics from reference media.
Set model to this subsection’s Model ID and operation to reference_to_video. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | on, off | on |
duration.mode | string | No | fixed, auto | fixed |
duration.seconds | integer | No | 2–30, step 1 s; only for fixed duration | 5 |
output.aspect_ratio | string | No | adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | adaptive |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 480p, 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
reference_image | image, optional, at most 10 | jpeg, jpg, png, bmp, webp | size at most 20 MB; width 240–8000 px; height 240–8000 px |
reference_video | video, optional, at most 5 | mp4, mov | size at most 100 MB; width 240–4096 px; height 240–4096 px; duration 1–15 s; frame rate at least 16 fps; total for this role at most 15 s |
reference_audio | audio, optional, at most 5 | wav, mp3 | size at most 15 MB; duration 1–15 s; total for this role at most 15 s |
Whether media is required also depends on the combination constraints below.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- Do not send
duration.secondswhen usingduration.mode="auto". - Provide at least one of these roles:
reference_image,reference_video,reference_audio. - With reference video, the total input-video duration plus output duration must not exceed 30 seconds. Automatic output duration is also capped by this remaining allowance.
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan3.0-video", "operation": "reference_to_video", "prompt": "Create a product video of the blue ceramic mug in the reference image. Keep its shape and color.", "duration": { "mode": "fixed", "seconds": 5 }, "output": { "resolution": "720p", "aspect_ratio": "adaptive" }, "media": [ { "id": "reference", "type": "image", "role": "reference_image", "source": "https://docs.bettertoken.ai/images/nano-banana-guide/sample-07.png" } ]}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
excludes | Remove fields that conflict with automatic duration or the last frame. |
sum_lte | Shorten the total reference-video duration or output duration so their sum does not exceed 30 seconds. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
Video editing
wan2.7-videoedit
Use this operation to change the visuals of an existing video. Prepare a source video that meets the limits first.
Set model to this subsection’s Model ID and operation to video_edit. Use only the generation fields listed below. Put media in the media array.
| Field | Type | Required | Allowed values or range | Default |
|---|---|---|---|---|
audio.mode | string | No | provider_default | provider_default |
duration.mode | string | No | fixed, auto | auto |
duration.seconds | integer | No | 2–15, step 1 s; only for fixed duration | None |
output.format | string | No | mp4 | mp4 |
output.resolution | string | No | 720p, 1080p | 1080p |
prompt | string | Yes | string | None |
provider_options.alibaba.prompt_extend | boolean | No | true / false; controls prompt expansion | true |
seed | integer | No | 0–2147483647, step 1; random seed; may be 0 | None |
watermark | boolean | No | false, true | false |
Media requirements
| Media role | Type and count | Formats | Per-file limits |
|---|---|---|---|
base_video | video, 1 (required) | mp4, mov | size at most 100 MB; width 240–4096 px; height 240–4096 px; duration 1–15 s; frame rate at least 16 fps; total for this role at most 15 s |
Whether media is required also depends on the combination constraints below.
Combination constraints
duration.mode="fixed"requiresduration.seconds. Include the number of seconds whenever you explicitly setfixed.- You must provide
base_video. - Do not send
duration.secondswhen usingduration.mode="auto".
Request example
Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.
{ "model": "wan2.7-videoedit", "operation": "video_edit", "prompt": "Keep the boy and his motion in the source video. Give the city plaza warmer evening lighting.", "duration": { "mode": "auto" }, "output": { "resolution": "720p" }, "media": [ { "id": "base", "type": "video", "role": "base_video", "source": "https://bettertoken.ai/video-api/shared/kling-hero-3.0.mp4" } ]}Common 422 errors
| 422 error code | Action |
|---|---|
enum / range / step | Adjust values and increments to match this subsection’s field table. |
unsupported_field | Remove fields absent from this operation’s field table. |
requires | Add seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints. |
excludes | Remove fields that conflict with automatic duration or the last frame. |
count / media_role | Adjust roles and counts to match this subsection’s media table. |
video_input_unsupported | Check the public HTTPS URL, Content-Type and file format, then quote again. |
Official resources
When calling BetterToken, use this page’s fields and the corresponding operation in the live model catalog.

