MoonApiX Docs

简体中文

English

简体中文

English

外观

创建视频任务 ​

视频创建接口用于提交文生视频、图生视频和参考素材视频任务。任务提交成功后会返回 id 或 task_id，需要通过查询接口获取最终结果。

方法与路径 ​

http
POST /v1/videos

兼容入口：

http
POST /v1/video/generations

标准请求 ​

POST /v1/videos 是统一的视频任务创建入口。不同模型的参数、素材类型、数量和时长边界可能不同；提交前请先打开对应的模型详情页确认能力。通用请求只约定任务字段和素材表达方式，不在本页维护模型清单。

对支持通用素材协议的模型，推荐使用 references[]：用 media_type 标明素材类型，用 role 标注用途，用 url 或模型支持的素材引用地址提供内容。images[]、videos[]、audios[] 以及历史字段仍可按模型页面说明兼容使用。

火山引擎官方参数兼容 ​

SH 系列 seedance-2.0-sh、seedance-2.0-sh-fast、seedance-2.0-sh-mini、seedance-2.5-sh 支持 /v1/videos 的 prompt / references[] / aspect_ratio / size，以及 /api/v3/contents/generations/tasks 的 content[] / ratio / resolution。同次请求选择一种素材表达；model 使用 SH 公开模型名。参数优先级为顶层 > input > metadata，显式 generate_audio=false 会保留；kwargs 仅接受 generate_audio、draft、draft_task_id、off_peak，同层直接字段与对应 kwargs 字段冲突时报错。SH 的 callback_url 仅用于 /api/v3/contents/generations/tasks，由 MoonApiX 处理；/v1/videos 不接受，回调交付尚未实测。SH 不支持 seed、watermark 等未列明的官方高级参数，显式传入 0、false 或 null 也会校验。时长、参考素材和 2.5 草稿边界见 SH 系列。

NT 系列 seedance-2.0-nt、seedance-2.0-nt-fast、seedance-2.0-nt-mini、seedance-2.5-nt 支持 /v1/videos 和 /api/v3/contents/generations/tasks，可使用官方形状的 content[]、ratio、resolution、duration、generate_audio、watermark。两种入口均使用 NT 公开模型名和 MoonApiX API Key；2.0 标准版和 2.5 支持 720P/1080P，Fast/Mini 仅支持 720P，Mini 支持 4 - 15 秒，2.5 严格首尾帧保持输入比例。NT 请使用轮询；完整示例及认证素材限制见 NT 系列，不要套用其他系列的回调或高级参数承诺。

seedance-2.0-sz、seedance-2.0-sz-fast、seedance-2.0-sz-mini、 seedance-2.5-sz、seedance-2.5-cl、seedance-2.0-cl-b-fast 和 seedance-2.0-cl-b-mini 在 /v1/videos 中兼容火山引擎官方形状的 content[]、ratio、 resolution、duration、generate_audio、watermark、seed、 callback_url 等字段。references[] 与这些字段是两种输入表达方式；同一请求 不要同时提交 content 和 references。

如果客户端必须保留火山引擎官方请求路径，可使用：

http
POST /api/v3/contents/generations/tasks

该入口仍使用 MoonApiX 公共模型 ID（例如 seedance-2.0-sz、seedance-2.0-sz-fast、 seedance-2.0-sz-mini、seedance-2.5-sz、seedance-2.5-cl、seedance-2.0-cl-b-fast 和 seedance-2.0-cl-b-mini）。 客户端只需替换请求路径，继续使用 MoonApiX API Key，model 仍填写本页列出的 MoonApiX 公共模型 ID。两种入口共享任务 查询、状态和结果处理规则。

seedance-2.5-cl 的字段对应关系和完整 content[] 示例见 官方兼容参数。兼容请求形状不代表支持官方所有参数，具体取值以模型页为准；两种写法中的 Asset:// 都必须已按本模型准备完成，解析失败直接报错，不回退为公网 URL。

CL-B 的官方形状混合素材请求要求每个媒体条目提供唯一 alias，用于保持提示词中的素材绑定语义。字段和能力说明见 CL-B 系列页面。

火山引擎官方字段与 MoonApiX 字段的对应关系、SZ 各型号边界和冲突规则请参阅 seedance-2.0-sz / seedance-2.5-sz。

