Skip to content
Sign Up Free
Seedance

Seedance video API: models, fields and media requirements

Connect to Seedance 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. The four China-region models support three generation operations; the two SR models support text-to-video and single-first-frame image-to-video. Choose a Model ID by operation, duration and output level.

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 IDOperationDuration (seconds)Output levelAspect ratioAudioMedia roles
ByteDance-Seedance-2.0-SRimage_to_video5–10, step 5720p, 1080p, 4k16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offfirst_frame
ByteDance-Seedance-2.0-SRtext_to_video5–10, step 5720p, 1080p, 4k16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offNone
ByteDance-Seedance-2.5-SRimage_to_video5–10, step 5720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offfirst_frame
ByteDance-Seedance-2.5-SRtext_to_video5–10, step 5720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offNone
doubao-seedance-2-0-260128image_to_video4–15, step 1; supports auto480p, 720p, 1080p, 4k16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offfirst_frame, last_frame
doubao-seedance-2-0-260128reference_to_video4–15, step 1; supports auto480p, 720p, 1080p, 4k16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offreference_image, reference_video, reference_audio
doubao-seedance-2-0-260128text_to_video4–15, step 1; supports auto480p, 720p, 1080p, 4k16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offNone
doubao-seedance-2-0-fast-260128image_to_video4–15, step 1; supports auto480p, 720p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offfirst_frame, last_frame
doubao-seedance-2-0-fast-260128reference_to_video4–15, step 1; supports auto480p, 720p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offreference_image, reference_video, reference_audio
doubao-seedance-2-0-fast-260128text_to_video4–15, step 1; supports auto480p, 720p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offNone
doubao-seedance-2-0-mini-260615image_to_video4–15, step 1; supports auto480p, 720p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offfirst_frame, last_frame
doubao-seedance-2-0-mini-260615reference_to_video4–15, step 1; supports auto480p, 720p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offreference_image, reference_video, reference_audio
doubao-seedance-2-0-mini-260615text_to_video4–15, step 1; supports auto480p, 720p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offNone
doubao-seedance-2-5-260628image_to_video4–30, step 1; supports auto480p, 720p, 1080padaptiveon, offfirst_frame, last_frame
doubao-seedance-2-5-260628reference_to_video4–30, step 1; supports auto480p, 720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offreference_image, reference_video, reference_audio
doubao-seedance-2-5-260628text_to_video4–30, step 1; supports auto480p, 720p, 1080p16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveon, offNone

The two SR models support only 5 or 10 seconds for fixed duration. China-region and SR models have different Model IDs. Do not apply one model’s field or media limits to another model.

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.

Video generation reference: a blue ceramic mug on a white table

Text-to-video

ByteDance-Seedance-2.0-SR

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixedfixed
duration.secondsintegerNo5–10, step 5 s; only for fixed duration5
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive16:9
output.formatstringNomp4mp4
output.resolutionstringNo720p, 1080p, 4k720p
promptstringYesstringNone
watermarkbooleanNofalsefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "ByteDance-Seedance-2.0-SR",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.

ByteDance-Seedance-2.5-SR

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixedfixed
duration.secondsintegerNo5–10, step 5 s; only for fixed duration5
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive16:9
output.formatstringNomp4mp4
output.resolutionstringNo720p, 1080p720p
promptstringYesstringNone
watermarkbooleanNofalsefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "ByteDance-Seedance-2.5-SR",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.

doubao-seedance-2-0-260128

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p, 1080p, 4k720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-0-260128",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.

doubao-seedance-2-0-fast-260128

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-0-fast-260128",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.

doubao-seedance-2-0-mini-260615

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-0-mini-260615",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.

doubao-seedance-2-5-260628

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autoauto
duration.secondsintegerNo4–30, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p, 1080p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

This operation does not accept media.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-5-260628",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.

Image-to-video

ByteDance-Seedance-2.0-SR

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixedfixed
duration.secondsintegerNo5–10, step 5 s; only for fixed duration5
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive16:9
output.formatstringNomp4mp4
output.resolutionstringNo720p, 1080p, 4k720p
promptstringYesstringNone
watermarkbooleanNofalsefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, 1 (required)jpeg, png, webpsize at most 10 MB; width 128–4096 px; height 128–4096 px

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • 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": "ByteDance-Seedance-2.0-SR",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

ByteDance-Seedance-2.5-SR

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixedfixed
duration.secondsintegerNo5–10, step 5 s; only for fixed duration5
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive16:9
output.formatstringNomp4mp4
output.resolutionstringNo720p, 1080p720p
promptstringYesstringNone
watermarkbooleanNofalsefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, 1 (required)jpeg, png, webpsize at most 10 MB; width 128–4096 px; height 128–4096 px

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • 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": "ByteDance-Seedance-2.5-SR",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

