Appearance
视频生成
MoonApiX 视频接口用于创建文生视频、图生视频和带参考素材的视频任务。视频通常采用异步处理：提交任务后先得到任务 ID，再通过查询接口或回调获取最终状态和结果。
本页只介绍所有视频模型都适用的调用流程和字段约定。模型是否支持某种素材、角色、比例、分辨率、时长或音频控制，请以对应模型详情页和视频模型矩阵为准。
基本流程
- 从模型列表或模型详情页选择一个当前可用的视频模型。
- 确认该模型支持的输入方式、素材数量、角色、比例、分辨率和时长。
- 准备任务素材。正式业务优先使用客户自有的稳定公网 URL；需要复用或模型明确要求素材引用时，再调用素材接口。
- 调用
POST /v1/videos创建任务。 - 保存返回的
id或task_id，通过GET /v1/tasks/{task_id}查询。 - 只有当
status为succeeded且没有error时，才读取结果地址并保存到业务系统。
统一创建入口
http
POST /v1/videos兼容入口：
http
POST /v1/video/generationsPOST /v1/videos 是统一的视频任务创建入口，但不同模型的字段和能力并不完全相同。客户端只提交公开的规范字段；模型专用字段、素材角色转换和模型差异由服务端按模型详情处理。
文生视频
没有参考素材时，提交模型、提示词和模型支持的生成参数：
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[]，并通过 media_type 和 role 说明素材类型与用途：
json
{
"model": "your-video-model",
"prompt": "Animate the product with a slow camera movement.",
"references": [
{
"media_type": "image",
"role": "first_frame",
"url": "https://example.com/product.png"
}
],
"duration": 5,
"aspect_ratio": "1:1"
}多素材输入
对支持多素材的模型，可以在同一个 references[] 中提交图片、视频和音频。每个条目都应明确标注 media_type、role 和素材地址：
json
{
"model": "your-video-model",
"prompt": "Keep the subject appearance from the image and follow the motion in the video.",
"references": [
{
"media_type": "image",
"role": "reference_image",
"url": "https://example.com/subject.png",
"alias": "subject"
},
{
"media_type": "video",
"role": "reference_video",
"url": "https://example.com/motion.mp4",
"alias": "motion"
},
{
"media_type": "audio",
"role": "audio",
"url": "https://example.com/music.mp3",
"alias": "music"
}
],
"duration": 5,
"aspect_ratio": "16:9"
}references[].alias 在同一请求内应唯一且不包含 @。只有模型详情页明确支持时，才在提示词中使用 @alias 引用素材。first_frame、last_frame、reference_image、reference_video 和 audio 等角色不能仅凭文件类型推断，必须按照模型页面的字段说明提交。
输入素材
公网 URL
公网素材必须满足以下条件：
- 无需登录或额外鉴权请求头即可访问。
- 在任务创建和执行期间保持有效，不使用会快速过期的临时签名地址。
- 响应的
Content-Type与声明的媒体类型一致。 - 文件大小、分辨率、时长和总素材数量符合所选模型限制。
图片、视频和音频都应在提交前完成可访问性检查。任一素材无法确认可抓取时，应先修复或更换素材，不要在请求中混用过期地址。
references[] 与兼容字段
支持通用素材协议的模型推荐使用 references[]：
| 字段 | 用途 |
|---|---|
media_type | image、video 或 audio 等素材类型。 |
role | 首帧、尾帧、普通参考、参考视频或音频等用途，具体取值以模型页为准。 |
url | 客户自有公网素材地址，或模型明确支持的素材引用地址。 |
alias | 可选的提示词引用别名，同一请求内应唯一。 |
images[]、videos[]、audios[]、content[]、image_url、video_url 和 audio_url 等字段继续兼容，但是否可用、字段优先级和结构以模型详情页为准。不要把某个模型的字段直接复制到另一个模型。
素材引用
目标模型明确要求素材 ID 或需要长期复用时，可先调用素材接口，再在视频请求中填写返回的素材引用。素材上传、认证和有效期规则见素材接口及目标模型页面；不要假设所有模型都接受同一种素材引用。
常用参数
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 当前可用的视频模型 ID。 |
prompt | string | 对主体、场景、动作、镜头和风格的描述。 |
references | array | 推荐的多素材输入数组，能力和数量以模型页为准。 |
images / videos / audios | array | 按媒体类型拆分的兼容输入字段。 |
duration / seconds | number / string | 目标时长或兼容时长字段，以模型支持范围为准。 |
aspect_ratio / ratio | string | 画幅比例，以模型支持范围为准。 |
resolution | string | 分辨率，以模型支持范围为准。 |
generate_audio | boolean | 仅在模型详情页明确支持时使用。 |
metadata | object | 模型支持的扩展参数。 |
callback_url | string | 可选的 HTTPS 回调地址。 |
请求创建成功不代表视频已经生成完成。请以任务查询响应中的状态和错误字段为准，不要仅根据 HTTP 成功或任务 ID 判断生成成功。
查询任务
bash
curl https://moonapix.com/v1/tasks/task_01HX... \
-H "Authorization: Bearer <MOONAPIX_API_KEY>"常见状态：
| 状态 | 说明 |
|---|---|
pending | 系统准备中。 |
submitted | 已提交，等待处理。 |
running | 正在生成。 |
succeeded | 已完成，可读取结果。 |
failed | 任务失败，应检查 error。 |
cancelled | 任务已取消。 |
客户端应采用递增间隔轮询，并在达到业务超时时间后停止轮询。回调和轮询可以同时使用，但应以同一个任务 ID 去重处理。
结果与下载
只有在 status=succeeded 且 error 为空时，才读取 output、url、video_url 或 result_url 等结果字段。结果地址可能位于数组、对象或元数据中，客户端应按实际响应结构解析并保存完整地址。
也可以在任务成功后调用：
http
GET /v1/videos/{task_id}/content该入口用于结果下载兜底。请不要在任务未完成或失败时调用，也不要把结果地址存在当作成功条件。下载时应遵循响应中的重定向，并在业务侧按需转存到自己的存储。
取消任务
未完成的视频任务可以调用取消接口：
bash
curl -X POST https://moonapix.com/v1/videos/task_01HX.../cancel \
-H "Authorization: Bearer <MOONAPIX_API_KEY>"取消是否能停止正在执行的模型任务，以响应中的 remote_cancel 和模型能力为准。取消与退款是两个相关但独立的处理步骤，客户端应检查最终状态和退款字段，不要重复发起取消请求。
排障建议
- 创建失败：记录请求 ID、任务 ID（如已返回）、模型 ID 和安全的错误摘要；先检查模型字段和素材可访问性。
- 长时间未完成：继续查询同一任务，不要因为客户端超时就重复创建任务。
- 任务失败：查看
error和任务链摘要，区分创建、轮询、素材准备和结果下载阶段。 - 结果不可下载：保留任务响应和 HTTP 状态，优先重试下载或使用
/content兜底，不要重新生成。 - 计费疑问：以任务状态、扣费记录和退款记录为准，不能仅根据前端显示或结果 URL 判断。
提示词建议保持简单明确：说明主体、动作、环境和镜头；参考素材的保留要求写在提示词中；避免一次请求中混入模型页面未声明的角色或控制字段。