文生视频 ​

没有参考素材时，只需提交模型要求的提示词和生成参数：

json
{
  "model": "your-video-model",
  "prompt": "A cinematic product shot with a slow camera push-in and clean studio light.",
  "duration": 5,
  "aspect_ratio": "16:9"
}

图生视频 ​

图片可以通过 references[] 传入，并使用 role 指定为首帧、尾帧或普通参考图。具体角色是否可用，以模型详情页为准：

json
{
  "model": "your-video-model",
  "prompt": "Animate the product with a slow camera movement.",
  "references": [
    {
      "media_type": "image",
      "role": "reference_image",
      "url": "https://example.com/product.png",
      "alias": "product"
    }
  ],
  "duration": 5,
  "aspect_ratio": "1:1"
}

多素材输入 ​

图片、视频和音频可以放在同一个 references[] 数组中。音频是否支持单独提交、每种素材的数量上限以及角色名称，均由所选模型决定：

json
{
  "model": "your-video-model",
  "prompt": "Create a video using @hero and @music as references.",
  "references": [
    {
      "media_type": "image",
      "role": "reference_image",
      "url": "https://example.com/hero.jpg",
      "alias": "hero"
    },
    {
      "media_type": "audio",
      "role": "reference_audio",
      "url": "https://example.com/music.mp3",
      "alias": "music"
    }
  ],
  "duration": 5
}

如果模型尚未覆盖通用素材协议，请完全按该模型页面的字段和示例提交，不要仅凭媒体类型推断支持范围。

bash
curl https://moonapix.com/v1/videos \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "prompt": "A cinematic product shot of @product, slow camera push-in, clean studio light.",
    "references": [
      {
        "media_type": "image",
        "role": "reference_image",
        "url": "https://example.com/product.png",
        "alias": "product"
      }
    ],
    "duration": 14,
    "aspect_ratio": "16:9",
    "callback_url": "https://example.com/moonapix/webhook"
  }'

常用参数 ​

字段类型说明
modelstring视频模型名。
promptstring视频描述。建议包含主体、场景、镜头、动作和风格。
return_last_frameboolean可选。支持该能力的模型可设为 true，成功查询时读取 content.last_frame_url。已验证 seedance-2.5-cl，其他模型以各自页面为准；这不是输入尾帧参考图。
referencesarray可选。新接入复杂素材的推荐数组。条目格式为 { "media_type": "image", "role": "reference_image", "url": "...", "alias": "hero" }。
image / image_urlstring可选。单张源图片 URL；兼容旧写法。是否支持由模型页面说明。
imagesarray可选。图片 URL 或素材引用数组。是否支持首帧、尾帧或参考图角色，以模型页面为准。
reference_image_url / reference_image_urlsstring / array可选。参考图 URL 或素材引用。
input_referencestring可选。单张参考图或首帧图；仅适用于支持该字段的模型。
first_frame_url / last_frame_urlstring可选。首帧图和尾帧图；是否支持及具体格式以模型页面为准。
video / video_urlstring可选。参考视频或待延展视频 URL；兼容旧写法。是否支持由模型页面说明。
reference_video_url / reference_video_urlsstring / array可选。参考视频 URL 或素材引用。部分模型不支持视频参考，请以对应模型页为准。
videosarray可选。视频素材数组。是否支持视频参考及角色，以模型页面为准。
audio / audio_urlstring可选。参考音频 URL 或素材引用；兼容旧写法。是否允许单独提交，以模型页面为准。
audiosarray可选。音频素材数组。是否支持及数量限制，以模型页面为准。
contentarray可选。多媒体内容数组，支持 text、image_url、video_url、audio_url 条目。
durationinteger可选。视频时长，具体取值以模型支持范围为准。
secondsstring可选。部分兼容模型使用该字段表示时长。
aspect_ratio / ratiostring可选。视频比例，例如 16:9、9:16、1:1。
resolutionstring可选。分辨率，例如 480p、720p、1080p。
video_configobject可选。兼容格式，常见字段为 aspect_ratio、resolution_name。
generate_audioboolean可选。控制是否生成音频；是否支持、默认值和可用取值，以模型页面为准。
generateAudioboolean可选兼容字段，语义与 generate_audio 相同；新接入优先使用 generate_audio。
metadataobject可选。扩展参数；也可放入 content、duration、seconds、resolution 等模型参数。
callback_urlstring可选。任务完成后接收回调的 HTTPS 地址。

