Skip to content

    Music Video

    Omn 音乐视频对接指南(中文)

    Availability varies by operationOpen App ↗

    本页是 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 秒。
    方式适合改动
    /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 秒视频
    480p9540
    768p(默认)12720
    1080p(AI 超分)201,200
    1440p / 2K(AI 超分)482,880

    实际金额以报价返回的 price.credits 为准。

    1. 报价(免费):POST /api/v2/mv/quotes,提交 spec。服务会下载并校验音频和图片、 测量真实时长,返回价格和过期时间(约 10 分钟)。请求有任何改动都要重新报价。
    2. 购买:POST /api/v2/mv/videos,body 为 { "quoteId": "...", "maxCredits": 报价金额 }, 请求头带 Idempotency-Key。也可以直接提交 { "spec": {...}, "maxCredits": ... } 一步完成。
    3. 等待:轮询、订阅进度流或接收 webhook(见下文)。
    4. 下载:状态为 completed 后读取 GET /api/v2/mv/videos/{id}/file,用返回的签名链接下载 MP4。
    Terminal window
    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" }
    }
    JSON
    curl -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
    # 只生成一次幂等键并保存;重试时复用同一个键和同一个 body
    uuidgen > mv-key.txt
    jq '{quoteId: .id, maxCredits: .price.credits}' quote.json > mv-buy.json
    curl -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 相同,从购买起不会改变,保存任意一个即可。

    字段说明
    source.typeaudio_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.modeauto(默认,Omn 自行决定方向和是否出现人物,不演唱)、sing(参考人物演唱原曲,口型同步)、story(叙事)、mood(氛围画面)
    creative.brief可选,≤ 3,000 字:画面内容、场景、人物、事件
    creative.style可选,≤ 1,000 字:视觉风格、色调、镜头感
    creative.storySourcestory 模式必填:lyrics(讲歌词的故事)或 brief(讲 brief 的故事,此时 brief 必填);其他模式不能填
    creative.peopleauto(默认)或 none(画面不出现人物,不能与 sing 或 references.performer 同时使用)
    references.performer{ imageUrl, description? },一张人物图(PNG/JPEG/WebP,≤ 10 MB)。sing 必填,是演唱者;其他模式作为主角
    references.styles / references.locations各最多 3 张图片 URL(≤ 12 MB),分别指定风格和场景
    output.resolution480p、768p(默认)、1080p、1440p(2K 的 API 值是 1440p,不接受 2K)
    output.aspectRatio21:9、16:9(默认)、3:2、4:3、5:4、1:1、4:5、3:4、2:3、9:16、9:21
    captions.modeoff(默认)、auto(根据音频自动对时)、provided(使用你的 SRT,配 srtUrl,≤ 4 MB,时间相对于所选片段)
    captions.languageauto、en、zh
    captions.requiredtrue 时字幕失败则整单失败(退款),而不是交付无字幕视频

    未知字段(包括 engineVersion 之类的引擎选择字段)会返回 400,不会被静默忽略。

    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 的视频,会删除存储文件, 账务记录保留;仍在制作中返回 409 video_in_progress。在开始生成前就取消的视频没有存储文件,删除会成功并返回 assetsDeleted: 0。
    • GET /api/v2/mv/videos:按时间倒序列出你的视频,用 nextCursor 作为 cursor 翻页,limit 为 1–50。
    • captions.language: "zh" 表示中文。字幕文字在提供 source.lyrics 时以歌词为准,简体或繁体跟随你提供的 歌词;需要繁体字幕请提供繁体歌词。
    • 未提供歌词时,字幕来自语音识别,属于机器估计,可能有错字,视频会带 MV_SUBTITLE_TEXT_REVIEW_REQUIRED 等警告。需要准确的字幕,请提供歌词或已校对的 SRT(captions.mode: "provided")。
    • 歌词每行一句,不要加 [主歌]、[Verse] 之类的段落标签。
    • 没有可用歌词时,story 模式会带 MV_CREATIVE_PLANNING_WITHOUT_LYRICS 警告,故事主要来自 brief 和音乐。

    先用 POST /api/v2/mv/migrations/v1-check 提交你现有的 /api/v1/mv 请求体(免费、不下载媒体), 它会返回对应的 Omn spec、每个字段的映射、阻断原因以及两边的价格。

    OneClickOmn
    resolution 省略或 540p480p(像素少于 540p:832×480 对 960×540),9 积分/秒
    720p768p,12 积分/秒
    1080p1080p(由 768p AI 超分),20 积分/秒,请比较两边报价
    lipSync: true + characterImagesing,以该人物演唱
    不开口型auto;lyrics_story / prompt_story → story;mood_visual → mood
    prompt / generation.stylecreative.brief / creative.style
    referenceImages 第 1–3 / 4–6 张references.styles / references.locations(超过 6 张会阻断)
    generation.quality: "high"、双人演唱、舞蹈或乐器表演、动作参考视频、Studio、上传音频不支持,继续使用 OneClick

    注意:OneClick 合同折扣不适用于 Omn;Omn 视频暂不支持单镜编辑、重新合成和升级,需要后续编辑的视频请继续用 OneClick。

    • 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-upscaledAI 超分1080p / 1440p 由 768p 放大
    refund settlement退款入账以 /charges 的 settlementStatus 为准