视频生成接口

视频接口采用异步任务模式。请先在用户中心创建 API Key，并确认 Key 所属分组已开启视频生成及目标模型。

认证与 Base URL

所有请求都必须携带 Bearer API Key：

BASE_URL="https://你的接口域名"
API_KEY="YOUR_MUSKAI_API_KEY"

以下示例的 BASE_URL 是域名根地址，不包含 /v1。如果控制台复制的地址已以 /v1 结尾，请使用 $BASE_URL/videos，不要拼接成 /v1/v1/videos。模型名称以模型列表和模型广场为准。

当前统一创建接口接收 JSON 与远程素材 URL，尚未适配官方 Videos SDK 的 multipart 文件上传。可以使用 curl、Python requests 或客户端的普通 HTTP 请求；不能仅配置 Base URL 就假定所有官方 SDK 视频方法都兼容。

创建任务

POST /v1/videos

curl "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video","prompt":"电影感海边日落","duration":5,"aspect_ratio":"16:9","resolution":"720p"}'

也可使用 POST /v1/video/generations。建议固定使用一个创建路径，重试时保持路径与请求参数一致。stream: true 不支持。

使用显式供应商适配协议的渠道返回统一结构。请同时保存 id 和 idempotency_key；下例仅展示结构，任务 ID 应从实际响应读取：

{"id":"YOUR_TASK_ID","object":"video","status":"queued","model":"grok-imagine-video","idempotency_key":"YOUR_RETURNED_KEY"}

视频模型、比例、分辨率及时长以模型广场当前能力为准；视频通常按秒或按次计费。

请求参数

字段	类型	说明
`model`	string	必填，客户端模型名；无需填写上游供应商模型名。
`prompt`	string	视频描述，建议明确镜头、主体动作与风格。
`duration`	integer	成片秒数，也兼容 `seconds`、`duration_seconds`。正整数，多个时长字段必须一致；建议显式填写。创建接口缺省为 8 秒。
`resolution`	string	如 `480p`、`720p`、`1080p`，必须符合模型与可用渠道能力。缺省取决于供应商协议，建议显式填写。
`aspect_ratio`	string	如 `16:9`、`9:16`；仅使用目标模型支持的比例。
`images`	array	参考图片 URL 列表。元素为字符串或 `{"url":"https://..."}`。
`videos`	array	参考视频 URL 列表，元素格式同图片。
`audio`	array	参考音频 URL 列表，兼容 `audios`。不是生成音轨的开关。
`first_frame` / `end_frame`	string 或 URL 对象	首帧与尾帧，计入参考图总数；仅支持该功能的模型可用。
`contains_real_person`	boolean	真人素材请求请设为 `true`，兼容 `real_person`。用于筛选支持真人的渠道，转发前移除。未填写按普通请求处理，不自动识别提示词或图片。

网关按分辨率、时长、真人标记及参考素材数量筛选账号，供应商切换也遵守相同限制。账号上限并不表示模型必然支持这些功能；实际模型能力仍需确认。首尾帧与 images 合并计数，不要同时提交两套不同的同义参考字段，也不要混用上游 content 素材结构与统一参考字段。

size 可用于尺寸匹配，常用横竖尺寸按短边归一化，如 1280x720 和 720x1280 匹配 720p。2k、4k 不自动视为 1080p、2160p。同时传 size 和 resolution 时二者必须一致。

参考素材示例

以下为参数结构示例，请替换模型名与可由供应商访问的真实 HTTPS 素材地址；各类素材及组合是否支持取决于模型。

{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "保持参考人物外观，镜头缓慢推近",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "contains_real_person": true,
  "images": ["https://your-public-host.example/reference.jpg"],
  "videos": ["https://your-public-host.example/reference.mp4"],
  "audio": ["https://your-public-host.example/reference.mp3"]
}

幂等键与安全重试