references[] 条目的常见结构：

字段类型说明
media_typestring素材类型。常见值为 image、video、audio、music。
rolestring素材用途。常见值为 first_frame、last_frame、reference_image、reference_video、reference_audio、background_music、voice_reference、style_reference、character_reference。音频参考通常需要同时提供图片或视频参考。
urlstring公网 URL、MoonApiX 托管 URL，或模型明确支持时的 Asset://asset_xxx。
aliasstring可选。素材别名，不包含 @，并且同一请求内应唯一；在 prompt 中用 @alias 指代素材。省略时会按媒体类型依次生成 图片1、视频1、音频1 等内置顺序别名。
asset_id / asset_refstring可选。MoonApiX 素材 ID 或素材引用。是否可直接生成取决于模型支持。

内置顺序别名兼容 @图片1 与 @图片 1 两种写法，视频N、音频N 同理；数字后可以直接继续正文，例如 @图片1保持人物外观。为便于阅读，仍建议在别名后加空格或标点。自定义别名必须与后续正文分隔，例如写成 @主体 走到龙椅旁，不要写成 @主体走到龙椅旁。

别名无法匹配素材时返回 invalid_reference_alias；同一别名绑定多个不同素材时返回 duplicate_reference_alias。别名只负责把提示词与参考素材绑定，不保证多个参考人物在成片中一定保持独立身份；多人任务仍需在提示词中明确人物、位置、服装和动作。

content[] 条目的常见结构：

字段类型说明
typestringtext、image_url、video_url 或 audio_url。
textstring文本内容。视频任务通常直接使用顶层 prompt。
image_url.urlstring图片 URL 或素材引用。
video_url.urlstring视频 URL 或素材引用。
audio_url.urlstring音频 URL 或素材引用。
asset_id / asset-idstring可选。MoonApiX 素材 ID。
asset_urlstring可选。素材引用地址，例如 Asset://asset_xxx。
rolestring媒体条目建议填写。常见值为 reference_image、first_frame、last_frame、reference_video、reference_audio；图片、视频或音频条目缺少 role 时会按媒体类型兼容为参考素材，但需要首帧、尾帧、参考图绑定音频等特定用途时必须显式填写。

获取生成结果尾帧 ​

使用 seedance-2.5-cl 时，在创建请求顶层设置 return_last_frame=true：

json
{
  "model": "seedance-2.5-cl",
  "prompt": "清晨海边，镜头平稳向前推进。",
  "duration": 4,
  "aspect_ratio": "16:9",
  "size": "480p",
  "return_last_frame": true
}

任务成功后，通过 GET /v1/videos/{task_id} 或官方兼容查询入口读取可选的 content.last_frame_url。默认响应即可，不需要开启 raw 模式。这个字段是生成视频的尾帧图片地址；输入素材中的 last_frame_url 或 role=last_frame 则是尾帧参考图，两者用途不同。

图片格式以下载响应的 Content-Type 为准，不固定为 PNG。字段可能省略，地址也不保证永久有效；完整响应示例和保存建议见 查询视频任务。

响应示例 ​

json
{
  "id": "task_01HX...",
  "object": "task",
  "status": "submitted",
  "model": "your-video-model",
  "created_at": 1710000000
}

兼容视频接口在任务成功后通常会把最终视频地址放在多个字段中，便于不同 SDK 读取。客户端应先判断 status，只有 succeeded 时才读取 URL；pending、submitted、running、failed 或 cancelled 都不要读取 URL，failed 时请读取 error：

json
{
  "id": "task_01HX...",
  "task_id": "task_01HX...",
  "object": "video",
  "model": "your-video-model",
  "status": "succeeded",
  "url": "https://example.com/result.mp4",
  "video_url": "https://example.com/result.mp4",
  "output": {
    "url": "https://example.com/result.mp4"
  },
  "metadata": {
    "url": "https://example.com/result.mp4"
  }
}

提交后要保存 ​

字段用途
id / task_id后续查询任务状态和结果。
model复盘参数、核对计费和排查问题。
trace_id / request_id联系 MoonApiX 排查时使用。
原始请求体便于重试、对比和定位字段差异。

相关页面 ​