Appearance
seedance-2.0-sz / seedance-2.5-sz
seedance-2.0-sz、seedance-2.0-sz-fast、seedance-2.0-sz-mini 和 seedance-2.5-sz 统一使用 /v1/videos 创建异步视频任务。请求参数沿用 Seedance 官方多模态接口的字段语义；MoonApiX 的 references[] 是新接入推荐的 统一素材写法，服务端会转换为模型所需的多模态内容结构。
型号选择
| 模型 | 定位 | 分辨率 | 时长 |
|---|---|---|---|
seedance-2.0-sz | 标准多模态视频生成 | 480P、720P、1080P、4K | 4 - 15 秒，或智能时长 -1 |
seedance-2.0-sz-fast | 快速多模态视频生成 | 480P、720P | 4 - 15 秒，或智能时长 -1 |
seedance-2.0-sz-mini | 轻量多模态视频生成 | 480P、720P | 4 - 15 秒，或智能时长 -1 |
seedance-2.5-sz | 新一代多模态视频生成 | 480P、720P、1080P | 4 - 30 秒，或智能时长 -1 |
实际可用的模型、分辨率、时长和比例以 GET /v1/models 返回的能力以及控制台为准。
能力边界
| 能力 | seedance-2.0-sz 系列 | seedance-2.5-sz |
|---|---|---|
| 文生视频 | 支持 | 支持 |
| 图片参考 | 最多 9 张 | 最多 30 张 |
| 视频参考 | 最多 3 个 | 最多 10 个 |
| 音频参考 | 最多 3 个；需同时提供图片或视频 | 最多 10 个；需同时提供图片或视频 |
| 混合素材 | 最多 15 个参考素材 | 最多 50 个参考素材 |
| 首帧 / 尾帧 | 支持 | 支持 |
| 视频编辑 / 延长 | 支持 | 以模型能力为准 |
| 真人参考 | 支持；仍需通过内容安全审核 | 支持；仍需通过内容安全审核 |
音频不能单独作为输入。可以提交文本、图片、视频、音频的任意合法组合，但至少要有一张图片或一个视频才能提交音频参考。素材 URL 必须是无需登录、无需 Cookie 或额外鉴权 Header 即可下载的稳定公网媒体直链。
请求参数
以下是 SZ 系列常用且与官方字段对应的参数。除表中说明外，参数是否可用仍以所选模型的能力配置为准。
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 必填。四个 SZ 公开模型之一。 |
prompt | string | 可选。描述主体、动作、镜头、场景和风格；也可以把文本放入 content[] 的 text 条目。 |
references | array | 推荐的统一素材数组。每项使用 media_type、role、url 和可选的 alias。 |
content | array | 官方兼容写法。条目类型为 text、image_url、video_url 或 audio_url；媒体条目建议显式填写 role。 |
ratio | string | 官方比例字段，例如 16:9、9:16、1:1、4:3、3:4、21:9 或 adaptive。 |
aspect_ratio | string | MoonApiX 兼容别名；服务端会转换为官方 ratio。不要在同一请求同时传入两个不同值。 |
resolution | string | 分辨率，例如 480p、720p、1080p 或 4k；以所选模型支持范围为准。 |
duration | integer | 目标时长（秒）。2.0 系列支持 4 - 15，2.5 支持 4 - 30；-1 表示模型自动选择整数秒时长。 |
frames | integer | 这四个 SZ 模型不支持。请使用 duration，不要同时发送 frames。 |
generate_audio | boolean | 是否生成音轨。true 生成有声视频，false 生成无声视频。官方默认值为 true；建议显式传入。 |
watermark | boolean | 是否添加水印；需要明确结果时请显式传 true 或 false。 |
seed | integer | 随机种子。使用 -1 或不传表示随机；相同请求和种子只能获得相近结果。 |
camera_fixed | boolean | 2.0 / Fast / Mini 不支持；2.5 仅接受 false。通常应省略并让模型决定运镜。 |
return_last_frame | boolean | 是否在任务结果中返回尾帧信息，默认 false。 |
omni_reference_task_type | string | 仅 2.5 支持。可选 auto、reference、edit、extend；默认 auto。edit 必须包含参考视频，并使用 ratio: adaptive、duration: -1；extend 必须包含参考视频并使用 ratio: adaptive。 |
output_format | string | 仅 2.5 支持。可选 mp4 或 mov，默认 mp4；专业后期、编辑或延长场景可使用 mov。 |
priority | integer | 可选排队优先级，范围 0 - 9，默认 0。仅在账户和模型能力允许时使用。显式 0 会被保留。 |
draft | boolean | 这四个 SZ 模型不支持，不要发送。 |
service_tier | string | 服务等级。这四个 SZ 模型使用 default，不支持 flex。 |
execution_expires_after | integer | 任务执行有效期（秒），范围 3600 - 259200。不传时使用平台默认值。 |
tools | array | 可选工具配置。仅在模型页面明确支持时使用。 |
safety_identifier | string | 可选的终端用户安全标识，最多 64 个可打印字符。不要放入密钥或个人敏感信息。 |
callback_url | string | 可选。任务状态变化后的 HTTPS 回调地址；收到回调后仍应查询核对 status 和 error。 |
generateAudio 是历史兼容别名，语义与 generate_audio 相同，新的客户端应使用下划线字段。显式传入的 false 不会被当作缺省值丢弃。
创建示例
1. 纯文生视频
bash
curl https://moonapix.com/v1/videos \
-H "Authorization: Bearer <MOONAPIX_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-sz-fast",
"prompt": "一只橘猫在窗边伸懒腰，镜头缓慢推近，午后自然光，写实风格。",
"duration": 4,
"ratio": "16:9",
"resolution": "480p",
"generate_audio": true,
"watermark": false
}'2. 单图片图生视频（关闭声音）
bash
curl https://moonapix.com/v1/videos \
-H "Authorization: Bearer <MOONAPIX_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-sz-mini",
"prompt": "让人物自然转身并向镜头微笑，保持服装和脸部特征稳定。",
"duration": 4,
"aspect_ratio": "9:16",
"resolution": "480p",
"generate_audio": false,
"references": [
{
"media_type": "image",
"role": "reference_image",
"url": "https://example.com/person.png",
"alias": "人物"
}
]
}'3. 图片 + 视频 + 音频组合（生成有声视频）
json
{
"model": "seedance-2.0-sz",
"prompt": "使用@人物的外观，参考@动作的运镜，并将@音乐作为背景音乐。",
"duration": 8,
"ratio": "16:9",
"resolution": "720p",
"generate_audio": true,
"references": [
{ "media_type": "image", "role": "reference_image", "url": "https://example.com/person.png", "alias": "人物" },
{ "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4", "alias": "动作" },
{ "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3", "alias": "音乐" }
]
}4. 首帧 + 尾帧
json
{
"model": "seedance-2.0-sz",
"prompt": "从室内平滑过渡到户外，保持主体和色彩连续。",
"duration": 6,
"ratio": "16:9",
"resolution": "1080p",
"generate_audio": false,
"content": [
{ "type": "image_url", "role": "first_frame", "image_url": { "url": "https://example.com/first.jpg" } },
{ "type": "image_url", "role": "last_frame", "image_url": { "url": "https://example.com/last.jpg" } }
]
}5. 文本放在 content[] 并使用智能时长
json
{
"model": "seedance-2.5-sz",
"content": [
{ "type": "text", "text": "一段电影感的城市夜景航拍。" }
],
"duration": -1,
"ratio": "adaptive",
"resolution": "1080p",
"seed": 42,
"camera_fixed": false,
"generate_audio": true,
"watermark": false,
"callback_url": "https://example.com/webhooks/moonapix"
}6. Seedance 2.5 视频编辑并输出 MOV
json
{
"model": "seedance-2.5-sz",
"prompt": "保留主体动作，调整为清晨自然光，并延续原视频的镜头节奏。",
"duration": -1,
"ratio": "adaptive",
"resolution": "1080p",
"omni_reference_task_type": "edit",
"output_format": "mov",
"generate_audio": true,
"references": [
{
"media_type": "video",
"role": "reference_video",
"url": "https://example.com/source.mp4",
"alias": "原视频"
}
]
}SZ 四个公开模型均使用 duration，不要发送 frames 或把不需要的字段设为 null。2.5 的 edit / extend 请求必须满足上表约束；任务虽然可以创建，模型仍可能因素材或提示词与指定任务类型不一致而异步失败。
参考素材角色
role | 用途 |
|---|---|
reference_image | 普通图片参考 |
first_frame | 首帧图片 |
last_frame | 尾帧图片 |
reference_video | 动作、画面或运镜参考视频 |
reference_audio | 音频参考；必须和图片或视频一起提交 |
提示词中的 @alias 只用于描述素材语义，服务端仍以 references[] 或 content[] 的结构化角色校验为准。需要严格首尾帧时，应显式使用 first_frame / last_frame。
素材可以使用客户自有的匿名公网直链，也可以使用已就绪的 MoonApiX Asset://asset_xxx 引用。公网地址不需要先调用 /v1/assets/uploads；只有需要托管、复用或由 MoonApiX 管理素材生命周期时才使用资产接口。无论采用哪种方式，素材仍需通过格式、时长、大小和内容安全检查。
查询任务与下载结果
提交后保存返回的 id 或 task_id，先查询状态，只有 status 为 succeeded 且没有 error 时才读取结果地址：
bash
curl https://moonapix.com/v1/videos/<TASK_ID> \
-H "Authorization: Bearer <MOONAPIX_API_KEY>"成功响应可能在 result_url、video_url、url、output.url、output[].url 或 content.video_url 中返回结果地址。请直接使用接口实际返回的完整 URL；它可能是经过批准的直达媒体地址，也可能是 MoonApiX 管理的媒体地址。不要自行拼接、替换域名或删除签名参数。
只有成功响应没有提供可用结果 URL 时，才使用兼容内容接口兜底下载：
bash
curl -L https://moonapix.com/v1/videos/<TASK_ID>/content \
-H "Authorization: Bearer <MOONAPIX_API_KEY>" \
-o result.mp4pending、submitted、running、failed 和 cancelled 状态都不要读取 URL；失败时请查看响应中的 error。结果 URL 可能带有临时签名和有效期，生成成功后应及时下载或转存到自己的存储。
计费方式
本系列按 Seedance 官方 Token 用量维度计费：视频费用由模型对应的 Token 单价和任务 Token 用量决定。包含视频参考素材的任务按官方“包含视频输入”计费维度处理；不包含视频参考素材的任务按官方“不含视频输入”计费维度处理。当前价格以模型列表、控制台和实际计费记录为准，本文不固定金额。