未提供 Idempotency-Key 时，服务器生成随机键，并通过响应 JSON 的 idempotency_key、响应头 Idempotency-Key 和 X-Idempotency-Key 返回。请将键与创建路径、原请求体、任务 ID 一起保存。

需要重试时，使用同一个 API Key、同一个创建路径、相同参数和原幂等键。已完成的请求重放会返回 X-Idempotency-Replayed: true，复用原结果，不再次生成或计费。

curl "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_RETURNED_KEY" \
  -d '{"model":"grok-imagine-video","prompt":"电影感海边日落","duration":5,"aspect_ratio":"16:9","resolution":"720p"}'

相同键对应不同参数会返回 409；原请求仍在处理或提交结果待核对时也可能返回 409，请读取错误信息，不要直接改键重建。
创建超时、网络断开、408 或 5xx 可能意味着上游已经受理。系统不会在受理结果未知时自动换供应商再创建；已有任务 ID 时继续查询，没有 ID 时联系运营核对。
如果首次响应到达前连接就断开，客户端可能还没拿到服务器生成的键。需要可靠自动重试的客户端应在首次请求前生成并持久化自己的唯一键，通过请求头提交。重试不能每次换随机键。
当前幂等与显式协议任务记录保留 7 天，这不是永久任务存储承诺。不要用一个键创建多个视频。

旧的“OpenAI 透传”渠道可能保留 task_id / request_id 等上游响应及原缓存绑定方式，不具备显式协议的全部持久化能力。新接入建议由管理员选择明确的供应商协议，详见视频渠道配置与监控。

查询任务状态

GET /v1/videos/{id}

TASK_ID="YOUR_TASK_ID"
curl "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

显式适配协议的常用状态为 queued、in_progress、completed、failed。in_progress 包含上游的 running / processing；旧透传渠道也可能保留这些原始值。completed（兼容 done、success、succeeded）表示已完成，failed、cancelled、expired 表示任务结束。失败时读取 error，不要继续下载。

建议轮询间隔 3–10 秒，使用退避并设置总等待上限，例如 10 分钟；生成耗时取决于模型与排队情况。单次 GET 超时后可再次 GET，不要重新 POST 创建。查询继续使用创建时的 API Key。显式协议任务固定到原供应商，查询不会重新负载分配。

下载视频成品

完成后使用：GET /v1/videos/{id}/content。

curl "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  --output result.mp4

该地址受 API Key 保护。直接将 URL 粘贴到浏览器地址栏不会自动携带 Authorization，会返回 API_KEY_REQUIRED；请使用上述 curl 或普通 HTTP 客户端请求，或在网页中点击下载按钮（网页会先携带 Key 获取 Blob）。成品缓存最长 24 小时，建议完成后立即保存。

部分响应可能包含 content_url 等结果字段。客户集成优先使用统一 /content 路径，避免依赖供应商临时链接；下载可用性仍取决于原供应商文件保留时间。不要把 API Key 暴露在 URL 查询参数中。

常见问题

现象	处理方法
JSON 解析错误 / multipart 不支持	使用 `Content-Type: application/json` 与远程素材 URL。
没有可用账号	核对分组、模型、分辨率、时长、真人标记和素材数量，联系管理员检查渠道能力与健康状态。
创建返回 409	区分参数冲突与原请求处理中；保留原键和参数，避免重复生成。
创建超时但可能已扣上游费用	有任务 ID 就轮询；没有 ID 保留幂等键与请求 ID，交由运营核对。
下载返回鉴权错误或文件不可用	携带创建时的 Bearer Key；确认任务完成并及时下载。

排查时提供请求时间、模型、路径、任务 ID、幂等键、响应 X-Request-ID 和安全的错误信息。不要提供完整 API Key，也不要公开敏感素材链接。

认证与 Base URL​

创建任务​

请求参数​

参考素材示例​

幂等键与安全重试​

查询任务状态​

下载视频成品​

常见问题​