火山方舟原生协议

Mozia API 提供火山方舟原生格式的视频生成接口，采用异步任务模式：创建任务、保存任务 ID、轮询状态、获取视频结果。本文覆盖视频任务的创建、查询、列表和取消/删除。

接入地址与鉴权

平台统一的 API 基础地址：

https://mzsjai.com/v1

火山方舟原生视频使用同一域名下的 /api/v3 路径。配置原生客户端时，将基础地址末尾的 /v1 替换为 /api/v3：

https://mzsjai.com/api/v3

创建任务的完整地址为 https://mzsjai.com/api/v3/contents/generations/tasks。下表中的路径从域名根目录开始，不再拼接到 /v1 后面。

所有请求使用 Mozia API Key 鉴权，创建任务时提交 JSON：

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

在控制台选择支持 volcengine-video endpoint 的模型，使用该模型对外显示的完整模型 ID。模型可用性、素材限制、参数范围和价格以该模型的配置为准；拥有某个模型的调用权限，不代表它一定支持本协议。

API Key 应保存在服务端。下文的 <YOUR_API_KEY>、<MODEL_ID>、cgt-example 和素材地址均为占位示例，调用前请替换。

接口一览

方法	路径	作用
POST	/api/v3/contents/generations/tasks	创建视频生成任务
GET	/api/v3/contents/generations/tasks/{task_id}	查询单个任务
GET	/api/v3/contents/generations/tasks	查询任务列表
DELETE	/api/v3/contents/generations/tasks/{task_id}	取消排队任务或删除已结束任务

本协议通过 content.video_url 提供生成结果，响应保留原生结构。

快速开始

1. 创建任务

设置调用参数：

export MOZIA_BASE_URL='https://mzsjai.com/v1'
export MOZIA_ARK_BASE_URL="${MOZIA_BASE_URL%/v1}/api/v3"
export MOZIA_API_KEY='<YOUR_API_KEY>'
export MOZIA_MODEL='<MODEL_ID>'

提交文生视频请求：

curl --fail-with-body \
  "${MOZIA_ARK_BASE_URL}/contents/generations/tasks" \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "${MOZIA_MODEL}",
  "content": [
    {"type": "text", "text": "日落时分的海边，镜头平稳向前推进，电影质感"}
  ],
  "duration": 5,
  "ratio": "16:9"
}
JSON

成功时返回 HTTP 200，响应示例：

{"id": "cgt-example"}

返回成功表示任务已提交，视频尚未生成完成。请完整保存 id，将其作为后续路径中的 task_id；不要修改前缀或自行生成替代 ID。

2. 查询状态

export MOZIA_TASK_ID='cgt-example'

curl --fail-with-body \
  "${MOZIA_ARK_BASE_URL}/contents/generations/tasks/${MOZIA_TASK_ID}" \
  -H "Authorization: Bearer ${MOZIA_API_KEY}"

建议每 5～10 秒查询一次，直到状态变为 succeeded、failed、cancelled 或 expired。达到客户端等待上限后，可以保存任务 ID，稍后继续查询。

3. 保存结果

当 status 为 succeeded 时，读取 content.video_url 并下载：

# 将此值替换为查询响应中的 content.video_url
export VIDEO_URL='https://example.com/result.mp4'
curl --fail-with-body -L "${VIDEO_URL}" -o result.mp4

下载结果 URL 时无需附带 Mozia API Key。结果地址可能有有效期，请在任务成功后及时保存文件。

创建任务参数

POST /api/v3/contents/generations/tasks

请求体

字段	类型	必填	说明
model	string	是	支持本协议且当前 API Key 可调用的模型 ID
content	array	是	非空数组，包含文本、图片、视频、音频或样片引用
duration	integer	否	生成时长，单位为秒；仅在模型及其计费方式支持自动时长时使用 -1
resolution	string	否	清晰度，例如 720p；可选值以模型为准
ratio	string	否	宽高比，例如 16:9、9:16、1:1
seed	integer	否	随机种子，取值范围以模型为准
generate_audio	boolean	否	是否生成音频，需模型支持
watermark	boolean	否	是否添加水印，需模型支持
camera_fixed	boolean	否	是否固定镜头，需模型支持
return_last_frame	boolean	否	是否返回尾帧，需模型支持
callback_url	string	否	任务状态通知地址；是否回调及通知格式由模型服务决定，仍可使用查询接口确认状态
service_tier	string	否	服务等级，支持时使用 default 或 flex
execution_expires_after	integer	否	任务执行过期时间设置，单位为秒；可用范围以模型为准
draft	boolean	否	是否生成样片，需模型支持
frames	integer	否	指定帧数，需模型支持；与时长的组合限制以模型为准
tools	array	否	模型支持的原生工具配置

