MoonApiX Docs

Appearance

Seedance SG 系列 ​

SG 系列提供四个公开模型，支持 MoonApiX 通用视频参数与火山官方兼容参数。两种入口都使用 MoonApiX API Key，model 始终填写下表中的公开模型名。

模型与能力 ​

公开模型分辨率整数时长图片 / 视频 / 音频配置上限
seedance-2.0-sg-mini480P、720P4 - 15 秒9 / 3 / 3，合计 15
seedance-2.0-sg480P、720P4 - 15 秒9 / 3 / 3，合计 15
seedance-2.0-sg-fast480P、720P4 - 15 秒9 / 3 / 3，合计 15
seedance-2.5-sg480P、720P、1080P4 - 30 秒30 / 10 / 10，合计 50

配置允许 duration=-1 自动选择时长；需要确定目标时长时请传整数秒数。比例支持 16:9、9:16、1:1、4:3、3:4、21:9，adaptive 的适用范围取决于生成模式。当前账号可用型号和能力以模型接口与控制台为准。

四个模型均已验证 720P、4 秒、单张 reference_image 的参考图模式；也已验证表中全部分辨率的 4 秒、2 张图片 + 1 段音频 + 1 个视频混合参考，共 9 组型号与分辨率组合。数量上限、自动时长和其他时长不等于均已逐项实测。SG 2.0 标准版当前不开放 1080P，不能套用其他系列标准版的分辨率范围。

参考模式与素材 ​

图片使用 role=reference_image，视频使用 reference_video，音频使用 reference_audio。只有一张参考图时，也必须保留 reference_image；不要改成 first_frame。提示词中的 @图片1 等标记用于描述素材，不能代替结构化 role。

  • 音频必须搭配图片或视频，不能单独提交。
  • 首帧 / 尾帧使用独立模式，不能与多模态参考混用；尾帧必须搭配首帧。需要固定输出比例的参考图请求请使用 reference_image。
  • 素材 URL 使用可匿名下载的 HTTPS 媒体直链，在任务完成前持续有效；不能是登录页面或预览网页。图片、音频和视频仍需满足内容安全及媒体规格要求。
  • 公网图片 URL 可以直接提交，由服务完成所需的素材准备，无需另外提交认证编号。
  • 已有 MoonApiX Asset:// 引用必须属于当前账号且适用于目标模型。待准备、失败或不匹配的认证绑定应先处理；不要复用其他模型的认证编号。下列已验证流程使用公网 URL，独立创建认证素材的操作见上传与素材。

MoonApiX 通用参数 ​

推荐入口为 POST /v1/videos。以下是 2 图 + 1 音频 + 1 视频、1080P、4 秒示例；example.com 地址为占位符，需替换为你有权使用的真实素材直链。

bash
curl https://moonapix.com/v1/videos \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-sg",
    "prompt": "保持 @图片1 与 @图片2 的主体外观，参考 @视频1 的镜头运动，结合 @音频1 的声音氛围。",
    "references": [
      { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-1.png" },
      { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-2.png" },
      { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/reference-audio.wav" },
      { "media_type": "video", "role": "reference_video", "url": "https://example.com/reference-video.mp4" }
    ],
    "size": "1080p",
    "aspect_ratio": "16:9",
    "duration": 4,
    "generate_audio": true
  }'

单图参考时，仅保留第一张图片条目，将提示词改为“参考 @图片1，保持主体外观，镜头平稳推进。”，保留 role=reference_image。选择任一 SG 2.0 型号时，将 model 改为对应公开名，并将 size 改为 480p 或 720p。

官方兼容参数 ​

兼容入口为 POST /api/v3/contents/generations/tasks；POST /v1/videos 也接受同一套官方兼容请求体。单次请求选用一套表达方式，避免同时提交 references[] 与 content[] 或重复提示词。

MoonApiX 通用字段官方兼容字段说明
modelmodel均填写 SG 公开模型名
promptcontent[] 的 type=text 条目文本提示词
references[]content[] 的媒体条目显式保留参考角色
sizeresolution按型号选择分辨率
aspect_ratioratio输出比例
durationduration整数秒数，或支持时使用 -1
generate_audiogenerate_audio布尔值；显式 false 关闭生成音轨

下面与通用参数示例使用相同素材和目标规格：

bash
curl https://moonapix.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-sg",
    "content": [
      { "type": "text", "text": "保持 @图片1 与 @图片2 的主体外观，参考 @视频1 的镜头运动，结合 @音频1 的声音氛围。" },
      { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-1.png" } },
      { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-2.png" } },
      { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/reference-audio.wav" } },
      { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://example.com/reference-video.mp4" } }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 4,
    "generate_audio": true
  }'

官方兼容表示请求字段和路径兼容，不代表所有高级参数、编辑或扩展模式均已验证。常规参考生成按上述示例传参即可。

查询与结果 URL ​

创建响应仅表示任务已受理。保存公开 id 或 task_id，使用同一 API Key 轮询：

bash
curl https://moonapix.com/v1/videos/{task_id} \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

官方兼容查询使用 GET /api/v3/contents/generations/tasks/{task_id}。先检查 status 和 error，排队或运行中继续轮询，失败时处理错误。只有成功终态且无错误时才读取 video_url、url 或官方兼容响应的 content.video_url；不能仅凭 URL 存在判断成功。状态与响应格式详见查询视频任务。

成功结果中的可直接下载媒体 URL 会原样返回，可直接交给客户端使用。请完整保留地址和查询参数，不拼接域名、不删除签名；地址可能有有效期，应及时下载或保存。若响应返回 MoonApiX 内容下载入口，则按接口要求携带 MoonApiX API Key；访问外部媒体直链时不要发送该 Key。

计费与错误 ​

SG 系列按百万输出 Token 计价，最终按 usage.completion_tokens 结算。计费档位区分型号、分辨率，以及是否输入参考视频；generate_audio 开关不等于“是否输入参考视频”。本系列采用官方原价口径，账户实际适用单价请读取控制台与价格接口，文档不固定金额。

提交时可能先预扣，完成后根据实际用量补扣或退还差额。“异步任务退款”也可能是成功任务的预扣差额返还，应结合任务状态、消耗和退款记录查看净扣费。提交失败未创建任务不计费；创建后的失败结算以任务完整计费记录为准。

参数或素材失败时，请读取安全错误说明及可用的 code、param，并保留 MoonApiX 请求 ID 供排障。参考图被按首帧处理时，先检查图片是否明确传入 reference_image，以及是否混用了首尾帧角色。提交失败与已经创建任务后的失败需分别处理，避免重复创建导致额外消耗。

相关页面 ​