异步回调

当任务耗时较长或不希望客户端阻塞等待时，传入 async=true 和 webhook_url 创建异步任务并接收终态回调。

异步回调不是某一个业务接口，而是「任意 /v1 音频任务接口 + async=true + webhook_url」的调用模式。下面以单人语音 POST /v1/audio/speech 为例演示，其他任务接口同理。

适用范围

1. 创建 API Key

   进入 API Key 管理平台，创建 API Key，并保存为环境变量。不要把 API Key 写进客户端代码或提交到仓库。

   export MOSS_API_KEY="<your-api-key>"
   

2. 准备回调接收端

   准备一个公网可访问的 HTTPS 接口，用来接收任务终态的 POST JSON 回调。

3. 发起带 async 的请求

   在任意任务接口的请求体中加入 async=true 和 webhook_url。接口立即返回任务对象，任务转入异步处理，不阻塞客户端。

   {
     "model": "moss-tts",
     "input": "这是一段异步生成的语音。",
     "voice_id": "<voice_id>",
     "async": true,
     "webhook_url": "https://example.com/webhook"
   }
   

   curl https://api.mosi.cn/v1/audio/speech \
     -H "Authorization: Bearer $MOSS_API_KEY" \
     -H "Content-Type: application/json" \
     -d @request.json
   

4. 接收终态回调

   任务到达终态后，MOSI 会向 webhook_url 发起一次 POST JSON 回调。回调请求体是精简的任务终态通知对象（TaskID / TenantID / Status / CallbackURL），不包含完整任务结果；如需结果 URL 等字段，用回调里的 TaskID 调用任务查询接口获取。字段说明见回调安全规则。

5. 主动查询兜底

   如果错过回调，可用服务端返回的 task_id 主动查询：通用音频任务用 GET /v1/audio/tasks/{task_id}，转写任务用 GET /v1/audio/transcriptions/{task_id}。

下一步