Omn 音乐视频对接指南(中文)
本页是 Music Video API 中 Omn 部分的中文版,面向首次对接或从 OneClick 迁移的开发者。字段名、错误码和接口路径保持英文原样;如与英文页不一致,以英文页和 API 参考为准。
- Base URL:
https://api.omnapi.com,请求头带x-api-key。 - 权限(scope):
task:create用于报价、购买和删除;task:read用于读取;task:cancel用于取消。未设置 scope 的 key 拥有全部权限。 - 异步:购买后立即返回视频对象,生成需要若干分钟,歌曲越长、分辨率越高耗时越长。
- 歌曲时长:有效时长 10–600 秒。
选择接入方式
Section titled “选择接入方式”| 方式 | 适合 | 改动 |
|---|---|---|
/api/v2/mv(推荐) | 新接入,或愿意改代码的 OneClick 客户 | 使用本页的资源式接口 |
/api/v1/mv 加 generation.engineVersion: "omn-v1" | 现有 OneClick 代码,想最少改动 | 请求、响应、轮询方式不变,见 Omn on API v1 |
| 由我们为你的 API key 切换默认引擎 | 完全不改代码 | 联系我们;Omn 无法承接的请求在扣费前改走 OneClick(或按你的选择直接报错) |
视频在哪个接口购买,就在哪个接口读取,修改 URL 中的 v1 / v2 不会迁移视频。
按有效成片秒数计费,向上取整;创作模式不影响价格;规划、参考图处理、字幕和超分都已包含。 Omn 不适用客户合同折扣。
| 分辨率 | 积分/秒 | 60 秒视频 |
|---|---|---|
| 480p | 9 | 540 |
| 768p(默认) | 12 | 720 |
| 1080p(AI 超分) | 20 | 1,200 |
| 1440p / 2K(AI 超分) | 48 | 2,880 |
实际金额以报价返回的 price.credits 为准。
- 报价(免费):
POST /api/v2/mv/quotes,提交 spec。服务会下载并校验音频和图片、 测量真实时长,返回价格和过期时间(约 10 分钟)。请求有任何改动都要重新报价。 - 购买:
POST /api/v2/mv/videos,body 为{ "quoteId": "...", "maxCredits": 报价金额 }, 请求头带Idempotency-Key。也可以直接提交{ "spec": {...}, "maxCredits": ... }一步完成。 - 等待:轮询、订阅进度流或接收 webhook(见下文)。
- 下载:状态为
completed后读取GET /api/v2/mv/videos/{id}/file,用返回的签名链接下载 MP4。
export OMNAPI_KEY="your-api-key"
cat > mv-spec.json <<'JSON'{ "source": { "type": "audio_url", "url": "https://example.com/song.mp3", "lyrics": "第一行歌词\n第二行歌词" }, "creative": { "mode": "sing", "brief": "歌手在雨夜的城市街头演唱", "style": "电影感写实,蓝紫色灯光" }, "references": { "performer": { "imageUrl": "https://example.com/singer.png" } }, "output": { "resolution": "768p", "aspectRatio": "9:16" }, "captions": { "mode": "auto", "language": "zh" }}JSONcurl -X POST https://api.omnapi.com/api/v2/mv/quotes \ -H "x-api-key: $OMNAPI_KEY" -H "Content-Type: application/json" \ --data @mv-spec.json -o quote.json
# 只生成一次幂等键并保存;重试时复用同一个键和同一个 bodyuuidgen > mv-key.txtjq '{quoteId: .id, maxCredits: .price.credits}' quote.json > mv-buy.jsoncurl -X POST https://api.omnapi.com/api/v2/mv/videos \ -H "x-api-key: $OMNAPI_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(cat mv-key.txt)" --data @mv-buy.json -o video.json幂等规则:幂等键只生成一次,和请求 body 一起保存。超时、断网或 5xx 时,用同一个键和同一个 body 重试,不会重复扣费;换新键就是一笔新的购买。
视频 id:视频的 id 与 taskId 相同,从购买起不会改变,保存任意一个即可。
请求字段(spec)
Section titled “请求字段(spec)”| 字段 | 说明 |
|---|---|
source.type | audio_url(配 url,公网 HTTPS,MP3/WAV/AAC/M4A,≤ 128 MB)或 suno_clip(配 clipId,你自己的 Suno 片段) |
source.range | 可选,{ startSec, endSec },只使用歌曲的这一段(10–600 秒) |
source.lyrics | 可选,≤ 5,000 字。每行一句,不要加 [Verse] 等段落标签。提供歌词能显著提升故事和字幕的准确度 |
title | 可选,≤ 200 字 |
creative.mode | auto(默认,Omn 自行决定方向和是否出现人物,不演唱)、sing(参考人物演唱原曲,口型同步)、story(叙事)、mood(氛围画面) |
creative.brief | 可选,≤ 3,000 字:画面内容、场景、人物、事件 |
creative.style | 可选,≤ 1,000 字:视觉风格、色调、镜头感 |
creative.storySource | story 模式必填:lyrics(讲歌词的故事)或 brief(讲 brief 的故事,此时 brief 必填);其他模式不能填 |
creative.people | auto(默认)或 none(画面不出现人物,不能与 sing 或 references.performer 同时使用) |
references.performer | { imageUrl, description? },一张人物图(PNG/JPEG/WebP,≤ 10 MB)。sing 必填,是演唱者;其他模式作为主角 |
references.styles / references.locations | 各最多 3 张图片 URL(≤ 12 MB),分别指定风格和场景 |
output.resolution | 480p、768p(默认)、1080p、1440p(2K 的 API 值是 1440p,不接受 2K) |
output.aspectRatio | 21:9、16:9(默认)、3:2、4:3、5:4、1:1、4:5、3:4、2:3、9:16、9:21 |
captions.mode | off(默认)、auto(根据音频自动对时)、provided(使用你的 SRT,配 srtUrl,≤ 4 MB,时间相对于所选片段) |
captions.language | auto、en、zh |
captions.required | true 时字幕失败则整单失败(退款),而不是交付无字幕视频 |
未知字段(包括 engineVersion 之类的引擎选择字段)会返回 400,不会被静默忽略。
1080p 与 2K
Section titled “1080p 与 2K”1080p / 1440p 由 768p 渲染后 AI 超分得到,16:9 时成片为 1920×1080 / 2560×1440,9:16 时宽高互换。
上线前请读取 GET /api/v2/mv/capabilities 的 availableResolutions:只有当前能购买的分辨率才会列出,
超分暂不可用时 1080p / 1440p 不在其中,此时报价会返回 503 且不扣费。
HD 订单不会用低分辨率文件交付:若无法产出 HD 文件或尺寸校验不通过,视频失败,错误码
MV_CENTER_HD_FAILED,全额退款。
三种方式任选其一,返回的 status 一致:
- 轮询:每 15–30 秒读取
GET /api/v2/mv/videos/{id},长歌曲或 HD 可逐步放宽到约 60 秒。 - 进度流(SSE):
GET /api/v2/mv/videos/{id}/events。每个event: video的 data 与GET /api/v2/mv/videos/{id}完全相同,连接时推送一次,之后状态、进度、价格、警告、失败原因或文件链接 变化时推送。视频结束后流关闭;否则约 55 秒断开,客户端重连即可(浏览器EventSource和 SDK 的streamOmnVideo/stream_omn_video会自动重连)。收到event: unavailable时改用轮询。 - Webhook:购买时传
webhookUrl。会收到task.*事件,以及视频结束时的mv.ready或mv.failed;事件体中的videoId即视频 id,viewUrl/finalUrl指向/api/v2/mv/videos/{id}及其/file。事件体示例、签名和重试规则见 Webhook events。 收到 webhook 后请先读取视频再处理,并按X-Webhook-Id去重。
status | 含义 | 下一步 |
|---|---|---|
queued | 已购买,等待开始 | 继续等待 |
generating | 正在生成镜头 | 继续等待;/shots 可查看逐镜头状态 |
delivering | 正在合成并检查成片 | 继续等待 |
completed | 成片就绪 | 读取 /file |
failed | 不会交付 | 看 failure.code;费用会退还 |
cancelled | 已按你的请求取消 | 费用会退还 |
deleted | 已被你删除 | 无可下载内容 |
GET /api/v2/mv/videos/{id}/file 在 completed 前返回 409(details.reason: file_not_ready)。
完成后返回 url(签名链接,约 1 小时有效,过期后重新读取)、实测的 width / height /
durationSec、resolution,以及 retainedUntil:存储文件在此时间之后删除(默认约 14 天),
请在此之前转存到你自己的存储。下载签名链接时不要带 API key。
- 技术失败、质量复检仍不通过(
MV_CENTER_QUALITY_FAILED)、HD 交付失败(MV_CENTER_HD_FAILED)、 演唱者图片中识别不到合适的人物(MV_CENTER_SINGER_UNAVAILABLE)都会使视频失败并全额退款。 failure.retryable表示原样再买一次是否可能成功;再买一次总是需要新报价和新幂等键。- 退款是异步入账的:视频变为
failed/cancelled后,price.refundedCredits可能短暂为 0。 以GET /api/v2/mv/videos/{id}/charges中settlementStatus变为REFUNDED为准。 - 主观上不满意不属于退款理由;成片可能带有审核类警告,发布前请人工查看。
错误体为 { "success": false, "error": { "code", "message", "details" } }。请依据 error.code 和
error.details.reason 判断,不要解析 message 文本。
| 返回 | 是否扣费 | 处理方式 |
|---|---|---|
| 购买时超时、断网或 5xx | 未知 | 用同一个幂等键和 body 重试,直到拿到明确结果 |
400 VALIDATION_ERROR(指出某字段) | 否 | 修正字段,重新报价,使用新键 |
400 VALIDATION_ERROR,quote_expired | 否 | 重新报价,确认价格,使用新键 |
409 CONFLICT,quote_already_used | 已购买 | 不要再买;读取 details.taskId 对应的视频 |
409 CONFLICT,同一个键配了不同 body | 否 | 恢复该键对应的原 body |
409 CONFLICT,同一个键仍在处理中 | 处理中 | 稍等几秒,用同一个键和 body 重试 |
402 INSUFFICIENT_CREDITS | 否 | 充值后用同一个键和 body 重试 |
402 INSUFFICIENT_CREDITS,MAX_CREDITS_EXCEEDED | 否 | 价格高于 maxCredits;确认更高上限(body 改变,需新键)或重新报价 |
422 MV_ENGINE_UNSUPPORTED | 否 | 修改 details.reason 指出的选项后重新报价 |
503 MV_PROVIDER_UNAVAILABLE(capacity_unavailable 等 retryable: true) | 否 | 等待 Retry-After;报价仍有效时用同一个键和 body 重试购买,否则重新报价 |
503 MV_PROVIDER_UNAVAILABLE,retryable: false | 否 | 暂时无法承接此请求,改用 OneClick 或稍后再试 |
429 RATE_LIMITED | 否 | 等待 Retry-After,用同一个键和 body 重试 |
409 CONFLICT,video_in_progress(删除时) | — | 先取消或等待结束,再删除 |
409 CONFLICT(取消时) | 照常扣费 | 视频会继续生成 |
409 CONFLICT,resource_contract_mismatch | — | 该视频是在 /api/v1/mv 购买的,请在那里读取 |
Omn 同时制作的视频数量有限,满载时报价和购买返回 503(capacity_unavailable,Retry-After: 60),
不会接下需要排队数小时的订单,也不扣费。
POST /api/v2/mv/videos/{id}/cancel(需要task:cancel):queued的视频立即取消;generating/delivering的视频要等生成侧确认停止后才算取消。无法确认或视频已完成时返回 409, 视频继续并照常扣费。取消成功的返回中refundedCredits为将退还的积分,入账以/charges为准。DELETE /api/v2/mv/videos/{id}:只能删除completed/failed/cancelled的视频,会删除存储文件, 账务记录保留;仍在制作中返回 409video_in_progress。在开始生成前就取消的视频没有存储文件,删除会成功并返回assetsDeleted: 0。GET /api/v2/mv/videos:按时间倒序列出你的视频,用nextCursor作为cursor翻页,limit为 1–50。
中文字幕与歌词
Section titled “中文字幕与歌词”captions.language: "zh"表示中文。字幕文字在提供source.lyrics时以歌词为准,简体或繁体跟随你提供的 歌词;需要繁体字幕请提供繁体歌词。- 未提供歌词时,字幕来自语音识别,属于机器估计,可能有错字,视频会带
MV_SUBTITLE_TEXT_REVIEW_REQUIRED等警告。需要准确的字幕,请提供歌词或已校对的 SRT(captions.mode: "provided")。 - 歌词每行一句,不要加
[主歌]、[Verse]之类的段落标签。 - 没有可用歌词时,
story模式会带MV_CREATIVE_PLANNING_WITHOUT_LYRICS警告,故事主要来自 brief 和音乐。
从 OneClick 迁移
Section titled “从 OneClick 迁移”先用 POST /api/v2/mv/migrations/v1-check 提交你现有的 /api/v1/mv 请求体(免费、不下载媒体),
它会返回对应的 Omn spec、每个字段的映射、阻断原因以及两边的价格。
| OneClick | Omn |
|---|---|
resolution 省略或 540p | 480p(像素少于 540p:832×480 对 960×540),9 积分/秒 |
720p | 768p,12 积分/秒 |
1080p | 1080p(由 768p AI 超分),20 积分/秒,请比较两边报价 |
lipSync: true + characterImage | sing,以该人物演唱 |
| 不开口型 | auto;lyrics_story / prompt_story → story;mood_visual → mood |
prompt / generation.style | creative.brief / creative.style |
referenceImages 第 1–3 / 4–6 张 | references.styles / references.locations(超过 6 张会阻断) |
generation.quality: "high"、双人演唱、舞蹈或乐器表演、动作参考视频、Studio、上传音频 | 不支持,继续使用 OneClick |
注意:OneClick 合同折扣不适用于 Omn;Omn 视频暂不支持单镜编辑、重新合成和升级,需要后续编辑的视频请继续用 OneClick。
SDK 与工具
Section titled “SDK 与工具”- TypeScript / Python SDK 0.7.1:见 TypeScript SDK 和 Python SDK,两页末尾都有 Omn 完整示例。
- Postman 集合的
MV Omn文件夹:报价后自动把price.credits作为购买的maxCredits。
| 英文 | 中文 | 说明 |
|---|---|---|
| quote | 报价 | 免费,固定价格约 10 分钟 |
| spec | 视频规格 | 一次请求的完整描述 |
| Idempotency-Key | 幂等键 | 防止重复扣费 |
| maxCredits | 扣费上限 | 价格高于此值时不扣费并返回 402 |
| performer | 演唱者 / 主角 | references.performer |
| captions | 字幕 | 烧录在画面中 |
| effective seconds | 有效秒数 | 计费时长,向上取整 |
| AI-upscaled | AI 超分 | 1080p / 1440p 由 768p 放大 |
| refund settlement | 退款入账 | 以 /charges 的 settlementStatus 为准 |