可选字段省略后由模型服务决定默认行为。接口保留显式的 false、0 和其他 JSON 字段；省略 duration 不会由本协议自动补成 5 秒。平台为所选模型配置的参数规则仍会生效，例如固定分辨率模型可以限定 resolution。

提示词写在 content 的文本项中。使用原生接口时，应直接提交模型支持的原生字段；接口不会将顶层 prompt、images、size 或 metadata 自动转换为对应的原生参数。

content 格式

每一项都必须有非空的 type。素材地址必须能被模型服务访问，推荐使用公网 HTTPS URL。

type	内容字段	role	用途
text	text	不需要	文本提示词
image_url	image_url.url	first_frame	首帧图片
image_url	image_url.url	last_frame	尾帧图片
image_url	image_url.url	reference_image	参考图片
video_url	video_url.url	reference_video	参考视频
audio_url	audio_url.url	reference_audio	参考音频
draft_task	draft_task.id	不需要	引用已有样片任务

素材类型、数量、大小、时长以及角色组合限制由所选模型决定。支持文本生成的模型不一定支持参考视频、参考音频或样片。

图生视频示例

以下为创建任务的 JSON 请求体：

{
  "model": "<MODEL_ID>",
  "content": [
    {"type": "text", "text": "人物自然转身，向镜头微笑，保持外观一致"},
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {"url": "https://example.com/start.jpg"}
    }
  ],
  "duration": 5,
  "ratio": "16:9",
  "generate_audio": false
}

需要首尾帧时，可在模型支持的情况下增加 role: "last_frame" 的图片项。首尾帧和参考素材能否混用，以模型限制为准。

参考视频示例

{
  "model": "<MODEL_ID>",
  "content": [
    {"type": "text", "text": "参考视频中的镜头运动，生成一段海边广告片"},
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {"url": "https://example.com/reference.mp4"}
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}

参考图片和参考音频采用相同的嵌套 URL 结构，分别使用 image_url / reference_image 和 audio_url / reference_audio。

样片引用

仅对支持样片的模型使用。引用的任务必须由当前账号通过本原生接口创建；每次请求只允许引用一个非空的 draft_task.id：

{
  "model": "<MODEL_ID>",
  "content": [
    {"type": "draft_task", "draft_task": {"id": "cgt-draft-example"}}
  ]
}

使用原样片对应的模型，并遵循该模型的样片转正式视频参数要求。

查询任务

GET /api/v3/contents/generations/tasks/{task_id}

task_id 为创建响应中的 id。查询成功返回 HTTP 200 和原生任务对象。

任务状态

status	含义	是否结束
queued	排队中	否
running	生成中	否
succeeded	生成成功	是
failed	生成失败，查看任务对象中的 error	是
cancelled	已取消	是
expired	已过期	是

HTTP 200 表示查询成功，不代表视频生成成功，应继续判断 status。

成功响应示例

{
  "id": "cgt-example",
  "model": "example-model",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/result.mp4",
    "last_frame_url": "https://example.com/last-frame.jpg"
  },
  "created_at": 1788840000,
  "updated_at": 1788840060,
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "usage": {
    "completion_tokens": 12345,
    "total_tokens": 12345
  }
}

以上为结构示例，字段是否出现取决于模型和任务状态：

字段	说明
id	原生任务 ID
model	模型服务返回的模型标识，可能与提交时的对外模型名不同
content.video_url	生成成功后的结果地址
content.last_frame_url	模型支持且实际返回时的尾帧地址
created_at、updated_at	原生时间戳，单位为秒
usage	模型服务返回的用量；未返回时不补零，也不据此推断任务免费
error	任务失败时的错误信息，通常包含 code 和 message

客户端应容忍可选字段缺失和新增字段。不要依赖 progress、object 或 task_id 一定出现在原生响应中。

失败任务示例

{
  "id": "cgt-example",
  "status": "failed",
  "error": {
    "code": "example_task_error",
    "message": "视频生成失败"
  }
}

这里的 error 属于已创建任务的执行结果；请求本身失败时的 HTTP 错误格式见下文。

查询任务列表

GET /api/v3/contents/generations/tasks

