MoonApiX Docs

Appearance

创建视频任务 ​

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

方法与路径 ​

http
POST /v1/videos

兼容入口：

http
POST /v1/video/generations

标准请求 ​

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

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

文生视频 ​

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

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视频描述。建议包含主体、场景、镜头、动作和风格。
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 时会按媒体类型兼容为参考素材，但需要首帧、尾帧、参考图绑定音频等特定用途时必须显式填写。

响应示例 ​

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 排查时使用。
原始请求体便于重试、对比和定位字段差异。

相关页面 ​