Mirelo SFX 2.0 API 怎么用

TL;DR

它是什么：文生音效模型，一段描述换一条 1–30 秒的 WAV（PCM 16-bit / 48 kHz / 单声道）。打开 Mirelo SFX 2.0 模型页写一句话就能试听。Mirelo SFX 2.0 已在 HiAPI 上线，新用户注册送 200 积分。
多少钱：按输出秒数计费，每秒 $0.0215（43 积分），1 秒起；一条 5 秒 $0.1075，30 秒 $0.645。
最快怎么调：模型页填描述、选时长、提交；接进产品就走 POST /v1/tasks，model 填 mirelo-sfx-2.0，input 里只有 prompt 和 duration。

Mirelo SFX 2.0 是什么

输入只有两个字段：prompt 和 duration。描述 1–2,000 字符，写清声源、材质、动作、距离与环境，再补起音和尾音；duration 是 1–30 的整数秒，默认 5。输出固定是一条 WAV，PCM 16-bit、48 kHz、单声道，没有格式选项。

它只做单条音效和环境声：一次请求一个声音事件，不生成歌曲、人声或对白。剪辑要补一个撞击点、游戏要一条 UI 反馈音、短视频要一段雨夜底噪，都是它的活。

站内这条锤击交付 1 秒，$0.0215，试听 WAV。瞬态和金属余响都装在这一秒里：

A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.

用这个提示词生成 → 链接只预填描述，打开后把 duration 设为 1 秒才是这条。

在线试用：4 步听到第一条

打开 Mirelo SFX 2.0 模型页，注册会拿到 200 积分。
在描述框里粘上面那条锤击描述，或者换成你自己要的声音。
把 duration 设成 1–3 秒，先听起音和尾音。
点提交，播放器里出来的就是 WAV，可以直接下载。

第 3 步别跳过。同样的描述在 1 秒和 10 秒下是两种东西，先短后长省的是重复生成的钱。

API 接入：4 步跑通

在控制台创建 API Key。
POST https://api.hiapi.ai/v1/tasks，model 写 mirelo-sfx-2.0，input 里放 prompt 和 duration。
拿到返回的 taskId，等 callback 通知，或轮询 GET /v1/tasks/{taskId}。
status 变成 success 后，从 output 里取 type 为 audio 的条目，用它的 url 下载 WAV。

可运行的 curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
    }
  }'

返回里的任务 ID 在 data.taskId：

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

拿这个 ID 查状态：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status 会经过 queued、handling、success 或 fail。成功时从 data.output 里找 type 为 audio 的那一项。

Python 版：创建、轮询、下载一次写完

import requests
import time

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "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,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    audio_url = next(item["url"] for item in data["output"] if item["type"] == "audio")
    with open("effect.wav", "wb") as f:
        f.write(requests.get(audio_url, timeout=60).content)
    print("saved effect.wav")
else:
    print(data.get("error"))

音效任务比视频短得多，轮询间隔 2 秒就够，不用等满 3 秒。

描述怎么写：五个要素

没有额外参数，prompt 就是全部的控制面。按这五样写，一条到位：

要素	写什么	案例里的对应句
声源	什么东西在发声	a heavy hammer strike
材质	发声体的材料	on a steel beam
动作	怎么发声、力度如何	single, heavy
距离与环境	听众在哪、空间多大	in a large empty warehouse, close perspective
起音与尾音	开头多快、结尾多长	sharp transient, long metallic ring

把握不住的维度就省掉，别写「大概」「电影感」这类形容词——描述里每一个具体名词都会落到声音上。「no music and no voices」这种收尾句值得留一句，它一次把不想要的层排除掉。

时长怎么选

先用 1–3 秒确认音色、起音和尾音对不对，定稿再把 duration 拉到目标长度。同一个描述在 3 秒和 10 秒下，事件的密度会不一样，短版试探方向、长版取成品，比直接跑 30 秒便宜得多。

撞击、UI、点按 → 1–3 秒。
环境声、底噪、房间氛围 → 10–30 秒。
要卡镜头长度 → 直接按镜头秒数取整填写，模型按你给的秒数交付。

上线前注意 4 件事

回调加轮询兜底。 请求体加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务进终态会通知你；通知可能丢，再配一个定时 GET /v1/tasks/{taskId} 补偿。
按 taskId 幂等。 success 和 fail 都是终态，同一个 taskId 可能收到多次通知，处理前先查库去重。
产物链接会过期。 output 里的 url 是临时地址，拿到就转存到自己的存储，别把它当长期 CDN 用。
一条描述只讲一个事件。 撞击加碎片落地、雨声加雷声再加狗叫，拆成多条请求分别生成，后期再叠，比塞进一句话可控。