跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

Mirelo SFX 2.0 API

POST Base URL: https://api.hiapi.ai /v1/tasks

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 mirelo-sfx-2.0
类型 音频生成（text-to-audio）
接口 POST /v1/tasks
价格 见 HiAPI 定价

Mirelo SFX 2.0 文生音效：用文字描述声音的来源、材质、动作、距离与环境，生成 1–30 秒的 WAV 音效，适合视频拟音、游戏音效和短视频声音设计。

生产建议

生产环境建议
  • 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
  • GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
  • callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

视频拟音

给剪辑补上缺失的撞击、开关、脚步或环境声，按镜头长度生成 1–5 秒的短音效。

promptduration
游戏音效

为按钮、拾取、技能、门和机关生成可复用的短音效，也可以生成环境底噪。

promptduration
短视频与播客

用一句描述补上转场、强调或环境层，不必为一次性的声音翻素材库。

promptduration

请求参数

model string 必填

固定填 mirelo-sfx-2.0。

示例 mirelo-sfx-2.0
input object 必填

业务参数对象；Mirelo SFX 2.0 的输入都放在这里。

prompt string 必填

声音描述，最多 2,000 个字符：写清声源、材质、动作、距离与环境，再补上起音和尾音。例如「铁锤敲击钢梁，空旷仓库，近距离，尖锐起音与长金属余响」。

duration integer 可选

生成音效的时长，1–30 的整数秒，省略时按 5 秒生成。时长越长，生成费用越高；建议先用 1–5 秒试听音色。

默认 5
callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

钢梁铁锤敲击（黄金示例）

1 秒近距离铁锤敲击钢梁，写出声源、材质、空间和尾音；本页请求示例、模型页案例与在线试用使用同一条请求。

请求体
{
  "model": "mirelo-sfx-2.0",
  "input": {
    "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
    "duration": 1
  }
}

获取结果

  1. 提交成功后立即返回 taskId（不等待生成完成）。
  2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后，从返回的 output 中找到 type=audio 的条目，通过 url 下载生成的音频。
  4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

Mirelo SFX 2.0 是什么模型？

Mirelo SFX 2.0 是文生音效模型：用一段文字描述声音的来源、材质、动作、距离与环境，生成 1–30 秒的 WAV 音效。它不生成歌曲、人声或对白。

提示词应该怎么写？

按「声源 → 材质 → 动作 → 距离与空间 → 环境 → 起音和尾音」的顺序写。例如「铁锤敲击钢梁，空旷仓库，近距离，尖锐起音与长金属余响」比只写「敲击声」更容易得到可用结果。

时长怎么控制？

用 duration 指定 1–30 的整数秒，省略时按 5 秒生成。时长越长，生成费用越高；建议先用 1–5 秒试听音色，确认后再生成更长的版本。

输出格式是什么？

每次请求输出一条 WAV 音频。首版不提供其他格式，也不支持一次请求生成多条音效；需要多个版本时，分别提交请求或调整提示词后再生成。

如何计费？

按输出音频的秒数计费，时长由请求里的 duration 决定。失败任务会退回扣费；实时单价以价格页为准。 查看价格页

如何通过 API 调用？

向 POST /v1/tasks 发送异步任务，model 填 mirelo-sfx-2.0，input 里传 prompt，按需传 duration。接口立即返回 taskId；可以用 callback.url 接收结果，或轮询 GET /v1/tasks/:id。

下一步