doubao-seedance-2-0-260128

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p, 1080p, 4k720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, 1 (required)jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
last_frameimage, optional, at most 1jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • 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": "doubao-seedance-2-0-260128",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

doubao-seedance-2-0-fast-260128

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, 1 (required)jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
last_frameimage, optional, at most 1jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • 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": "doubao-seedance-2-0-fast-260128",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

doubao-seedance-2-0-mini-260615

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, 1 (required)jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
last_frameimage, optional, at most 1jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • 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": "doubao-seedance-2-0-mini-260615",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

doubao-seedance-2-5-260628

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autoauto
duration.secondsintegerNo4–30, step 1 s; only for fixed durationNone
output.aspect_ratiostringNoadaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p, 1080p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
first_frameimage, 1 (required)jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
last_frameimage, optional, at most 1jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • You must provide first_frame.
  • This operation requires output.aspect_ratio="adaptive", whether you supply only the first frame or both the first and last frames.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-5-260628",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

Reference generation

doubao-seedance-2-0-260128

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p, 1080p, 4k720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
reference_imageimage, optional, at most 9jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
reference_videovideo, optional, at most 3mp4, movsize at most 200 MB; width 300–6000 px; height 300–6000 px; duration 2–15 s; frame rate at least 24 fps, and at most 60 fps; total for this role at most 15 s
reference_audioaudio, optional, at most 3wav, mp3size at most 15 MB; duration 2–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" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • Provide at least one of these roles: reference_image, reference_video, reference_audio.
  • Reference audio cannot be used alone. Also provide a reference image or reference video.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-0-260128",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

doubao-seedance-2-0-fast-260128

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
reference_imageimage, optional, at most 9jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
reference_videovideo, optional, at most 3mp4, movsize at most 200 MB; width 300–6000 px; height 300–6000 px; duration 2–15 s; frame rate at least 24 fps, and at most 60 fps; total for this role at most 15 s
reference_audioaudio, optional, at most 3wav, mp3size at most 15 MB; duration 2–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" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • Provide at least one of these roles: reference_image, reference_video, reference_audio.
  • Reference audio cannot be used alone. Also provide a reference image or reference video.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-0-fast-260128",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

doubao-seedance-2-0-mini-260615

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autofixed
duration.secondsintegerNo4–15, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
reference_imageimage, optional, at most 9jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
reference_videovideo, optional, at most 3mp4, movsize at most 200 MB; width 300–6000 px; height 300–6000 px; duration 2–15 s; frame rate at least 24 fps, and at most 60 fps; total for this role at most 15 s
reference_audioaudio, optional, at most 3wav, mp3size at most 15 MB; duration 2–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" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • Provide at least one of these roles: reference_image, reference_video, reference_audio.
  • Reference audio cannot be used alone. Also provide a reference image or reference video.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-0-mini-260615",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck the public HTTPS URL, Content-Type and file format, then quote again.

doubao-seedance-2-5-260628

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.

FieldTypeRequiredAllowed values or rangeDefault
audio.modestringNoon, offon
duration.modestringNofixed, autoauto
duration.secondsintegerNo4–30, step 1 s; only for fixed durationNone
output.aspect_ratiostringNo16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptiveadaptive
output.formatstringNomp4mp4
output.resolutionstringNo480p, 720p, 1080p720p
promptstringYesstringNone
watermarkbooleanNofalse, truefalse

Media requirements

Media roleType and countFormatsPer-file limits
reference_imageimage, optional, at most 30jpeg, png, webp, bmp, tiff, gif, heic, heifsize 1–31457279 bytes; width 300–6000 px; height 300–6000 px
reference_videovideo, optional, at most 10mp4, movsize at most 200 MB; width 300–6000 px; height 300–6000 px; duration 2–30 s; frame rate at least 24 fps, and at most 60 fps; total for this role at most 30 s
reference_audioaudio, optional, at most 10wav, mp3size at most 15 MB; duration 2–30 s; total for this role at most 30 s

Whether media is required also depends on the combination constraints below.

Combination constraints

  • duration.mode="fixed" requires duration.seconds. Include the number of seconds whenever you explicitly set fixed.
  • Do not send duration.seconds when using duration.mode="auto".
  • Provide at least one of these roles: reference_image, reference_video, reference_audio.

Request example

Save the JSON below as request.json, then follow the shared workflow to quote first and create after confirmation.

{
"model": "doubao-seedance-2-5-260628",
"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 codeAction
enum / range / stepAdjust values and increments to match this subsection’s field table.
unsupported_fieldRemove fields absent from this operation’s field table.
requiresAdd seconds, aspect ratio, audio settings or media as required by this subsection’s combination constraints.
excludesRemove fields that conflict with automatic duration or the last frame.
count / media_roleAdjust roles and counts to match this subsection’s media table.
video_input_unsupportedCheck 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.