查询参数	类型	默认值	说明
page_num	integer	1	页码，范围 1～500
page_size	integer	20	每页数量，范围 1～500
filter.model	string	不筛选	使用查询响应中的 model 值筛选
filter.status	string	不筛选	queued、running、succeeded、failed、cancelled、expired
filter.service_tier	string	不筛选	default 或 flex
filter.task_ids	string，可重复	不筛选	多个任务 ID 使用重复的同名参数

查询成功任务：

curl --fail-with-body --get \
  "${MOZIA_ARK_BASE_URL}/contents/generations/tasks" \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  --data-urlencode 'page_num=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'filter.status=succeeded'

按多个 ID 筛选时，使用 filter.task_ids=cgt-first&filter.task_ids=cgt-second，不要将多个 ID 合并成逗号分隔的字符串。

响应示例：

{
  "items": [
    {"id": "cgt-example", "status": "queued", "created_at": 1788840000}
  ],
  "total": 1
}

items 中每项为原生任务对象，按创建时间倒序排列。total 是当前账号可见、满足筛选条件的任务总数，不是当前页数量；没有结果或页码超出结果范围时，items 为 []。

列表仅包含当前账号在最近七天内通过本原生接口创建且仍可查询的任务，并遵守当前 API Key 的模型权限。其他账号的任务、通过其他视频协议创建的任务以及已删除或不可用的任务不会被导入列表。任务归属按账号判断，不要求查询时使用与创建时完全相同的 API Key。

取消或删除任务

DELETE /api/v3/contents/generations/tasks/{task_id}

curl --fail-with-body --request DELETE \
  "${MOZIA_ARK_BASE_URL}/contents/generations/tasks/${MOZIA_TASK_ID}" \
  -H "Authorization: Bearer ${MOZIA_API_KEY}"

• 排队中的任务可申请取消；任务可能在请求期间进入生成状态，是否接受取消以接口结果为准。
• 正在生成的任务能否取消由模型服务决定，不应假设可以强制中断。
• 已结束的任务可申请删除。需要视频文件时，应先下载并保存结果。

成功时返回 HTTP 200，响应体保留模型服务的返回结果，可能为 {} 或空内容。不要依赖删除响应包含任务 ID 或完整任务对象。

删除后再次查询可能返回 404。删除任务不会删除平台的账单和用量记录，也不表示已消费费用会退款。

错误处理与计费

HTTP 请求失败时使用 error 对象，例如任务不存在：

{
  "error": {
    "code": "NotFound",
    "message": "task not found"
  }
}

模型服务的标准 error 对象和 HTTP 错误状态会保留；平台鉴权、参数校验、路由和网络错误也使用 error 对象，错误码可能不同。type、param 等附加字段不保证始终存在。

HTTP 状态	常见原因	处理方式
400	缺少必填字段、参数类型或组合不受支持	修改请求后再提交
401	API Key 缺失或无效	检查鉴权头和密钥状态
403	没有模型或任务访问权限	检查账号与 API Key 权限
404	任务不存在、不属于当前账号或已不可用	核对创建时保存的任务 ID；不要将其视为退款凭据
429	请求频率或并发受限	降低频率并延迟重试
5xx	服务暂时不可用或任务服务异常	查询请求可有限退避重试；创建请求先确认是否已生成任务

创建任务可能先预扣费用，再按模型的计费规则和实际结果结算。失败、取消或过期需要得到明确的任务终态后处理费用；一次 DELETE 成功、客户端等待超时或一次 404 都不等于退款完成。费用以控制台账单为准，遇到任务已不可查询而费用未明确结算的情况，请携带任务 ID 联系支持。

创建请求发生网络超时后，任务仍可能已提交成功。请先核对任务列表或控制台记录，避免立即重复创建导致重复生成和计费。

与统一视频接口的区别

项目	本文原生协议	统一视频接口
创建路径	/api/v3/contents/generations/tasks	/v1/video/generations
提示词	content[].text	支持顶层 prompt 等统一参数
创建响应	原生对象，例如 {"id":"cgt-example"}	平台统一任务对象
结果地址	content.video_url	按统一接口文档解析
列表与取消/删除	使用本文对应路径	不适用本文路径约定

同一个任务的创建、查询和删除应使用本协议的配套路径。本文的兼容范围是原生视频任务协议；模型能力、账号权限、列表可见范围及平台错误码仍遵循上述说明，不代表所有火山方舟产品接口均已开放。

统一接口的接入方式见视频生成。